How x402 Works: The HTTP 402 Payment Flow

The short version

x402 turns payment into a normal HTTP negotiation. A buyer requests a resource. The seller replies with 402 Payment Required and describes acceptable payment options. The buyer signs a payment payload for one option and retries the same resource request. The seller verifies and settles the payment, then returns the paid content.

That means x402 is not a checkout page and not a user account system. It is a request-response pattern that lets software clients and agents pay for a single API call, file, report, or content resource directly over HTTP.

GET /weather HTTP/1.1
Host: api.example.com

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

GET /weather HTTP/1.1
Host: api.example.com
PAYMENT-SIGNATURE: <signed payment payload>

HTTP/1.1 200 OK
PAYMENT-RESPONSE: <settlement metadata>
Content-Type: application/json

The headers explain the state

The status code tells you whether payment is required. The payment headers tell you which x402 state you are seeing. A seller challenge uses PAYMENT-REQUIRED. A paid retry uses PAYMENT-SIGNATURE. A successful paid response can include PAYMENT-RESPONSE metadata so the client can log the payment result.

Do not debug an x402 route by looking only at the response body. Capture headers, selected scheme, selected network, route key, and facilitator response. Those fields usually explain whether the failure is an HTTP handler bug, a policy rejection, a malformed payment payload, a network issue, or settlement failure.

The four roles to keep separate

Most implementation mistakes come from mixing responsibilities. The seller owns the paid resource and the declared payment requirements. The buyer owns the decision to pay and the wallet policy. The facilitator helps verify and settle. The selected network executes the scheme-specific payment.

Seller: declares price, scheme, network, payTo address, route description, and MIME type.
Buyer: evaluates requirements, signs a payment payload, and retries within policy.
Facilitator: verifies payment payloads and helps settle validated payments.
Network: executes the payment according to the selected scheme and chain rules.

The separation matters for agents. An agent seeing a 402 has not been ordered to pay. It has received an offer to pay. The agent still needs a host allowlist, maximum price, network allowlist, budget, retry policy, and user-intent check before it signs.

A debugging checklist

1. Confirm the unpaid request returns HTTP 402 rather than 403, 404, or 500.
2. Inspect the PAYMENT-REQUIRED header or response details and confirm the route, price, network, and destination address.
3. Confirm the buyer selected one acceptable requirement and signed for the same resource.
4. Log facilitator verification separately from settlement.
5. Confirm the paid resource is served only after valid verification and successful settlement policy.
6. Record PAYMENT-RESPONSE metadata for audit and retry decisions.

To see the same sequence interactively, open the x402 Flow Simulator. To generate starter route code, use the Quickstart Configurator. To check the concepts, take the Payment Scheme Quiz.