x402: HTTP 402 Payment Required for APIs and Agents

In brief: x402 is an HTTP payment pattern built around 402 Payment Required. A useful 402 response tells the client resource, amount, network, asset, recipient, and retry path. For agent services, x402 works best when paired with clear schemas, demo mode, and budget controls.

Subscriptions are the wrong shape for agents

Most API billing still assumes a human buyer. Someone creates an account, adds a card, copies an API key, waits for usage to batch into an invoice, and asks finance what to do when the card fails. That flow is tolerable for a team integrating a vendor once. It is a bad fit for an agent selecting tools while it is already in the middle of a task.

An agent needs a smaller contract: what does this request cost, which asset do you accept, where should payment go, and what proof do I send back? x402 answers that question inside the HTTP exchange. A server can return 402 Payment Required with machine-readable payment terms. The client signs a payment payload, retries the request, and receives the resource after verification and settlement.

This sounds like a billing detail, but it changes the product surface of an API. Paid endpoints can be discovered, priced, and called by software without a dashboard, a sales form, or a long-lived customer account.

What x402 changes

HTTP 402 Payment Required has existed as a reserved status code for decades. MDN still describes it as reserved and not standardized for one browser-wide behavior. x402 gives that unused status a concrete protocol for paid resources: payment requirements, signed payment payloads, and settlement receipts all move over normal HTTP.

The official x402 docs describe the standard as accountless, sessionless, credential-light payment for APIs and content. The important part for builders is narrower: x402 makes "this request costs this much" a response your client can parse.

The causal chain is practical because each step removes one piece of account-based billing: a parseable 402 lets the client choose a payment option, a signed payload gives the server proof that the payer authorized the amount, and settlement gives both sides a receipt before the server sends the paid resource.

Traditional metered billing still has a place. It works when the buyer is a company, usage is recurring, and the seller wants account-level controls. It breaks down when the buyer is a program that wants one geocoding call, one report, one model inference, or one enriched record. At that scale, signup and monthly invoicing become larger than the transaction.

Raw onchain payment is not enough either. Without a protocol, every API has to explain its chain, token, decimals, receiver, nonce model, and replay rules in its own SDK. x402 keeps the money-specific details in a standard payment envelope, so the API can remain an HTTP resource.

The actual flow, on the wire

A paid request starts as an ordinary HTTP request:

GET /v1/reports/eth-holders?address=0xabc... HTTP/1.1
Host: api.example.dev
Accept: application/json

If the endpoint requires payment and the request has no valid payment payload, the server returns 402 Payment Required. In the V2 flow described by current x402 materials, the payment requirement can be exposed through a Base64-encoded PAYMENT-REQUIRED header. Some implementations also include the decoded JSON in the body so humans and crawlers can inspect it:

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIiwiYWNjZXB0cyI6Wy4uLl19

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://api.example.dev/v1/reports/eth-holders?address=0xabc...",
    "description": "Holder report",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x071B17003fF214BaaF295813b5f585cC4ffd788c",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}

The accepts array is the negotiation surface. Each entry says which scheme, network, token, amount, and receiver the server will accept. A client that can pay with exact USDC on Base signs that payload. A client that cannot match any entry should stop or choose a different provider.

For EVM USDC, the client commonly signs an authorization for a token transfer, then retries the request with a Base64-encoded payment payload in PAYMENT-SIGNATURE:

curl 'https://api.example.dev/v1/reports/eth-holders?address=0xabc...' \
  -H 'PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6Miwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLCJwYXlsb2FkIjp7Ii4uLiI6Ii4uLiJ9fQ=='

The server verifies the payload locally or through a facilitator, settles the payment, and returns the resource. The response carries a Base64-encoded PAYMENT-RESPONSE header so the caller can store a receipt:

HTTP/1.1 200 OK
Content-Type: application/json
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4ZTQ3Zi4uLiIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MyJ9

{
  "address": "0xabc...",
  "holders": 14211,
  "generated_at": "2026-04-15T10:12:44Z"
}

The server can sit behind ordinary HTTP infrastructure. Proxies and clients see a status code, headers, and JSON. The payment-specific part is the contract between the resource server, the payer, and whichever settlement path the server chooses.

Before copying a header example, verify the current x402 docs, the client library you use, and the facilitator you plan to settle through. Header names, supported networks, and library defaults can move faster than evergreen articles.

What a facilitator actually does

The part most API teams do not want to own is blockchain plumbing: validating signatures, checking that a payload matches the declared payment terms, broadcasting settlement, watching confirmation, and returning a receipt. x402 calls the optional helper service for that job a facilitator.

The facilitator interface is intentionally small. A server posts the payment payload and payment details to /verify when it needs to know whether the client has authorized a valid payment. After the application work succeeds, the server posts to /settle; the facilitator submits the transaction and returns the settlement result.

The split matters because verification and settlement fail in different ways. Verification tells you the client produced a plausible payment authorization. Settlement is when funds actually move. Your API still decides when to do work, what to cache, how to handle errors, and whether to fulfill the request.

As of this article's last update, the x402 ecosystem includes multiple facilitators and bindings, including EVM and non-EVM paths. Treat that list as changing infrastructure. Pick one chain and one facilitator for your first endpoint, publish exactly what you accept, and make the 402 response honest.

How to actually ship it

For the first pass, choose one route where the value of a single call is already clear: a report, a search result, a scoring run, a piece of enriched data, or a model output. Do not put your whole product behind x402 on the first pass.

Then add payment middleware in front of that route:

1. When the request has no payment payload, return 402 with PAYMENT-REQUIRED and a readable JSON body.
2. When the request includes PAYMENT-SIGNATURE, verify that the payload matches the amount, asset, receiver, network, and resource you declared.
3. Run the handler only after verification succeeds.
4. Settle after the handler has produced a successful response.
5. Attach PAYMENT-RESPONSE to the final response and log enough receipt metadata to debug disputes.

Three implementation details are worth being strict about.

First, do not settle before your application work succeeds unless you have explicit refund or retry semantics. A payment that clears before your handler crashes becomes a support problem.

Second, derive the canonical resource URL on the server and compare it with the payment requirement you issued. The client should not be able to change resource and reuse a payment against a different paid response.

Third, treat replay and duplicate settlement as protocol bugs. EVM token authorizations rely on nonce rules, and non-EVM paths can have their own duplicate-submission concerns. Your facilitator should help, but your service should still assume duplicate requests will happen.

If you want a public sanity check, The Spawn's agent checker is built to separate declared x402 support from a live payment surface. A metadata file that says "x402" is weaker than an endpoint that actually returns a full 402 payment descriptor and can complete a follow-up roundtrip.

Why AI agents specifically need this

Agent discovery and agent payment are separate problems. ERC-8004 gives agents a place to publish identity, metadata, services, and reputation. x402 gives a buyer a way to pay a discovered service without opening a vendor account. Together, they make a practical path for agent-to-agent commerce: find the seller, inspect the service, receive payment terms, sign, retry, and use the result.

That path still needs guardrails because payment authorization is only one part of trust. A buyer agent should understand its budget, supported chains, allowed assets, and maximum spend before it signs anything. A seller agent should expose enough schema, pricing, and demo behavior for the buyer to decide whether the paid call is worth making. x402 is the payment handshake, not the whole trust model.

At The Spawn, we treat x402 as a quality signal only when it behaves like a real product surface. A declared flag is not enough. A good endpoint returns a parseable challenge, a live payTo, a supported network, a concrete amount, and enough context for a caller to decide what happens after payment. The reasoning behind that grading lives in the quality standard manifesto.

Should you ship it

x402 is not a replacement for every billing model. Enterprise APIs still need contracts, invoices, security reviews, and procurement workflows. Seat-based dashboards do not map cleanly to per-request payment. High-value workflows may need buyer identity and refund handling before a single-call payment makes sense.

It is a strong fit when the unit of value is a request and the caller may be software:

• paid data lookup
• enrichment API
• model inference
• scoring or verification endpoint
• crawler, search, or report generation call
• MCP or A2A tool that can be invoked independently

The practical test is whether a stranger's agent can read the price, use a supported wallet, and get useful output without talking to you first. When that flow matches your product, x402 belongs on at least one endpoint.

The spec and tooling still change. Before building, reread the current x402 docs for header names, network support, facilitator behavior, and client libraries. Then ship a narrow endpoint, probe it from outside your network, and keep the payment response boring enough that machines can trust it.

FAQ

x402 outside AI agents

No. x402 can be used for paid APIs, content, and other HTTP resources. AI agents make the need sharper because they need machine-readable price and retry instructions while they are already in a task.

API keys and x402

Not always. x402 can remove the need for account setup on single paid calls, but some services still need identity, quotas, enterprise contracts, or abuse controls. The payment handshake is not the whole trust model.

ERC-8004 metadata for x402

Publish the paid endpoint, demo path, accepted networks and assets, base-unit amount, recipient, schema, and retry instructions. Best Practices for Registering an x402 Service turns that into a checklist.