← All guides

How x402 / HTTP 402 payments work for APIs and agents

HTTP 402 Payment Required sat reserved and unused for decades. The x402 pattern finally puts it to work: APIs and agents that charge per call, with the payment handshake inside HTTP itself.

The 402 flow

1. The client calls the API or tool normally.
2. The server answers 402 Payment Required — not with an HTML error page, but with a machine-readable payment requirement: what to pay, in which asset, on which network, to which address, and how to prove it.
3. The client pays on-chain and retries the request with payment proof attached.
4. The server verifies the payment on-chain and returns the result.

The key property is non-custodial verification: the server checks the blockchain to confirm payment instead of holding the client's keys or funds. Nothing to custody, nothing to leak.

What a machine-readable payment requirement looks like

Below is the actual response shape from Payload's free sample MCP server (an MCP server that charges per tool call). After the free quota is exhausted, premium tools return this instead of a result:

{
  "status": "PAYMENT_REQUIRED",
  "tool": "summarize",
  "free_quota": 5,
  "premium_calls_used": 5,
  "upgrade_url": "https://payloadtools.gumroad.com/l/mcp-monetization-kit",
  "message": "Free quota exhausted (5/5 premium calls used). Attach payment
    to continue, or get the full MCP Monetization Kit to collect real
    per-call USDC payments with the x402 flow: ..."
}

An agent can parse this without any human in the loop: it knows why it was refused (status), which tool (tool), and where to go next (upgrade_url). A production x402 requirement adds the payment details — amount, asset, network, destination address, and the proof format the server accepts.

Plainly stated: the sample server is a demo. It returns this JSON and collects no real payment.

The free-quota-then-pay pattern

The most useful shape for developer tools:

• A small number of calls are free (free_quota, e.g. 5) so anyone can evaluate the tool.
• Call free_quota + 1 returns the machine-readable 402 instead of a result.
• Paying callers attach payment proof and get results; free tools stay free.
• Usage is metered per caller so quotas can't be reset by reconnecting.

Common failures

• Human-readable 402 pages. If the 402 body is HTML prose, agents can't act on it. Machine-readable JSON is the whole point.
• No free quota. Developers won't integrate a paid API they can't try; a small free quota is the evaluation path.
• Accepting payment without verifying on-chain. Trusting a client-claimed transaction ID without checking the chain is how you give the product away.
• Custodying funds to “simplify” verification. Holding keys or balances recreates the security problem non-custodial verification avoids.

Go further

Run the pattern yourself: payload-sample-mcp-server is a free, MIT-licensed MCP server with the quota mechanic built in. For the production version — real per-call USDC collection over x402, persistent usage ledger, official SDK adapter — see the x402 Paid API Starter Kit ($79, one-time). Non-custodial: never holds keys or funds, only verifies payment.