> For the complete documentation index, see [llms.txt](https://docs.grandprotocol.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.grandprotocol.org/protocols/x402.md). # x402 x402 is an open payment protocol developed by Coinbase that uses the HTTP 402 status code to embed blockchain payments directly in HTTP request/response cycles. Grand Protocol supports x402 natively and uses it as the default protocol when a service supports both x402 and MPP. *** ## Background The HTTP 402 status code ("Payment Required") was reserved in the original HTTP specification in 1997 but was never formally standardized. x402 gives it a real implementation: when a server responds with 402, it includes a structured payment requirement, and the client fulfills it on-chain before retrying the request. *** ## How x402 works The x402 flow has three parties: the **client** (your agent), the **resource server** (the API you are paying), and the **facilitator** (routes and verifies on-chain settlement). ``` 1. Agent sends request to resource server GET https://api.service.com/data 2. Server responds with 402 + payment requirements HTTP/1.1 402 Payment Required Content-Type: application/json { "scheme": "exact", "network": "robinhood-mainnet", "token": "", // USDC on Robinhood Chain "amount": "2000", // 0.002 USDC (6 decimal places) "payTo": "0x9bC4...a2B4", "resource": "https://api.service.com/data" } 3. Grand Protocol constructs and signs a PaymentPayload { "scheme": "exact", "network": "robinhood-mainnet", "payload": { "from": "", "to": "0x9bC4...a2B4", "amount": "2000", "token": "", "nonce": "01j9x4k2m3n5p6q7" }, "signature": "" } 4. Agent retransmits original request with payment header GET https://api.service.com/data X-PAYMENT: X-PAYMENT-SIGNATURE: 5. Server verifies payment via facilitator and returns data HTTP/1.1 200 OK ...response body... ``` Settlement on Robinhood Chain confirms within a 100ms block. The chain then settles to Ethereum for final security. *** ## Key properties | Property | Value | | ---------------- | ------------------------------------------------------------------------------- | | Settlement layer | Robinhood Chain (Grand Protocol default); x402 also supports other EVM networks | | Settlement token | USDC (primary), USDT | | Protocol fee | None | | KYC required | No | | Account required | No | | Session support | Yes (v2, wallet-based) | | Confirmation | 100ms block time on Robinhood Chain | *** ## x402 on Robinhood Chain Robinhood Chain is an Ethereum Layer 2 built on the Arbitrum stack, which makes it a natural fit for x402: * x402 was designed EVM-first, so the standard `exact` scheme, EIP-712 payment authorizations, and existing facilitator tooling work unchanged * 100ms block time, so a payment confirms before the retried request completes * Settles to Ethereum for security, with ETH as the gas token Grand Protocol uses Robinhood Chain as the default x402 settlement network. USDC is transferred as an ERC-20 token. Every transaction is publicly visible on the Robinhood Chain explorer. *** ## x402 sessions x402 v2 introduced session support, allowing a wallet to pre-authorize a spending allowance for a service. This eliminates per-request overhead for high-frequency calls to the same endpoint. Grand Protocol manages x402 sessions automatically. When a session is established with a service, subsequent calls reuse it without renegotiating the full payment handshake. *** ## How Grand Protocol handles x402 When `POST /v1/pay` is called: 1. Grand Protocol sends the original request to the target endpoint 2. If the response is 402, Grand Protocol reads the `PaymentRequired` object 3. The spend policy is checked against the required amount and domain 4. If the policy passes, Grand Protocol constructs a signed `PaymentPayload` using the agent's wallet signing key 5. The original request is retransmitted with the `X-PAYMENT` and `X-PAYMENT-SIGNATURE` headers 6. The server verifies the payment via the x402 facilitator and returns the response 7. Grand Protocol records the transaction to the on-chain ledger The caller sends `POST /v1/pay` and receives the API response. The x402 handshake is invisible. *** ## Accepting x402 payments (server side) If you want your own API to accept x402 payments from agents, your server must return a `402 Payment Required` response when the `X-PAYMENT` header is absent. The response body must follow the x402 `PaymentRequired` schema: ``` HTTP/1.1 402 Payment Required Content-Type: application/json { "accepts": [{ "scheme": "exact", "network": "robinhood-mainnet", "maxAmountRequired": "2000", "resource": "/api/data", "description": "API access", "mimeType": "application/json", "payToAddress": "", "requiredDeadlineSeconds": 60, "asset": "", "extra": { "name": "USDC", "version": "1" } }] } ``` When the client retransmits the request with a valid `X-PAYMENT` header, verify the payment proof against the x402 facilitator before serving the response. Payments are confirmed on Robinhood Chain within a 100ms block. *** ## Further reading * [x402 specification](https://x402.org) * [MPP protocol](/protocols/mpp.md) — the alternative agent payment protocol * [Payment Router](/features/payment-router.md) — how Grand Protocol chooses between x402 and MPP --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.grandprotocol.org/protocols/x402.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.