> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/x402.md).

# X402

Accept x402 agent payments

## Build x402 payment requirements

> Build the payment requirements to return to a paying agent.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/requirements":{"post":{"description":"Build the payment requirements to return to a paying agent.","operationId":"X402V2Controller_requirements","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildX402RequirementsDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402RequirementsResponseDto"}}}},"400":{"description":"Invalid input"}},"summary":"Build x402 payment requirements","tags":["x402"]}}},"components":{"schemas":{"BuildX402RequirementsDto":{"type":"object","properties":{"chain":{"type":"string","enum":["base","arbitrum","bsc","solana"]},"asset":{"type":"string","enum":["USDC","USDT"],"description":"Friendly symbol; resolved to the contract/mint"},"amount":{"type":"string","description":"Human units; converted to atomic maxAmountRequired"},"payTo":{"type":"string","description":"Destination address. Defaults to your deposit address for the chain when omitted."},"resource":{"type":"string","description":"The protected resource URL","maxLength":500},"description":{"type":"string","maxLength":255},"mimeType":{"type":"string","maxLength":255},"maxTimeoutSeconds":{"type":"number"}},"required":["chain","asset","amount"]},"X402RequirementsResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/X402RequirementsResult"}},"required":["success","message","data"]},"X402RequirementsResult":{"type":"object","properties":{"x402Version":{"type":"number"},"chain":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string"},"accepts":{"type":"array","items":{"$ref":"#/components/schemas/X402RequirementsAcceptDto"}}},"required":["x402Version","chain","asset","amount","accepts"]},"X402RequirementsAcceptDto":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"maxAmountRequired":{"type":"string"},"resource":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"number"},"asset":{"type":"string"},"extra":{"type":"object"}},"required":["scheme","network","maxAmountRequired","resource","description","mimeType","payTo","maxTimeoutSeconds","asset","extra"]}}}}
```

## Verify an x402 payment

> Validate a signed payment against its requirements without settling.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/verify":{"post":{"description":"Validate a signed payment against its requirements without settling.","operationId":"X402V2Controller_verify","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402FacilitatorRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402VerifyResponseDto"}}}},"400":{"description":"Invalid input"}},"summary":"Verify an x402 payment","tags":["x402"]}}},"components":{"schemas":{"X402FacilitatorRequestDto":{"type":"object","properties":{"x402Version":{"type":"number"},"paymentPayload":{"$ref":"#/components/schemas/X402PaymentPayloadDto"},"paymentRequirements":{"$ref":"#/components/schemas/X402PaymentRequirementsDto"}},"required":["x402Version","paymentPayload","paymentRequirements"]},"X402PaymentPayloadDto":{"type":"object","properties":{"x402Version":{"type":"number"},"scheme":{"type":"string"},"network":{"type":"string","description":"CAIP-2 network id"},"payload":{"$ref":"#/components/schemas/X402PaymentPayloadInnerDto"}},"required":["x402Version","scheme","network","payload"]},"X402PaymentPayloadInnerDto":{"type":"object","properties":{"signature":{"type":"string","description":"[evm] EIP-712 signature"},"authorization":{"description":"[evm] signed authorization","allOf":[{"$ref":"#/components/schemas/X402AuthorizationDto"}]},"transaction":{"type":"string","description":"[solana] base64 partially-signed transaction"},"payer":{"type":"string","description":"[solana] payer public key"}}},"X402AuthorizationDto":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"value":{"type":"string","description":"Atomic units"},"validAfter":{"type":"string"},"validBefore":{"type":"string"},"nonce":{"type":"string","description":"EIP-3009 32-byte hex nonce or Permit2 numeric nonce"},"deadline":{"type":"string","description":"Permit2 deadline (unix seconds)"}},"required":["from","to","value"]},"X402PaymentRequirementsDto":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"maxAmountRequired":{"type":"string","description":"Atomic units; exact amount for the exact scheme"},"resource":{"type":"string","maxLength":500},"description":{"type":"string","maxLength":255},"mimeType":{"type":"string","maxLength":255},"payTo":{"type":"string","description":"Destination address"},"maxTimeoutSeconds":{"type":"number"},"asset":{"type":"string","description":"Token contract (EVM) / mint (Solana)"},"extra":{"type":"object","description":"EVM EIP-712 domain { name, version } or Solana { feePayer }"}},"required":["scheme","network","maxAmountRequired","payTo","asset"]},"X402VerifyResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/X402VerifyResult"}},"required":["success","message","data"]},"X402VerifyResult":{"type":"object","properties":{"isValid":{"type":"boolean"},"invalidReason":{"type":"string","nullable":true},"payer":{"type":"string","nullable":true},"chain":{"type":"string"},"asset":{"type":"string"},"payTo":{"type":"string"},"amount":{"type":"string"},"checks":{"type":"object"}},"required":["isValid","invalidReason","payer","chain","asset","payTo","amount","checks"]}}}}
```

## Settle an x402 payment

> Submit a signed payment on-chain and return the settlement receipt.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/settle":{"post":{"description":"Submit a signed payment on-chain and return the settlement receipt.","operationId":"X402V2Controller_settle","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402FacilitatorRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402SettleResponseDto"}}}},"400":{"description":"Invalid input"}},"summary":"Settle an x402 payment","tags":["x402"]}}},"components":{"schemas":{"X402FacilitatorRequestDto":{"type":"object","properties":{"x402Version":{"type":"number"},"paymentPayload":{"$ref":"#/components/schemas/X402PaymentPayloadDto"},"paymentRequirements":{"$ref":"#/components/schemas/X402PaymentRequirementsDto"}},"required":["x402Version","paymentPayload","paymentRequirements"]},"X402PaymentPayloadDto":{"type":"object","properties":{"x402Version":{"type":"number"},"scheme":{"type":"string"},"network":{"type":"string","description":"CAIP-2 network id"},"payload":{"$ref":"#/components/schemas/X402PaymentPayloadInnerDto"}},"required":["x402Version","scheme","network","payload"]},"X402PaymentPayloadInnerDto":{"type":"object","properties":{"signature":{"type":"string","description":"[evm] EIP-712 signature"},"authorization":{"description":"[evm] signed authorization","allOf":[{"$ref":"#/components/schemas/X402AuthorizationDto"}]},"transaction":{"type":"string","description":"[solana] base64 partially-signed transaction"},"payer":{"type":"string","description":"[solana] payer public key"}}},"X402AuthorizationDto":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"value":{"type":"string","description":"Atomic units"},"validAfter":{"type":"string"},"validBefore":{"type":"string"},"nonce":{"type":"string","description":"EIP-3009 32-byte hex nonce or Permit2 numeric nonce"},"deadline":{"type":"string","description":"Permit2 deadline (unix seconds)"}},"required":["from","to","value"]},"X402PaymentRequirementsDto":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"maxAmountRequired":{"type":"string","description":"Atomic units; exact amount for the exact scheme"},"resource":{"type":"string","maxLength":500},"description":{"type":"string","maxLength":255},"mimeType":{"type":"string","maxLength":255},"payTo":{"type":"string","description":"Destination address"},"maxTimeoutSeconds":{"type":"number"},"asset":{"type":"string","description":"Token contract (EVM) / mint (Solana)"},"extra":{"type":"object","description":"EVM EIP-712 domain { name, version } or Solana { feePayer }"}},"required":["scheme","network","maxAmountRequired","payTo","asset"]},"X402SettleResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/X402TransactionDto"}},"required":["success","message","data"]},"X402TransactionDto":{"type":"object","properties":{"id":{"type":"string"},"txHash":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"amlCheck":{"type":"string","enum":["passed","pending","failed"]},"errorReason":{"type":"string","nullable":true},"network":{"type":"string","description":"CAIP-2 network id"},"chain":{"type":"string"},"asset":{"type":"string"},"resource":{"type":"string","nullable":true,"description":"The protected resource the agent paid to access"},"description":{"type":"string","nullable":true,"description":"Human description of the paid resource"},"payer":{"type":"string","description":"Paying agent wallet"},"payTo":{"type":"string","description":"Destination address"},"amount":{"type":"string"},"fee":{"type":"string","description":"CoinCircuit facilitator fee charged for this settlement"},"blockNumber":{"type":"number","nullable":true},"explorerUrl":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"}},"required":["id","txHash","status","amlCheck","errorReason","network","chain","asset","resource","description","payer","payTo","amount","fee","blockNumber","explorerUrl","createdAt"]}}}}
```

## GET /api/v1/x402/supported

> List supported x402 networks and assets

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/supported":{"get":{"operationId":"X402V2Controller_supported","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402SupportedResponseDto"}}}}},"summary":"List supported x402 networks and assets","tags":["x402"]}}},"components":{"schemas":{"X402SupportedResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/X402SupportedResult"}},"required":["success","message","data"]},"X402SupportedResult":{"type":"object","properties":{"kinds":{"type":"array","items":{"$ref":"#/components/schemas/X402SupportedKind"}}},"required":["kinds"]},"X402SupportedKind":{"type":"object","properties":{"x402Version":{"type":"number"},"scheme":{"type":"string"},"network":{"type":"string"},"chain":{"type":"string"},"assets":{"type":"array","items":{"type":"string"}},"extra":{"type":"object"}},"required":["x402Version","scheme","network","chain","assets"]}}}}
```

## List x402 transactions

> List settled x402 payments for your account, newest first.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/transactions":{"get":{"description":"List settled x402 payments for your account, newest first.","operationId":"X402V2Controller_transactions","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by transaction hash or address","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["pending","confirmed"]}},{"name":"chain","required":false,"in":"query","schema":{"type":"string","enum":["base","arbitrum","bsc","solana"]}},{"name":"asset","required":false,"in":"query","schema":{"type":"string","enum":["USDC","USDT"]}},{"name":"startDate","required":false,"in":"query","description":"Created from this date/time (ISO 8601)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Created up to this date/time (ISO 8601)","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402TransactionsResponseDto"}}}}},"summary":"List x402 transactions","tags":["x402"]}}},"components":{"schemas":{"X402TransactionsResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/X402TransactionDto"}},"meta":{"$ref":"#/components/schemas/PaginationMetaDto"}},"required":["success","message","data","meta"]},"X402TransactionDto":{"type":"object","properties":{"id":{"type":"string"},"txHash":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"amlCheck":{"type":"string","enum":["passed","pending","failed"]},"errorReason":{"type":"string","nullable":true},"network":{"type":"string","description":"CAIP-2 network id"},"chain":{"type":"string"},"asset":{"type":"string"},"resource":{"type":"string","nullable":true,"description":"The protected resource the agent paid to access"},"description":{"type":"string","nullable":true,"description":"Human description of the paid resource"},"payer":{"type":"string","description":"Paying agent wallet"},"payTo":{"type":"string","description":"Destination address"},"amount":{"type":"string"},"fee":{"type":"string","description":"CoinCircuit facilitator fee charged for this settlement"},"blockNumber":{"type":"number","nullable":true},"explorerUrl":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"}},"required":["id","txHash","status","amlCheck","errorReason","network","chain","asset","resource","description","payer","payTo","amount","fee","blockNumber","explorerUrl","createdAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}}
```

## Get an x402 transaction

> Fetch a settled x402 payment by transaction hash.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/transactions/{txHash}":{"get":{"description":"Fetch a settled x402 payment by transaction hash.","operationId":"X402V2Controller_transaction","parameters":[{"name":"txHash","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402TransactionResponseDto"}}}},"404":{"description":"Not found"}},"summary":"Get an x402 transaction","tags":["x402"]}}},"components":{"schemas":{"X402TransactionResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/X402TransactionDto"}},"required":["success","message","data"]},"X402TransactionDto":{"type":"object","properties":{"id":{"type":"string"},"txHash":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"amlCheck":{"type":"string","enum":["passed","pending","failed"]},"errorReason":{"type":"string","nullable":true},"network":{"type":"string","description":"CAIP-2 network id"},"chain":{"type":"string"},"asset":{"type":"string"},"resource":{"type":"string","nullable":true,"description":"The protected resource the agent paid to access"},"description":{"type":"string","nullable":true,"description":"Human description of the paid resource"},"payer":{"type":"string","description":"Paying agent wallet"},"payTo":{"type":"string","description":"Destination address"},"amount":{"type":"string"},"fee":{"type":"string","description":"CoinCircuit facilitator fee charged for this settlement"},"blockNumber":{"type":"number","nullable":true},"explorerUrl":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"}},"required":["id","txHash","status","amlCheck","errorReason","network","chain","asset","resource","description","payer","payTo","amount","fee","blockNumber","explorerUrl","createdAt"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.coincircuit.io/x402.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.