Skip to content
CryptonlyCryptonlyCryptonly

x402: verify a payment

POST
/x402/verify

Checks a payment payload against its requirements without broadcasting. Request and response bodies follow the x402 v2 facilitator protocol. Protocol failures are HTTP 200 with isValid: false / success: false and a reason code, so stock x402 clients can read them.

Required scope: x402.verify.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
x402Version
number
Allowed values: 2

Example 

2
paymentPayload
required
object
x402Version
required
number
Allowed values: 2

Example 

2
resource
object
key
additional properties
any
accepted
required

The accepts[] entry the buyer chose.

object
scheme
required

Only exact is supported.

string

Example 

exact
network
required

CAIP-2 network id. Must match this environment (GET /x402/supported).

string

Example 

eip155:84532
amount
required

Price in atomic units of asset (USDC has 6 decimals).

string

Example 

1000
asset
required

ERC-20 contract of a registered asset.

string

Example 

0x036CbD53842c5426634e7929541eC2318f3dCF7e
payTo
required

The merchant’s own address. The asset is transferred here.

string

Example 

0x209693Bc6afc0C5328bA36FaF03C514EF312287C
maxTimeoutSeconds
required
number
>= 1

Example 

60
extra

EIP-712 domain of the token (name, version) and, optionally, assetTransferMethod (eip3009 or permit2).

object
key
additional properties
any

Example 

{
  "name": "USDC",
  "version": "2",
  "assetTransferMethod": "eip3009"
}
payload
required
object
signature
required

65-byte hex.

string

Example 

0x1111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111
authorization
object
from
required
string

Example 

0x857b06519E91e3A54538791bDbb0E22373e36b66
to
required
string

Example 

0x209693Bc6afc0C5328bA36FaF03C514EF312287C
value
required

Atomic units.

string

Example 

1000
validAfter
required

Unix seconds.

string

Example 

0
validBefore
required

Unix seconds.

string

Example 

1790000000
nonce
required

32-byte hex.

string

Example 

0xabababababababababababababababababababababababababababababababab
permit2Authorization
object
permitted
required
object
token
required
string

Example 

0x036CbD53842c5426634e7929541eC2318f3dCF7e
amount
required

Atomic units.

string

Example 

1000
from
required
string

Example 

0x857b06519E91e3A54538791bDbb0E22373e36b66
spender
required

Canonical x402ExactPermit2Proxy.

string

Example 

0x402085c248EeA27D92E8b30b2C58ed07f9E20001
nonce
required

Permit2 nonce, decimal uint256.

string

Example 

1
deadline
required

Unix seconds.

string

Example 

1790000000
witness
required
object
to
required
string

Example 

0x209693Bc6afc0C5328bA36FaF03C514EF312287C
validAfter
required

Unix seconds.

string

Example 

0
extensions
object
key
additional properties
any
paymentRequirements
required

The requirements the seller is enforcing for this request.

object
scheme
required

Only exact is supported.

string

Example 

exact
network
required

CAIP-2 network id. Must match this environment (GET /x402/supported).

string

Example 

eip155:84532
amount
required

Price in atomic units of asset (USDC has 6 decimals).

string

Example 

1000
asset
required

ERC-20 contract of a registered asset.

string

Example 

0x036CbD53842c5426634e7929541eC2318f3dCF7e
payTo
required

The merchant’s own address. The asset is transferred here.

string

Example 

0x209693Bc6afc0C5328bA36FaF03C514EF312287C
maxTimeoutSeconds
required
number
>= 1

Example 

60
extra

EIP-712 domain of the token (name, version) and, optionally, assetTransferMethod (eip3009 or permit2).

object
key
additional properties
any

Example 

{
  "name": "USDC",
  "version": "2",
  "assetTransferMethod": "eip3009"
}

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
isValid
required
boolean
invalidReason

Set when isValid is false.

string
Allowed values: insufficient_funds invalid_exact_evm_payload_authorization_valid_after invalid_exact_evm_payload_authorization_valid_before invalid_exact_evm_payload_authorization_value_mismatch invalid_exact_evm_payload_signature invalid_exact_evm_payload_recipient_mismatch invalid_network invalid_payload invalid_payment_requirements invalid_scheme invalid_x402_version invalid_transaction_state unexpected_verify_error unexpected_settle_error settlement_pending compliance_rejected pay_to_rejected authorization_already_used settlement_disabled gas_ceiling_exceeded gas_budget_exhausted tenant_gas_budget_exhausted fee_payer_reserve_low fee_payer_busy permit2_allowance_required
payer

authorization.from, once the payload parses.

string

Example 

{
  "isValid": true,
  "invalidReason": "insufficient_funds",
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66"
}

400

Section titled “400”

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"
}

401

Section titled “401”

Missing or invalid x-tenant-api-key header. Code: exceptions.auth.invalidApiKey.

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"
}

403

Section titled “403”

Request origin IP is not on the tenant API allowlist (exceptions.auth.ipNotAllowed), or the API key is missing the scope required by this operation (exceptions.auth.insufficientScope).

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"
}

429

Section titled “429”

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"
}

500

Section titled “500”

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"
}