> ## Documentation Index > Fetch the complete documentation index at: https://developers.fireblocks.com/llms.txt > Use this file to discover all available pages before exploring further. # x402 Protocol Reference > Reference for x402 v2 on Fireblocks: the 402 PaymentRequired body, the payment headers, facilitator request and response shapes, and the error codes. 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](/docs/x402-concepts). For calling the endpoints, see [Integration](/docs/x402-facilitator-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. ```jsonc theme={"system"} { "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. ```jsonc theme={"system"} { "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. ```jsonc theme={"system"} { "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](/docs/x402-agent) signs only `eip-3009` and `permit2`; it does not produce `erc7710` `delegation` payloads, because Fireblocks cannot sign delegations. See [Transfer mechanisms](/docs/x402-facilitator-integration#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. ```jsonc theme={"system"} // 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: ```json theme={"system"} { "isValid": true, "payer": "0x…", "invalidReason": null } ``` **Settle response** reports the on-chain result: ```json theme={"system"} { "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: ```json theme={"system"} { "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: ```jsonc theme={"system"} { "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](/docs/x402-facilitator-product-catalog#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. | ## What to read next * [Integration](/docs/x402-facilitator-integration) — the endpoints that consume and emit these shapes. * [x402 Troubleshooting and FAQ](/docs/x402-troubleshooting) — what these errors mean in practice and how to resolve them. * [Payment Instruction Integrity](/docs/x402-facilitator-operations#payment-instruction-integrity) — the `integrity` envelope and `X-402-Integrity` header.