The x402 Payment Flow, Request by Request

HTTP 402 Payment Required is one response. An x402 purchase is a controlled sequence around it: a resource request, a machine-readable offer, a signed payment payload, the selected payment flow, and a final response the buyer can reconcile.

The status code is the visible hinge. The useful part is everything the client and seller can prove on either side of it.

402 is a negotiation boundary

The IANA HTTP registry names 402 as “Payment Required.” x402 version 2 gives that status an interoperable payment exchange. The protocol separates the core payment objects from the transport that carries them and the scheme that moves value.

For HTTP, three headers carry the exchange. PAYMENT-REQUIRED tells the client what the server will accept. PAYMENT-SIGNATURE returns the client’s selected requirement and scheme-specific authorization. PAYMENT-RESPONSE reports the settlement result.

That distinction matters. A 402 is not proof that money moved. It is a counteroffer from a protected resource: satisfy one of these requirements, then try the request again.

The first request asks for the resource

The client starts with an ordinary HTTP request to the protected URL. It might ask for a dataset, an API action, a generated report, or a piece of content. If the request already carries a valid payment payload, the server can skip the challenge. Otherwise it returns 402 Payment Required.

The x402 HTTP transport specification makes the base64-encoded PAYMENT-REQUIRED header the canonical wire location for the PaymentRequired object. The body remains an application concern, so the seller can still return a useful machine-readable error document.

The first request does not need a checkout session. It establishes which resource the client wants and gives the server a chance to state the commercial requirement in the same HTTP interaction.

The 402 response is an executable offer

In version 2, PaymentRequired identifies the protocol version and the protected resource. Its accepts field contains one or more payment requirements. Each requirement names a scheme, network, amount, asset, recipient, and timeout, plus any scheme-specific data.

The server is not saying “go pay somehow.” It is describing the combinations it can verify and settle for this request. The client can compare those requirements with the networks, assets, and schemes it supports, then select one.

The amount is expressed in the atomic unit required by the selected asset. That makes the instruction precise for software, but precision on the wire does not choose the price. The seller still has to decide what the resource costs, how long the offer remains valid, and when a replacement price should apply. Pricing an API for agents begins before the protocol message: define one billable action and a limit the buyer can understand before work runs.

The client selects, signs, and retries

The client creates a PaymentPayload JSON object for one accepted requirement. At the top level, x402Version identifies the protocol version, optional resource data identifies what is being purchased, accepted copies the one PaymentRequirements entry the client chose, and payload holds the scheme-specific authorization. Optional extensions carry negotiated protocol extensions.

For the specification’s exact-EVM example, the inner payload contains two things: signature, a hexadecimal EIP-712 signature, and authorization, the EIP-3009 parameters that name the payer, recipient, amount, validity window, and replay-prevention nonce.

PAYMENT-SIGNATURE is the transport representation of that whole object. The client serializes the complete PaymentPayload as JSON, Base64-encodes those bytes, and puts the resulting text in the HTTP header. Base64 is reversible encoding, not encryption. The header is therefore not “the signature” alone; after decoding, it yields the selected requirement, resource context, and scheme-specific payload containing the actual cryptographic signature.

const paymentSignature = Buffer.from(  JSON.stringify({    "x402Version": 2,    "resource": {      "url": "https://api.example.com/premium-data",      "description": "Access to premium market data",      "mimeType": "application/json"    },    "accepted": {      "scheme": "exact",      "network": "eip155:84532",      "amount": "10000",      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",      "maxTimeoutSeconds": 60,      "extra": {        "name": "USDC",        "version": "2"      }    },    "payload": {      "signature": "0x2d6a7588d6acca505cbf0d9a4a227e0c52c6c34008c8e8986a1283259764173608a2ce6496642e377d6da8dbbf5836e9bd15092f9ecab05ded3d6293af148b571c",      "authorization": {        "from": "0x857b06519E91e3A54538791bDbb0E22373e36b66",        "to": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",        "value": "10000",        "validAfter": "1740672089",        "validBefore": "1740672154",        "nonce": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f13480"      }    }  }),  "utf8",).toString("base64");headers.set("PAYMENT-SIGNATURE", paymentSignature);

The client then resends the original resource request with that header. Its method, URL, and application input remain the same, as the query body does in the example. The seller validates the attached payment evidence against the accepted offer.

The example illustrates encoding, not a runnable purchase. Its authorization expired in February 2025, and the signature is not a credential to reuse. A real client must generate fresh authorization for the requirement it accepts.

EIP-3009 signs the transfer fields from, to, value, validAfter, validBefore, and nonce within an EIP-712 domain. It does not automatically sign the resource URL, contract or rights revision, or application request body. Those fields need server-side validation and association with the accepted offer; their presence in the outer JSON object does not make them signed purchase terms.

A signature is evidence of the payer’s authorization under a particular scheme. It is not, by itself, a settlement receipt. Treating “header present” as “paid” would remove the very control the next step exists to provide.

Authorization flow verifies before execution

In the default authorization flow, the resource server validates the payment locally or asks a facilitator to verify it before execution. Verification checks the selected requirement and the scheme-specific authorization. The result answers whether the payload is valid for the payment the server requested.

A failed verification stops execution in this flow. A failed settlement stops a successful paid response, but work may already have run. The server can return 402 with a failure PAYMENT-RESPONSE; it must preserve the execution outcome for recovery. A malformed payment payload or requirements is an invalid request instead. The HTTP transport maps that case to 400 Bad Request. A failed payment may result from an expired authorization, insufficient funds, a mismatched amount or recipient, an unsupported scheme and network pair, or a reused payload that the scheme rejects.

Verification should happen against the exact offer that produced the retry. If price configuration changes between the first request and the second, the seller needs a stable offer or revision to determine which requirement is authoritative. The protocol carries the requirement; the seller’s system preserves its commercial history.

Fulfillment and settlement are separate decisions

The v2 specification defines three flows. Its default authorization sequence is verify → resource execution → settlement → response. Origin execution and delivery to the buyer are distinct: settlement can fail after work ran but before a successful response is sent.

The upfront flow settles before resource execution. The escrow flow commits a deposit or ceiling before execution and records the final charge afterward. Both omit a separate /verify step. A scheme and its mechanism must support the chosen flow, and the seller must decide what execution and delivery risk it accepts.

This is where implementation details become business consequences. A seller might be able to regenerate a data response safely after a timeout. An external action may be irreversible. The integration needs to know whether work ran, whether it can run again, and which outcome should be returned when the buyer retries.

AWS WAF’s AI traffic monetization flow is one concrete ordering. AWS verifies the authorization synchronously, allows the origin request, and settles only when the origin returns a successful 2xx response. If the origin fails, settlement is skipped. If settlement fails after the origin succeeds, AWS does not serve the content to the buyer. That is a product implementation of x402, not a universal rule for every resource server or scheme.

The final response closes the protocol loop

In the authorization flow, after successful settlement the server returns the purchased resource and a base64-encoded PAYMENT-RESPONSE header. The SettlementResponse reports whether settlement succeeded and can include the transaction, network, payer, actual amount, and extension data.

The response gives the client a protocol-level result it can decode without scraping the resource body. A failed settlement can also return a 402 with a failure PAYMENT-RESPONSE, while leaving the body available for an application-specific explanation.

The settlement response still is not the seller’s complete commercial record. It does not prove what the product delivered, whether the buyer later received a refund, how the amount was converted, or when proceeds reached a payout destination. An Agent Paid. Now What? follows that wider record from quote through fulfillment, corrections, and payout.

A facilitator changes the operator, not the contract

A facilitator is optional. The x402 facilitator documentation describes it as a service that verifies payment payloads and submits validated payments for settlement on behalf of resource servers. A seller can instead verify and settle locally when it has the network connectivity and scheme logic to do so.

Using a facilitator moves specialized verification and settlement execution behind an API. It does not choose the protected resource, price, accepted requirement, or fulfillment policy. The resource server still decides what to offer and when the selected payment flow permits delivery.

Production also requires an explicit facilitator path. The public x402.org facilitator is documented for development and testnet use. A mainnet seller must choose a production provider that supports the target network, run a facilitator, or self-facilitate.

Map one endpoint before adding middleware

Start with one protected endpoint and trace both attempts. Name the exact resource the first request identifies. Write the requirement the 402 returns. Decide which component selects and signs it, which component verifies it, when paid work may begin, what makes a retry safe, and what settlement result the final response must preserve.

Then trace the failure boundaries. The authorization can be invalid. Verification can time out. The resource can fail after verification. Settlement can fail after work. The final HTTP response can disappear on the way back to the buyer. Each boundary needs an owner and a recoverable transaction identity.

If you are preparing an endpoint for agent buyers, define the protected resource and its price before binding your business policy to protocol-specific code. recuut handles the seller-side payment interface around resources you continue to host and fulfill.