# 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.

By Valerii Checha, 14 Nov 2026

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.

1. Ask (client → server): GET /premium-data HTTP/1.1 / Host: api.example.com. 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](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md).
2. 402 (server → client): HTTP/1.1 402 Payment Required / PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi… (base64). “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). Sources: [x402 HTTP transport, v2](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md), [x402 specification, v2](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md) and [RFC 9110: HTTP Semantics, 402 Payment Required](https://www.rfc-editor.org/rfc/rfc9110.html#name-402-payment-required).
3. Pay and retry (client → server): GET /premium-data HTTP/1.1 / PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6Mi… (base64). “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. Sources: [x402 specification, v2](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md), [x402 docs: HTTP 402](https://docs.x402.org/core-concepts/http-402) and [x402 docs: FAQ](https://docs.x402.org/faq).
4. Settle (server, often via a facilitator): POST /verify, then POST /settle (to the facilitator). “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. Sources: [x402 specification, v2](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md) and [x402 docs: Facilitator](https://docs.x402.org/core-concepts/facilitator).
5. Deliver (server → client): HTTP/1.1 200 OK / PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVl… (base64). 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. Sources: [x402 docs: HTTP 402](https://docs.x402.org/core-concepts/http-402) and [x402 HTTP transport, v2](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md).

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](https://storewalk.ai/blog/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 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".

## 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.

On the page, you paste the PAYMENT-REQUIRED header value and the body of a 402 response (or load an example), and read where the requirements are, the x402 version, what is for sale, how many ways to pay there are, the first one, and what our TRX-005 would report. The examples:

- The spec’s v2 example. Copied from the x402 HTTP transport spec, v2. The first way to pay: exact on eip155:84532: 10000 atomic units of USDC, paid to 0x209693Bc6afc0C5328bA36FaF03C514EF312287C. PASS: answers 402 with x402 v2 requirements (1 way to pay).
- The spec’s v1 example. Copied from the x402 specification, v1: no header, the requirements in the body. The first way to pay: exact on base-sepolia: 10000 atomic units of USDC, paid to 0x209693Bc6afc0C5328bA36FaF03C514EF312287C. PASS: answers 402 with x402 v1 requirements (1 way to pay).
- A half-built one (ours). Made up by us: the spec’s v2 object without its resource. The first way to pay: exact on eip155:84532: 10000 atomic units of 0x036CbD53842c5426634e7929541eC2318f3dCF7e, paid to 0x209693Bc6afc0C5328bA36FaF03C514EF312287C. WARN: answers 402 but its x402 payment-required header has no resource (x402 v2 requires it).
- A bare 402 (ours). Made up by us: the kind of page a store closed for an unpaid bill can show, with no x402 in it. The first way to pay: none. FAIL: answers HTTP 402 with no x402 payment requirements: not an x402 challenge.

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](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md), [x402 specification, v1](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v1.md) and [Storewalk: TRX-005, x402 payment challenge offered](https://storewalk.ai/checks/TRX-005).

The reader uses the same rules as our [TRX-005](https://storewalk.ai/checks/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](https://storewalk.ai/checks/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.

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](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md).

Articles, downloads or files. What x402’s own pages say: 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.

Sources: [x402 specification, v2](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md) and [x402 docs: FAQ](https://docs.x402.org/faq).

Physical goods with shipping. What x402’s own pages say: 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.

Sources: [x402 specification, v2](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md) and [x402 docs: FAQ](https://docs.x402.org/faq).

Shoppers who pay by card. What x402’s own pages say: “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.

Sources: [x402.org](https://www.x402.org/) and [x402 docs: FAQ](https://docs.x402.org/faq).

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](https://storewalk.ai/blog/ucp-explained) and [ACP](https://storewalk.ai/blog/acp-explained) define, and payments inside those flow through card tokens or mandates such as [AP2](https://storewalk.ai/blog/ap2-explained). 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](https://storewalk.ai/) 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](https://storewalk.ai/blog/why-agents-cant-buy) matters more than this check.

The sources below were last checked on the date shown.

## Sources

- [x402.org](https://www.x402.org/)
- [x402 specification, v2](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md)
- [x402 HTTP transport, v2](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md)
- [x402 specification, v1](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v1.md)
- [x402 docs: HTTP 402](https://docs.x402.org/core-concepts/http-402)
- [x402 docs: Facilitator](https://docs.x402.org/core-concepts/facilitator)
- [x402 docs: Payment schemes](https://docs.x402.org/schemes/overview)
- [x402 docs: FAQ](https://docs.x402.org/faq)
- [x402 docs: Migration guide, V1 to V2](https://docs.x402.org/guides/migration-v1-to-v2)
- [GitHub: coinbase/x402](https://github.com/coinbase/x402)
- [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html)

Last checked 4 Nov 2026
