x402: pay an invoice
An invoice’s x402Url, for AI agents and other x402 clients. Without payment it answers 402 Payment Required: the PAYMENT-REQUIRED header (base64 JSON, x402 v2) lists the price in each accepted stablecoin, USDC and EURC on Base, each to the invoice’s own address. Retry the same request with a signed PAYMENT-SIGNATURE; Cryptonly relays the transfer and pays the gas. 200 means the transfer is on chain, 202 that it was sent but not yet mined. The invoice becomes paid once the deposit is confirmed, as with any payment: use its status or the invoice.statusChanged webhook, never the HTTP status alone. A browser is redirected to the payment page.
No API key required.
Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The token in the invoice’s x402Url.
Header Parameters
Section titled “Header Parameters”Base64 x402 v2 PaymentPayload signed for one of the accepts entries.
Responses
Section titled “Responses”The transfer is on chain (PAYMENT-RESPONSE has it), or the invoice was already paid.
object
Set on 404, 409, 410 and 503.
object
Atomic units.
Set once the invoice is paid.
Example
{ "error": "invoice_expired", "status": "created", "payment": { "status": "pending", "network": "eip155:8453" }}The transfer was sent and is not mined yet, or a payment is being confirmed. Do not pay again.
object
Set on 404, 409, 410 and 503.
object
Atomic units.
Set once the invoice is paid.
Example
{ "error": "invoice_expired", "status": "created", "payment": { "status": "pending", "network": "eip155:8453" }}A browser: redirected to the hosted payment page.
Request validation failed (e.g. missing or malformed body / query).
object
Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.
Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.
Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.
object
Example
{ "code": "exceptions.auth.invalidApiKey", "message": "Invalid or missing API key"}Payment required. PAYMENT-REQUIRED (base64) holds what the body shows. After a refused payment, error and PAYMENT-RESPONSE say why; nothing was paid.
object
payment_required, or why the last payment was refused (an x402 reason code).
object
The invoice’s x402Url.
The merchant’s public name.
One entry per stablecoin, the one pegged to the invoice currency first.
object
CAIP-2 network.
Atomic units of asset.
Token contract.
The invoice’s address on this network.
The token’s EIP-712 name and version.
object
payment-identifier: send an id (16-128 of [A-Za-z0-9_-]) to make retries idempotent.
object
Example
{ "x402Version": 2, "error": "payment_required", "resource": { "description": "Invoice INV-11: 49.99 USD", "mimeType": "application/json" }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "49990000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 300 } ]}Unknown invoice, or x402 is off for it.
object
Set on 404, 409, 410 and 503.
Example
{ "error": "invoice_expired", "status": "created"}Another payment attempt holds the invoice (Retry-After says until when).
object
Set on 404, 409, 410 and 503.
Example
{ "error": "invoice_expired", "status": "created"}The invoice can no longer be paid: invoice_expired, invoice_cancelled, invoice_partially_paid, invoice_failed or invoice_suspended.
object
Set on 404, 409, 410 and 503.
Example
{ "error": "invoice_expired", "status": "created"}Rate limit exceeded for this endpoint. Retry after the window resets. Code: exceptions.rateLimit.exceeded. The extension.msBeforeNext field tells you how long to wait.
object
Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.
Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.
Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.
object
Example
{ "code": "exceptions.auth.invalidApiKey", "message": "Invalid or missing API key"}Unexpected server error. Safe to retry idempotent operations after a backoff.
object
Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.
Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.
Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.
object
Example
{ "code": "exceptions.auth.invalidApiKey", "message": "Invalid or missing API key"}X402 payments are temporarily unavailable (Retry-After).
object
Set on 404, 409, 410 and 503.
Example
{ "error": "invoice_expired", "status": "created"}