What HTTP 402 Payment Required means
In x402, a server responds with HTTP 402 Payment Required and payment requirements so the client can pay and retry the request. RFC 9110 still reserves the code for future use, and x402, an open protocol created by Coinbase, defines how that payment works.
HTTP 402 exists, but HTTP leaves payment behavior undefined
HTTP 402 is a status code with a reserved meaning in the HTTP standard and a payment workflow in x402. RFC 9110, section 15.5.3, reserves the code for future use. It specifies neither a payment format nor a client retry.
x402 supplies the payment exchange around the status code. Its v2 HTTP transport puts a PaymentRequired object in the PAYMENT-REQUIRED response header, giving a client payment data alongside the 402.
The x402 whitepaper, dated May 6, 2025, describes an open payments protocol developed by Coinbase using the long-reserved status code.
The official x402 FAQ says x402 is an open protocol and requires no Coinbase products. Coinbase Developer Platform created the standard and provides tooling. The repository uses Apache License 2.0.
402 was reserved in HTTP/1.1
402 Payment Required first appears in RFC 2068, published in January 1997. Section 10.4.3 says, “This code is reserved for future use.”
The earlier HTTP/1.0 specification, RFC 1945, was published in May 1996. Its section 9.4 lists client errors 400, 401, 403 and 404. It does not define 402.
RFC 2616, published in June 1999, retains 402 in section 10.4.3 with the same wording. RFC 7231, published in June 2014, uses the fuller sentence in section 6.5.2: “The 402 (Payment Required) status code is reserved for future use.”
RFC 9110, published in June 2022, keeps that sentence in section 15.5.3. It obsoletes RFC 7231, but it does not define a payment exchange for 402.
x402 brought a payment protocol to that reserved code. Its v2 announcement says the protocol launched in May 2025, and the Linux Foundation announced the x402 Foundation on April 2, 2026. That announcement describes the protocol, created by Coinbase, as moving to the Linux Foundation.
402 vs 401, 403 and 429
401 Unauthorized means the request lacks valid authentication credentials. The client uses the server's WWW-Authenticate challenge to authenticate and retry.
402 Payment Required, in x402 v2, asks the client to pay and retry. The server sends the price in PAYMENT-REQUIRED, and the client retries with its payment payload in PAYMENT-SIGNATURE.
403 Forbidden means the server understood the request and refuses to fulfill it. The client should not automatically retry with the same credentials. It may retry with new or different ones.
429 Too Many Requests means the client sent too many requests in a given amount of time. The client waits, for as long as the Retry-After header says when the server sends one.
A received 402 needs payment instructions
A 402 with a PAYMENT-REQUIRED header carries the x402 v2 payment requirements in Base64-encoded JSON. Decode the header and read the PaymentRequired object before constructing the payment.
An absent PAYMENT-REQUIRED header does not, by itself, rule out x402. The earlier HTTP transport placed payment requirements in a JSON response body. Inspect the body and the server's documentation to distinguish that transport from a server-specific payment convention.
A payable x402 v2 response uses defined headers
An x402 v2 server sends status 402 with a PAYMENT-REQUIRED response header containing a Base64-encoded JSON PaymentRequired object. Use the v2 HTTP transport specification as the reference for the exchange.
The client signs its payment payload and retries the request with PAYMENT-SIGNATURE. This request header contains a Base64-encoded JSON PaymentPayload. The buyer's signature remains part of the payload sent for verification and settlement.
The server returns settlement information through PAYMENT-RESPONSE on success. That response header contains a Base64-encoded JSON SettlementResponse. Keep the response header distinct from the payment requirements sent with the initial 402.
A facilitator can verify and settle the payment for the resource server. Using a facilitator is optional but recommended in the x402 documentation, and a resource server can perform verification and settlement itself. A facilitator does not hold funds or act as a custodian.
TypeScript, Python and Go have reference implementations. TypeScript server integrations include Express, Hono, Next.js and Fastify. Python integrations include FastAPI and Flask, while Go integrations include Gin, net/http and Echo.
The client integrations include Fetch and Axios, Go net/http, and Python httpx and requests. Match your client and server work to the same transport specification. The v2 announcement, dated December 11, 2025, says the reference SDKs are fully backward-compatible with v1.
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi... # base64 JSON: x402Version 2, accepts[]
GET /api/report HTTP/1.1
PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6Mi... # base64 JSON: the signed payment
HTTP/1.1 200 OK
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLC... # base64 JSON: settlement result
An x402 v2 exchange. The full field list is on the x402 page.
from fastapi import FastAPI, Request
from xenarch import require_payment
app = FastAPI()
gate = require_payment(SITE_TOKEN, api_base="https://api.xenarch.dev")
@app.get("/premium/article")
@gate
async def article(request: Request):
return {"content": "..."}
Xenarch's FastAPI decorator (pip install "xenarch[fastapi]"). Bots get a 402 at the price set in the dashboard, people get the page.
AI agents pay through HTTP or MCP
An AI agent can use the HTTP payment exchange through a client that signs a payment and retries the request. The agent's wallet supplies the buyer's signature. On the EVM exact scheme, the facilitator pays gas while the client controls the flow of funds through cryptographic signatures.
A facilitator cannot change a signed payment and settle the altered payload. The x402 documentation says tampering would fail signature checks. This separates submitting settlement from controlling the buyer's signed payment.
MCP carries x402 payment data in tool results and metadata rather than HTTP payment headers. A paid tool returns a result with isError: true and PaymentRequired data. The client retries with the payment in _meta['x402/payment'].
The MCP settlement information arrives in _meta['x402/payment-response']. Follow the v2 MCP transport specification for that exchange. An MCP implementation needs the metadata transport even when its payment uses the same underlying protocol.
Xenarch uses 402 for crawler gating and agent payments
Xenarch gating returns HTTP 402 to charge bots for access. Its integrations include WordPress, Joomla, a Cloudflare Worker and Python FastAPI middleware with a require_payment decorator. The Python middleware and decorator let humans through and serve the page if the Xenarch API is unreachable.
The WordPress, Joomla and Cloudflare integrations add Link, X-Pay-Json and X-Xenarch headers to the 402 response, pointing to the site's /.well-known/pay.json.
The price for require_payment(site_token, api_base, cache_ttl_s) comes from the dashboard.
Xenarch's 402 body is an x402 version 1 envelope with x402Version 1 and an accepts array. It also carries gate_id, price_usd, seller_wallet, network, asset, protocol, the facilitator list, verify_url and expires. Xenarch seller integrations accept a standard v1 X-PAYMENT header containing base64-encoded JSON with x402Version 1, scheme exact and network base, including from agents that know nothing about Xenarch. Xenarch settles the payment through a facilitator. After paying, a Xenarch-aware agent retries with X-Xenarch-Gate-Id and X-Xenarch-Tx-Hash. The seller's middleware re-verifies that pair on each request. There is no access token to issue or rotate.
Xenarch takes one asset on one network: USDC on Base mainnet. Native USDC uses 6 decimals. Each payment requirement Xenarch issues sets payTo to the seller's own wallet, so funds move directly from payer to seller without a Xenarch contract between them.
The MCP server, @xenarch/agent-mcp, uses xenarch_pay to pay only 402 responses that carry a Xenarch gate_id. The tool treats a plain x402 402 from a non-Xenarch server as not gated. The server refuses every payment unless an agent token is set in XENARCH_API_TOKEN. Its local payment cap is $1 per call, configurable with XENARCH_MAX_PAYMENT_USD. The xenarch_pay_link tool pays a hosted payment link by link id and refuses links over $1 unless max_price_usd is raised. It gets the link’s x402 envelope from the Xenarch API.
Questions
HTTP 402 Payment Required is a status code reserved for future use by RFC 9110. In x402 over HTTP, the server uses it to send payment requirements in the format defined by the protocol version.
Yes, RFC 9110 includes 402 Payment Required. It marks the code as reserved for future use rather than defining a payment exchange.
With x402, a 402 requires payment before the server serves the request, so the client pays and retries. A 403 means the server understood the request and refuses it, so the client should not automatically retry with the same credentials. RFC 9110 still reserves 402, while x402 defines the payment exchange.
Return status 402 with a Base64-encoded JSON PaymentRequired object in PAYMENT-REQUIRED for x402 v2. Receive the client's retry in PAYMENT-SIGNATURE and return settlement information in PAYMENT-RESPONSE.
An agent signs a payment and retries the request. Over HTTP, x402 v1 uses X-PAYMENT and v2 uses PAYMENT-SIGNATURE. The x402 v2 MCP transport carries the payment in _meta['x402/payment'].
Answer AI crawlers with 402
Xenarch gating returns a payable 402 to AI crawlers on WordPress, Joomla, a Cloudflare Worker or FastAPI, and the USDC goes straight to your wallet.
GatingDocs