x402 Protocol Reference

This page is a field reference for the x402 v2 messages the Fireblocks facilitator emits and accepts: the 402 body, the HTTP headers, the verify and settle payloads, and the standardized error codes. For how these fit together, see x402 Concepts and Glossary. For calling the endpoints, see Integration.

HTTP headers

Header	Direction	Purpose
`payment-signature`	Request	Base64-encoded signed payment payload, sent by the caller on the retry after a `402`.
`PAYMENT-RESPONSE`	Response	Returned with the `200` after settlement. Carries the settlement result (transaction hash, network, payer).
`X-402-Integrity`	Response	Optional. The Payment Instruction Integrity envelope, mirrored from the `402` body’s `integrity` field.

The `402` body (`PaymentRequired`)

A server returns this JSON with a 402 status. The accepts[] array holds one entry per way to pay; the caller chooses one.

{
  "x402Version": 2,
  "error": "string",                 // Optional - present when describing why payment is required
  "resource": {
    "url": "https://pay.example.com/premium",
    "description": "string",         // Optional
    "mimeType": "application/json"   // Optional
  },
  "accepts": [ /* PaymentRequirements, one per option */ ],
  "extensions": { },                 // Optional - extension data
  "integrity": "base64url…"          // Optional - Payment Instruction Integrity envelope
}

PaymentRequirements

Each entry in accepts[] fully describes one payment option.

{
  "scheme": "exact",                 // 'exact' or 'upto'
  "network": "eip155:8453",          // CAIP-2 network id
  "amount": "10000",                 // base units of the asset (string)
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  // token contract
  "payTo": "0x…",                    // recipient address
  "maxTimeoutSeconds": 300,          // how long the quote is valid to pay
  "extra": {
    "assetTransferMethod": "eip-3009",  // Optional - the transfer mechanism
    "name": "USD Coin",                 // EIP-712 domain name
    "version": "2"                      // EIP-712 domain version
  }
}

The signed payment payload

The caller signs an authorization and sends the payload base64-encoded in the payment-signature header. The shape of the inner authorization depends on the transfer mechanism.

{
  "x402Version": 2,
  "accepted": { /* the PaymentRequirements entry the caller chose */ },
  "payload": {
    "signature": "0x…",
    "authorization": { },          // eip-3009: from, to, value, validAfter, validBefore, nonce
    "permit2Authorization": { },   // permit2 / upto-permit2: permitted, from, spender, nonce, deadline, witness
    "delegation": { }              // erc7710: delegationManager, permissionContext, delegator
  }
}

Exactly one of authorization, permit2Authorization, or delegation is present, matching the chosen mechanism. The facilitator settles all four mechanisms, but the Fireblocks x402 Agent signs only eip-3009 and permit2; it does not produce erc7710 delegation payloads, because Fireblocks cannot sign delegations. See Transfer mechanisms.

Facilitator request and response shapes

The merchant server calls the facilitator with the same body shape for both verify and settle: the signed paymentPayload plus the paymentRequirements it advertised.

// POST /api/payments/verify  and  POST /api/payments/settle
{
  "x402Version": 2,
  "paymentPayload": { /* the signed payload above */ },
  "paymentRequirements": { /* the accepts[] entry */ }
}

Verify response validates the signature off-chain without moving funds:

{ "isValid": true, "payer": "0x…", "invalidReason": null }

Settle response reports the on-chain result:

{
  "success": true,
  "transaction": "0x…",
  "network": "eip155:8453",
  "payer": "0x…",
  "amount": "10000"
}

On failure, success is false and errorReason carries one of the error codes below.

Supported capabilities

GET /api/payments/supported is public and reports what the facilitator accepts:

{
  "kinds": [ { "x402Version": 2, "scheme": "exact", "network": "eip155:8453" } ],
  "extensions": ["…"],
  "signers": { "…": ["…"] }
}

Discovery resource shape

GET /api/discovery/resources lists discoverable products. Each item is a resource an agent can act on:

{
  "resource": "https://pay.example.com/premium",
  "type": "http",
  "x402Version": 2,
  "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "10000", "asset": "0x…" } ],
  "lastUpdated": 1776521334,
  "metadata": { "category": "data", "description": "…", "mimeType": "application/json" }
}

Only fixed-price (native-denomination) rows appear; USD-converted rows are omitted. See Publish to the discovery catalog.

Error codes

The facilitator returns these standardized x402 error codes in invalidReason (verify) or errorReason (settle).

Code	Meaning
`insufficient_funds`	The payer’s balance cannot cover the authorized amount.
`invalid_exact_evm_payload_signature`	The EIP-712 signature did not verify.
`invalid_exact_evm_payload_authorization_valid_before`	The authorization’s `validBefore` has passed (quote expired).
`invalid_exact_evm_payload_authorization_valid_after`	The authorization’s `validAfter` is in the future.
`invalid_exact_evm_payload_authorization_value_mismatch`	The signed value does not match the advertised amount.
`invalid_exact_evm_payload_recipient_mismatch`	The signed recipient does not match `payTo`.
`invalid_payload`	The payment payload is malformed.
`invalid_payment_requirements`	The supplied `paymentRequirements` are invalid.
`invalid_network`	The network is not supported or does not match.
`invalid_scheme`	The scheme is not supported or does not match.
`invalid_transaction_state`	The payment is not in a state that allows this operation.
`unexpected_settle_error`	Settlement failed for an unexpected reason.
`unexpected_verify_error`	Verification failed for an unexpected reason.
`unsupported_scheme`	The resolved mechanism is not offered for this product.
`permit2_allowance_required`	The payer must grant a Permit2 allowance before paying.

Get Started

Workspace & Security

Webhooks

Direct Custody Wallets

Manage Wallets

Embedded Wallets

Transactions

Transaction Fees & Gas Station

Treasury & Trading

Smart Contracts & Tokenization

Assets & NFTs

Compliance

Payments

Offchain Signing

API Co-Signers

Integrations

HTTP headers

The `402` body (`PaymentRequired`)

PaymentRequirements

The signed payment payload

Facilitator request and response shapes

Supported capabilities

Discovery resource shape

Error codes

What to read next

​HTTP headers

​The 402 body (PaymentRequired)

​PaymentRequirements

​The signed payment payload

​Facilitator request and response shapes

​Supported capabilities

​Discovery resource shape

​Error codes

​What to read next

HTTP headers

The `402` body (`PaymentRequired`)

PaymentRequirements

The signed payment payload

Facilitator request and response shapes

Supported capabilities

Discovery resource shape

Error codes

What to read next