1. Overview
x402 is an HTTP-based protocol for charging per-request payment in exchange for access to a resource. It uses the unused HTTP status code 402 ("Payment Required") in combination with a small set of standardized headers to negotiate payment between a client and a server.
The protocol is chain-agnostic and currency-agnostic. Servers advertise the chain, currency, and payee they expect; clients sign a payment with their own wallet and resubmit the request.
2. Request flow
On an unpaid request, the server returns 402 with X-Payment-Required, X-Payment-Currency, X-Payment-Chain, and X-Pay-To headers. The body is implementation-defined.
The client constructs a payment, signs it, and resubmits the original request with an X-Payment header carrying the receipt.
The server (typically via a facilitator) verifies the receipt and, on success, returns 200 with the original resource representation. On failure, the server returns 402 again or 4xx with X-Payment-Error.
3. Headers
Header values are case-insensitive identifiers; amounts are decimal strings, not floats. Receipts are opaque to the client; format is defined per (chain, facilitator) pair.
# Response (402 Payment Required) X-Payment-Required: 0.0030 # decimal amount X-Payment-Currency: USDC # ISO-style currency / token X-Payment-Chain: base # chain identifier X-Pay-To: 0x4f3a…b2c1 # payee address # Request retry (200 OK on success) X-Payment: eyJjaGFpbiI6ImJhc2Ui... # base64-encoded signed receipt
4. Verification
The server forwards the X-Payment value to a verifier — usually run by the facilitator — which returns a signed attestation. Servers SHOULD cache attestations keyed by (receipt-hash, resource-uri) for the lifetime of the receipt to avoid hot-loop chain reads.
Receipts SHOULD be single-use against (resource-uri). Replay protection is the verifier's responsibility.
5. Discovery
Servers MAY register at the public Bazaar registry (bazaar.x402.org). The registry is informational; servers are not required to register and may publish endpoints out-of-band.
Clients MAY observe the Bazaar registry to populate menus or directories of payable services.
6. Error semantics
A 402 response is not an error in the protocol sense — it is the explicit handshake. Repeated 402 after a valid X-Payment indicates a verification failure; the server SHOULD include X-Payment-Error.
Servers SHOULD treat malformed X-Payment as 400 Bad Request. Servers SHOULD NOT charge for failed requests.