> 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","arc","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","arc","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"]}}}}
```
