The HTTP 402 Flow

The sequence

A first request can be an ordinary GET or POST. If the resource requires payment and no acceptable payment payload is present, the resource server returns HTTP 402 and includes machine-readable requirements. In v2 those requirements are exposed through the PAYMENT-REQUIRED header, with response-body details depending on the middleware and error case.

The client decodes the requirements, chooses an acceptable option, builds the payment payload for the selected scheme and network, signs it, Base64-encodes it, and retries the same resource request with PAYMENT-SIGNATURE. The server verifies the payload locally or through a facilitator. It then settles immediately, batches later, or rejects the attempt according to the scheme.

The final response carries PAYMENT-RESPONSE with settlement details. On success this accompanies the requested content. On failure it can accompany another 402 response so the client has structured payment feedback instead of a generic access denial.

GET /paid-report HTTP/1.1
Host: api.example

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64 PaymentRequired>

GET /paid-report HTTP/1.1
Host: api.example
PAYMENT-SIGNATURE: <base64 PaymentPayload>

HTTP/1.1 200 OK
PAYMENT-RESPONSE: <base64 SettlementResponse>

What the headers mean

PAYMENT-REQUIRED is the server offer. It tells the client which schemes, networks, assets, amounts, destination addresses, and optional extensions the server accepts for that resource. The most important implementation detail is that this is not a human paywall message. It is data that software can evaluate.

PAYMENT-SIGNATURE is the client authorization. Its exact structure depends on the chosen payment scheme and network. For EVM exact payments it may involve EIP-712-style signing; for Solana it involves Solana transaction semantics; for other networks it follows that network binding.

PAYMENT-RESPONSE is the receipt-like result. It lets the server tell the client what happened after verification and settlement, including success or error details.

• A good client does not blindly pay the first option; it checks scheme, network, asset, amount, destination, and policy.
• A good server does not trust the header shape alone; it verifies signature, amount, destination, expiry, replay controls, and scheme-specific invariants.
• A good facilitator treats the payload and requirements as a security boundary, not only as routing metadata.

The 402 caveat

HTTP 402 is real, but generic user agents do not have a universal payment UI for it. That means the x402 experience depends on SDK-aware clients, wallets, agents, command-line tools, or application-specific browser integrations. A normal browser that receives a raw 402 will treat it like a generic 4xx response.

That caveat is not a weakness for API and agent use cases. It is the reason the docs emphasize clients and wrappers such as fetch, Axios, Python HTTP clients, Go clients, MCP tools, and paywall components.