What is x402? The HTTP payment protocol for AI agents, with a live example

Updated 2026-11-09

x402 is an open payment protocol that lets any HTTP client, including an AI agent, pay for an API per request in stablecoins such as USDC. It reuses the status code 402 Payment Required, which HTTP reserved decades ago and almost nobody used. No account, no API key, no card: the server states its price, the client pays, and the same request returns the data. Coinbase introduced x402 on May 6, 2025 (Coinbase).

Why x402 matters for AI agents

An agent cannot fill a signup form, pass a captcha or hold a company card. It can hold a wallet. With x402, a paid API becomes something an agent can find, price and buy on its own, one call at a time, for amounts as small as a fraction of a cent. That is what people mean by agentic payments or machine-to-machine (M2M) commerce.

How x402 works, step by step

1. The client calls the API like any other HTTP request.
2. The server answers 402 Payment Required with a PAYMENT-REQUIRED header: the price, the wallet to pay (payTo), the token and the networks it accepts.
3. The client signs a payment for one of the accepted options and sends the same request again with a PAYMENT-SIGNATURE header.
4. The server has a facilitator verify the payment, does the work, then has the facilitator settle it on chain.
5. The server returns the data with a PAYMENT-RESPONSE header that confirms the settlement.

The payment adds a second or two to the call. An x402 server can settle only after a successful response, so a call that fails costs the buyer nothing (How x402 works).

What is an x402 facilitator?

A facilitator is the service that checks a payment and settles it on chain, so the API seller does not have to run blockchain infrastructure. The seller's server sends the signed payment to the facilitator to verify it, then to settle it.

Coinbase runs the CDP facilitator. In November 2026 it supports Base, Polygon, Arbitrum, Monad, World and Solana. The first 1,000 on-chain transactions each month are free, then each costs $0.001, and verification is always free (CDP facilitator).

The facilitator handles the settlement network fee, so the buyer only needs USDC. On Solana, for example, a wallet holding only USDC, with no SOL, can pay an x402 API.

x402 v1 vs v2

x402 v2 shipped on December 11, 2025 (x402.org). The main changes:

• Payment data moves to the PAYMENT-REQUIRED, PAYMENT-SIGNATURE and PAYMENT-RESPONSE headers, and the older X-* headers are dropped.
• Networks and tokens are named the same way everywhere (for example eip155:8453 for Base), so one API can accept Base and Solana at the same time.
• A discovery extension lets facilitators index paid endpoints automatically. This is how catalogs such as the Coinbase x402 Bazaar stay current.
• Extensions let builders add features without forking the spec.

The reference SDKs stay compatible with v1.

Who is behind x402

Coinbase created x402. On September 23, 2025, Cloudflare and Coinbase announced the x402 Foundation to develop it as an open Internet standard (Cloudflare). Anyone can run an x402 server, client or facilitator.

Try it: see a real 402 response (free)

Tolca sells web search and business checks over x402. This call costs nothing: without a payment, it only returns the price.

curl -i -X POST https://tolca.tonbot.ca/v1/web-search \
  -H "content-type: application/json" \
  -d '{"query":"x402 protocol"}'

You get a 402 status and a PAYMENT-REQUIRED header. It is base64-encoded JSON: decode it to read the price ($0.008), the payTo wallet and the accepted networks (Base and Solana).

Pay for a call with the x402 SDK

In Node.js 20 or later, install the v2 client with npm install @x402/fetch @x402/evm viem, and use a wallet that holds a little USDC on Base.

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY);
const client = new x402Client().register("eip155:8453", new ExactEvmScheme(account));

// Spending guard: refuse anything above 0.01 USDC (amounts use 6 decimals)
client.onBeforePaymentCreation(async ({ selectedRequirements: r }) =>
  Number(r.amount) <= 10000 ? undefined : { abort: true, reason: "too expensive" });

const pay = wrapFetchWithPayment(fetch, client);
const res = await pay("https://tolca.tonbot.ca/v1/web-search", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ query: "x402 protocol", read: 2 }),
});
console.log(await res.json());

Keep a guard like this in any agent that pays: check the price, the network and the payTo before signing. For sellers it has never paid, an agent can also call payment-check ($0.01), which screens the payTo wallet against OFAC sanctions, confirms the asset is the official USDC and returns a signed receipt.

Where to find x402 APIs

• x402scan: an explorer of x402 sellers and their payments.
• nohumans.directory: a registry that tests listings and buys from many of them to check they deliver.
• To list your own API, see How to get your x402 API found by AI agents.

FAQ

Is x402 only for crypto? Today most x402 payments use USDC on Base or Solana. The v2 spec is written so that other rails, such as cards or bank transfers, can follow the same flow.

Does the buyer need an account? No. A wallet with USDC is enough; the server never sees an email or a card.

What does x402 cost? The seller sets the price per call. Settlement fees are small: on the CDP facilitator, $0.001 per transaction after 1,000 free each month.

Is HTTP 402 new? No. HTTP has listed 402 Payment Required since the 1990s, "reserved for future use". x402 gives it a concrete meaning.