The x402 protocol, explained

HTTP 402 Payment Required has been a reserved status code since 1997. For nearly thirty years it sat unused — there was no agreed-upon way for a server to say what payment it wanted, and no agreed-upon way for a client to pay. x402 fills that gap. It is a tiny open spec that turns 402 into a real handshake, designed for the case where the client is not a human with a credit card but an autonomous AI agent acting on a budget.

The whole protocol is two HTTP round trips, a base64-encoded payload, and an on-chain settlement. There is no account, no API key, no Stripe Checkout iframe. An agent can discover a priced endpoint, pay for it, and consume the response in under a second.

The handshake in one diagram

The first call is unauthenticated. The server responds with 402 and a machine-readable accepts payload describing what it will take.

GET /api/public/v1/{endpoint}?{params} HTTP/1.1

→ HTTP/1.1 402 Payment Required
   Content-Type: application/json

   {
     "x402Version": 1,
     "error": "payment_required",
     "accepts": [{
       "scheme": "exact",
       "network": "base",
       "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
       "maxAmountRequired": "5000",
       "payTo": "0x05e8...b7b7",
       "resource": "https://marketplaceforaiagents.com/api/public/v1/{endpoint}",
       "extra": { "name": "USDC", "version": "2" }
     }]
   }

The agent picks an accepts entry it can satisfy, signs an EIP-3009 transferWithAuthorization on the USDC contract, base64-encodes the signed payload, and resends the request with an X-PAYMENT header.

GET /api/public/v1/youtube-transcripts?video_id=abc123 HTTP/1.1
X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiYmFzZSIsLi4u

→ HTTP/1.1 200 OK
   X-PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4Li4uIn0=
   Content-Type: application/json

   { "video_id": "abc123", "lang": "en", "transcripts": [...] }

The X-PAYMENT-RESPONSE header is a base64 receipt the agent stores for its own ledger. The transaction hash links back to a real on-chain transfer on Base.

Why EIP-3009 instead of a regular ERC-20 transfer

EIP-3009 is the part that makes the whole thing work in a single HTTP request. A normal ERC-20 transfer would require the agent to broadcast a transaction itself, wait for confirmation, and only then call the API. EIP-3009 introduces transferWithAuthorization: the holder signs a typed message off-chain, and any third party can submit it on-chain on their behalf.

In x402 the third party is a facilitator — a service the API operator trusts to verify the signature, broadcast the transfer, and report back. The agent never touches gas. The facilitator pays the gas in ETH on Base, then collects the USDC. Because Base settlement is sub-second and gas is fractions of a cent, the whole flow feels like a normal HTTP call.

Discovery: /.well-known/x402

An x402 server publishes a manifest at /.well-known/x402 listing its endpoints, prices, networks, and OpenAPI spec. Agents — and agent API marketplace crawlers — read this file to auto-generate tools.

{
  "name": "Marketplace for AI Agents",
  "networks": ["base", "base-sepolia"],
  "endpoints": [
    { "id": "youtube-transcripts", "url": "https://.../api/public/v1/youtube-transcripts" },
    { "id": "google-search", "url": "https://.../api/public/v1/google-search" },
    { "id": "google-shopping", "url": "https://.../api/public/v1/google-shopping" }
  ],
  "prices": [
    { "network": "base", "asset": "0x8335...", "amountAtomic": "5000" }
  ]
}

Pair this with an OpenAPI 3.1 spec and an agent framework can wire your endpoint into a tool call automatically, including the X-PAYMENT header logic.

Where x402 fits in the agentic commerce stack

x402 is the settlement layer. Above it you have agent runtimes (LangChain, the Vercel AI SDK, MCP servers) that decide when to spend. Below it you have the chain (Base mainnet today, others later) that finalizes the transfer. The protocol itself is intentionally thin — it does not specify what kind of agent is calling, what business logic the API runs, or how the operator reports revenue. That is the point. It is the HTTP 402 of the agent economy: a small interoperable primitive that lets the rest of the stack assume payment just works.