Skip to content

Guide8 min readPublished

x402 explained: HTTP 402 payments for stores

x402 turns the long-unused HTTP 402 status code into a pay-and-retry step for agents. How a payment works, what changed in version 2, and why it suits data and downloads better than parcels.

An AI agent asks a weather API for tomorrow's forecast. Instead of the data, it gets back status 402 and a header listing a price, a network and a wallet address. It signs a payment from its own wallet, sends the same request again with the signature attached, and this time gets the forecast. Nobody created an account, and no API key changed hands.

That is x402. Its documentation calls it "an open‑source protocol that turns the dormant HTTP 402 Payment Required status code into a fully‑featured, onchain payment layer for APIs, websites, and autonomous agents." For a store that ships parcels it is not a checkout: it has no cart, no shipping and no tax fields, and its own pages say stablecoins are "the primary use case". It fits per-request digital goods: API calls, data, articles and downloads.

Everything about x402 below comes from its specification, its documentation and its site. What our scan does with it comes from our own code, which at least has the decency to be shorter.

What is HTTP 402, and why was it never used?

HTTP has had a status code for "pay first" for a long time, and no agreed way to use it. The current HTTP standard, RFC 9110, gives it one sentence: "The 402 (Payment Required) status code is reserved for future use." It has been the status code with nothing to do, the HTTP version of a spare room nobody is allowed to use.

x402 moves in. Its docs open with "For decades, HTTP 402 Payment Required has been reserved for future use. x402 unlocks it". The site describes the idea in one line: "If a request arrives without payment, the server responds with HTTP 402, prompting the client to pay and retry."

A bare 402 is not x402. Some platforms already answer 402 for a shop that is closed or has an unpaid bill. Without the payment requirements x402 defines, a 402 is just a status code.

How does an x402 payment work?

The specification lists four steps: the client asks, the server answers that payment is required and says how, the client sends "a signed payment authorization in the subsequent request", and the server "verifies the payment authorization and initiates blockchain settlement". Over HTTP that is three headers, all base64-encoded JSON. Step through it:

An x402 payment, step by step: ask, 402, pay and retry, settle, deliver
The step

Showing: Ask

GET /premium-data HTTP/1.1
Host: api.example.com

What the spec says

The spec’s first step: “Client Request: Client makes a request to a resource server”. Nothing about it is special: no header, no account.

In plain words (ours)

An agent asks for a page or an API result the way any client does.

Source: x402 specification, v2

The headers are x402 v2 (December 2025). Version 1 sent the price list as a JSON body and the payment in an X-PAYMENT header; the migration guide maps one to the other.

The server does not have to touch a blockchain. The docs describe a facilitator as "an optional but recommended service that simplifies the process of verifying and settling payments between clients (buyers) and servers (sellers)", and add that it "does not hold funds or act as a custodian". The FAQ says "anyone can run a facilitator". In card terms, it is closer to a payment processor's verification service than to a bank, though the comparison is ours.

The agent needs a wallet. The FAQ is blunt about it: "Do agents need wallets? Yes." That puts it beside the card-based routes in how agents pay, as a separate way for an agent to hold and spend money.

What changed in x402 version 2?

Version 2, dated 9 December 2025 in the specification's own history, moved the price list out of the response body and into a header. Its changes, in the spec's words: "CAIP-2 networks, restructured PaymentPayload/Required, ResourceInfo separation, extensions support".

Version 1Version 2
Where the server's requirements goA JSON bodyThe PAYMENT-REQUIRED header
The client's paymentX-PAYMENT headerPAYMENT-SIGNATURE header
The server's receiptX-PAYMENT-RESPONSEPAYMENT-RESPONSE
How a network is namedA name such as base-sepoliaCAIP-2, such as eip155:84532
The price fieldmaxAmountRequiredamount

The amount is in "atomic token units", so 10000 of a token is not ten thousand dollars. The project also changed hands: Coinbase's repository now says "We've moved the x402 repo under the x402 Foundation repo" and calls itself "a development fork", and the site's footer names "x402 a Series of LF Projects, LLC". The FAQ still credits Coinbase Developer Platform as "the creators of the standard".

What does an x402 challenge look like?

Paste the PAYMENT-REQUIRED header and the body of a 402 response, or load one of the examples. The first two are copied from the specification; the last two are ours, made up to show what goes wrong:

Read a 402 response the way our x402 check does
Start from

Copied from the x402 HTTP transport spec, v2.

Where it was
The PAYMENT-REQUIRED header (the v2 place)
x402Version
2
What is for sale
https://api.example.com/premium-data
Ways to pay
1
The first way
exact on eip155:84532: 10000 atomic units of USDC, paid to 0x209693Bc6afc0C5328bA36FaF03C514EF312287C

Our TRX-005 would report: PASS: answers 402 with x402 v2 requirements (1 way to pay).

The reader assumes the response status was 402 and runs in your browser; nothing is sent or paid. Our scan only reads a 402 it meets on your home page or at /api, and when it meets none it reports SKIPPED, because x402 has no discovery file to look for.

Sources: x402 HTTP transport, v2, x402 specification, v1 and Storewalk: TRX-005, x402 payment challenge offered

The reader uses the same rules as our TRX-005. That check reads two places: the home page our crawl already fetched, and one probe at /api, the same path another public scanner asks for. A 402 with a valid v2 header, or a valid v1 body, passes. A half-built one is a warning that says what is missing. A 402 with no x402 payload at all fails (unless bot protection answered instead, which is SKIPPED), because to an agent it is a locked door with no price on it. When no 402 turns up, the check reports SKIPPED, since x402 has no discovery file and a store could be charging on a route we never asked about. It never pays anything. It is one of the lightly weighted agent signals in our score, next to TRX-006, which looks for a related draft, the Machine Payments Protocol.

Does x402 fit a store that ships parcels?

Mostly not yet, and x402 does not claim it does. The specification's own examples are "APIs, content, data", "Pay-per-use content (articles, videos, downloads, tools)" and "per-call pricing". Pick what you sell:

Does x402 fit what you sell? x402’s own pages, and our reading
What you sell

Showing: An API or data feed, priced per call

What x402’s own pages say

This is the spec’s home ground: a resource server is “A service that requires payment for access to protected resources (APIs, content, data, etc.)”, and its use cases include “Resource monetization with per-call pricing”.

Our reading

A good fit. No account, no API key, and an agent can pay as it goes. TRX-005 is written for this case.

Source: x402 specification, v2

Three details decide it for a typical store. The payment requirements carry a scheme, a network, an amount, an asset, a recipient and a timeout, and nothing for an address, a delivery option or tax. Payments with the default scheme are final: the FAQ calls the exact scheme "a push payment", "irreversible once executed". Its answer on refunds lists two options: "Business‑logic refunds: Seller sends a new token transfer back to the buyer", or batch-settlement, a scheme for "many small payments on EVM", where "Cooperative refunds and timed withdrawals from channel escrow are defined in the scheme". And card payers are out of reach without help. Asked about fiat, the FAQ says "Not natively. However, facilitators or third‑party gateways can wrap x402 flows with on‑ and off‑ramps."

A store selling shoes to an agent needs a checkout around the payment: a cart, shipping, tax and an order. That is what UCP and ACP define, and payments inside those flow through card tokens or mandates such as AP2. x402 could sit inside such a flow as one way to pay. On its own, x402 is a till with no shop built around it.

Where x402 does make sense for a retailer is the side door. A store that sells digital downloads, paid product data, a price feed for comparison agents, or an API for wholesale stock checks could put x402 in front of those routes and let agents pay per request. The x402 site shows the middleware as a single app.use(paymentMiddleware(...)) call, with each route's ways to pay in its config. Whether your accountant is ready for stablecoin receipts is a separate question, and no status code answers it.

Frequently asked questions

What is x402 in simple terms?

A way for a server to answer "pay first" with HTTP status 402, list a price and where to pay, and accept a signed payment on the next request. Its site calls it "an open, neutral standard for internet-native payments".

Is x402 only for crypto?

Its site says "Stablecoin payments are the primary use case" and that x402 "is also extensible to traditional payment methods". The FAQ says it does not support fiat or card deposits "natively", but gateways can wrap it.

Can an online store use x402 for checkout?

Not as a checkout. x402 has no cart, shipping or tax fields. A store can use it for per-request digital goods, such as data or downloads, and use a checkout protocol such as UCP or ACP for parcels.

What is the difference between x402 v1 and v2?

Version 2 (December 2025) moved the requirements into a PAYMENT-REQUIRED header, renamed the client and receipt headers to PAYMENT-SIGNATURE and PAYMENT-RESPONSE, and named networks in CAIP-2 form. Our TRX-005 accepts both.

Does Storewalk check for x402?

Yes, with TRX-005. It reads a 402 only where it already asks, the home page and /api, and it reports SKIPPED rather than FAIL when it sees none, because x402 has no discovery file. For a store without paid digital routes, there is nothing to fix.

If you do sell data or downloads by the request, run our agent readiness scanner and look at TRX-005 first. If you sell only parcels, expect SKIPPED there, and spend the afternoon on your shipping rates instead. For a parcel store, what decides whether an agent can buy matters more than this check.

The sources below were last checked on the date shown.