Botvatar/ Protocols/ x402

x402: paying over plain HTTP

x402 turns 402 Payment Required — a status code reserved in the HTTP spec and left unused for about thirty years — into a working payment handshake. No checkout page, no session, no account. A request, a price, a payment, the thing you asked for.

Why anyone bothered

Every existing way to charge for an API assumes a human did something first: signed up, entered a card, generated a key, agreed to terms. That's fine when a person is driving. It falls apart the moment the buyer is a piece of software that woke up thirty seconds ago and needs one thing.

The alternative has always been sitting in the spec. 402 Payment Required was reserved for exactly this and never standardised into anything usable. x402, created at Coinbase, finally defines what the server should say and what the client should send back.

The exchange

Three steps, and the first two are just HTTP:

1. The client requests a resource with no payment attached. The server replies 402 and describes what it wants — amount, asset, network, and where to pay.
2. The client constructs a payment, signs it, and repeats the same request with the payment attached as a header.
3. The server verifies and settles — usually by handing the payload to a facilitator so it needs no blockchain connectivity of its own — then returns 200 and the resource, with a receipt header.

→  POST /api/agent/generate
←  402 Payment Required
   PAYMENT-REQUIRED: { amount, asset, network, payTo }

→  POST /api/agent/generate
   PAYMENT-SIGNATURE: <signed payment payload>
←  200 OK
   PAYMENT-RESPONSE: <settlement receipt>
   · signed identity card

Header names per Cloudflare's Agents SDK implementation. Botvatar's route shape is not final.

The three headers

• PAYMENT-REQUIRED — the server's challenge. What it costs and how to pay it.
• PAYMENT-SIGNATURE — the client's signed payment payload, sent on the retry.
• PAYMENT-RESPONSE — the receipt, returned alongside the resource.

Payments settle in USDC, across Base, Ethereum, Solana and other networks. Amounts are small by design — this is built for the sub-dollar machine purchase that a card-based checkout could never carry economically.

Why this stack, specifically

Botvatar runs on Cloudflare Workers, and Cloudflare ships x402 support natively — x402-hono middleware for HTTP Workers, plus withX402 and paidTool for MCP servers, and withX402Client on the client side to handle the 402 retry automatically. Cloudflare is also a founding member of the x402 Foundation alongside Coinbase.

In plain terms: the payment layer is a middleware import on the stack this product already runs on, not a rebuild.

What it means for a botvatar

Today a person signs in, gets a code by email, and renders a card. With x402 the agent does it unattended: it asks for a card, is told the price, pays, and receives a signed identity card it can then present anywhere. No account, no checkout page, nobody watching.

That closes a loop that's currently open. An agent that can pay for things should be able to prove who it is when it does — and it shouldn't need a human to hold its hand for either half.