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.
01What 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.
02How 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
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.
“If no valid payment is attached, the server responds with a payment required signal and payment requirements”. Over HTTP: “The PAYMENT-REQUIRED header is the canonical HTTP transport location for the PaymentRequired object.” The HTTP standard itself says only that 402 “is reserved for future use.”
In plain words (ours)
The header, once decoded, is a price list: what is for sale, and each way the server will take payment (a network, an asset, an amount and an address).
GET /premium-data HTTP/1.1
PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6Mi… (base64)
What the spec says
“Client submits a signed payment authorization in the subsequent request”. The docs: PAYMENT-SIGNATURE “is sent by the client when retrying a request after receiving a 402 response”. And on agents: “Do agents need wallets? Yes.”
In plain words (ours)
The agent signs a payment from its own wallet and sends the same request again, with the signature attached.
POST /verify, then POST /settle (to the facilitator)
What the spec says
“Server verifies the payment authorization and initiates blockchain settlement”. The facilitator “is an optional but recommended service”, and it “does not hold funds or act as a custodian”.
In plain words (ours)
The server can hand the checking and the on-chain transfer to a facilitator, so it never needs to talk to a blockchain itself.
HTTP/1.1 200 OK
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVl… (base64)
What the spec says
PAYMENT-RESPONSE “is returned by the server after attempting settlement, whether successful or failed, providing structured feedback about the payment outcome.”
In plain words (ours)
The agent gets what it paid for, plus a receipt in a header. A failed payment comes back as another 402.
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.
03What 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 1
Version 2
Where the server's requirements go
A JSON body
The PAYMENT-REQUIRED header
The client's payment
X-PAYMENT header
PAYMENT-SIGNATURE header
The server's receipt
X-PAYMENT-RESPONSE
PAYMENT-RESPONSE
How a network is named
A name such as base-sepolia
CAIP-2, such as eip155:84532
The price field
maxAmountRequired
amount
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".
04What 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
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.
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.
05Does 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
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.
The spec lists “Pay-per-use content (articles, videos, downloads, tools)”. Payment is final with the default scheme: the FAQ calls it “a push payment”, “irreversible once executed”.
Our reading
A reasonable fit for small, instant digital goods, as long as you are happy refunding by sending money back yourself.
The payment requirements have a scheme, network, amount, asset, payTo and timeout. None of the fields x402 lists is for an address, shipping or tax. Refunds: “Business‑logic refunds: Seller sends a new token transfer back to the buyer”, or, with batch-settlement on EVM, “Cooperative refunds and timed withdrawals from channel escrow are defined in the scheme”.
Our reading
A poor fit today. A cart, shipping options and tax need a checkout protocol, such as UCP or ACP, around the payment. x402 covers only the moment of paying.
“Stablecoin payments are the primary use case. x402 is also extensible to traditional payment methods.” On fiat: “Not natively. However, facilitators or third‑party gateways can wrap x402 flows with on‑ and off‑ramps.”
Our reading
Not a fit on its own. An agent paying with a card goes through the card networks’ and checkout protocols’ routes instead.
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.
06Frequently 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.