Skip to content

x402: pay an invoice

GET
/x402/invoice/{publicToken}

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.

publicToken
required
string

The token in the invoice’s x402Url.

PAYMENT-SIGNATURE
string

Base64 x402 v2 PaymentPayload signed for one of the accepts entries.

The transfer is on chain (PAYMENT-RESPONSE has it), or the invoice was already paid.

Media typeapplication/json
object
error

Set on 404, 409, 410 and 503.

string
invoiceId
string format: uuid
status
string
Allowed values: created processing paid partially_paid overpaid expired cancelled failed suspended
amount
number
fiatCurrencyCode
string
expiresAt
string
nullable
paymentPageUrl
string
payment
object
status
required
string
Allowed values: pending confirmed
network
required
string
asset
required
string
amount
required

Atomic units.

string
payer
required
string
transaction
required
string
nullable
paidAt

Set once the invoice is paid.

string

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.

Media typeapplication/json
object
error

Set on 404, 409, 410 and 503.

string
invoiceId
string format: uuid
status
string
Allowed values: created processing paid partially_paid overpaid expired cancelled failed suspended
amount
number
fiatCurrencyCode
string
expiresAt
string
nullable
paymentPageUrl
string
payment
object
status
required
string
Allowed values: pending confirmed
network
required
string
asset
required
string
amount
required

Atomic units.

string
payer
required
string
transaction
required
string
nullable
paidAt

Set once the invoice is paid.

string

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).

Media typeapplication/json
object
code
required

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.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

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.

Media typeapplication/json
object
x402Version
required
number
error
required

payment_required, or why the last payment was refused (an x402 reason code).

string
resource
required
object
url
required

The invoice’s x402Url.

string
description
required
string
mimeType
required
string
serviceName

The merchant’s public name.

string
accepts
required

One entry per stablecoin, the one pegged to the invoice currency first.

Array<object>
object
scheme
required
string
network
required

CAIP-2 network.

string
amount
required

Atomic units of asset.

string
asset
required

Token contract.

string
payTo
required

The invoice’s address on this network.

string
maxTimeoutSeconds
required
number
extra
required

The token’s EIP-712 name and version.

object
key
additional properties
any
extensions
required

payment-identifier: send an id (16-128 of [A-Za-z0-9_-]) to make retries idempotent.

object
key
additional properties
any

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.

Media typeapplication/json
object
error

Set on 404, 409, 410 and 503.

string
invoiceId
string format: uuid
status
string
Allowed values: created processing paid partially_paid overpaid expired cancelled failed suspended
amount
number
fiatCurrencyCode
string
expiresAt
string
nullable
paymentPageUrl
string

Example

{
"error": "invoice_expired",
"status": "created"
}

Another payment attempt holds the invoice (Retry-After says until when).

Media typeapplication/json
object
error

Set on 404, 409, 410 and 503.

string
invoiceId
string format: uuid
status
string
Allowed values: created processing paid partially_paid overpaid expired cancelled failed suspended
amount
number
fiatCurrencyCode
string
expiresAt
string
nullable
paymentPageUrl
string

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.

Media typeapplication/json
object
error

Set on 404, 409, 410 and 503.

string
invoiceId
string format: uuid
status
string
Allowed values: created processing paid partially_paid overpaid expired cancelled failed suspended
amount
number
fiatCurrencyCode
string
expiresAt
string
nullable
paymentPageUrl
string

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.

Media typeapplication/json
object
code
required

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.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example

{
"code": "exceptions.auth.invalidApiKey",
"message": "Invalid or missing API key"
}

Unexpected server error. Safe to retry idempotent operations after a backoff.

Media typeapplication/json
object
code
required

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.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example

{
"code": "exceptions.auth.invalidApiKey",
"message": "Invalid or missing API key"
}

X402 payments are temporarily unavailable (Retry-After).

Media typeapplication/json
object
error

Set on 404, 409, 410 and 503.

string
invoiceId
string format: uuid
status
string
Allowed values: created processing paid partially_paid overpaid expired cancelled failed suspended
amount
number
fiatCurrencyCode
string
expiresAt
string
nullable
paymentPageUrl
string

Example

{
"error": "invoice_expired",
"status": "created"
}