What is x402? HTTP 402 payments for APIs and AI agents

x402 is an open payment protocol built on the HTTP status code 402 Payment Required. A client requests a resource; the server answers 402 with a machine-readable price; the client signs a stablecoin payment for exactly that amount and retries the same request with the proof attached; the server checks it, returns the data and settles. No sign-up, no API key, no invoice at the end of the month.

That shape suits AI agents, which can hold a wallet but cannot fill in a signup form. TickerLayer runs x402 in production for market data, so this guide uses real responses from https://x402.tickerlayer.com instead of a diagram of a hypothetical API. If your agent already has a TickerLayer account, the financial MCP server is usually the better door; the comparison near the end shows where each one wins.

The x402 protocol round trip, step by step

The first move is an ordinary GET with nothing attached. Here is the production gateway answering it:

curl --include 'https://x402.tickerlayer.com/v1/stocks/quote/US:KO'

HTTP/2 402
content-type: application/json; charset=utf-8
cache-control: no-store
payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly94NDAy...

{"error":"payment_required","message":"This TickerLayer resource requires an x402 payment.","endpoint":"stocks.quote"}

The JSON body is for humans reading logs. The part a client acts on is the PAYMENT-REQUIRED header: base64-encoded JSON that names the price, the network and who gets paid. The client decides whether it is willing to pay, signs a transfer authorization with its wallet, and sends the identical request again with a PAYMENT-SIGNATURE header. Only then does the gateway fetch, validate and return the data.

Anatomy of an HTTP 402 challenge

You can read a challenge without any x402 library. This pipeline pulls the header out of a response and decodes it:

curl -s -D - -o /dev/null 'https://x402.tickerlayer.com/v1/stocks/quote/US:KO' \
  | awk 'tolower($1)=="payment-required:" {print $2}' \
  | tr -d '\r' | base64 --decode | python3 -m json.tool

{
  "x402Version": 2,1
  "error": "Payment required",
  "resource": {
    "url": "https://x402.tickerlayer.com/v1/stocks/quote/US:KO",
    "mimeType": "application/json"
  },
  "accepts": [{2
    "scheme": "exact",3
    "network": "eip155:8453",4
    "amount": "10000",5
    "asset": "0x8335...2913",6
    "payTo": "0x7Dc9...0dAC",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USD Coin", "version": "2" }
  }],
  "extensions": {
    "payment-identifier": { "info": { "required": true } }7
  }
}

The full header also carries discovery metadata: the route template (/v1/stocks/quote/:symbol), the path parameters of this request, a JSON Schema for the input and an example of the output. An agent or a marketplace can list and describe the resource from the challenge alone, without reading documentation first.

Pay from code: a Node.js client with a spending cap

The x402 client libraries handle signing and the retry. Your job is to decide what the client may pay. This is the example from the x402 page, pointed at US:KO: it accepts only the exact scheme on the configured network, refuses anything above 100,000 units ($0.10), and attaches a payment identifier before signing.

// npm install @x402/fetch @x402/evm @x402/extensions viem
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import {
  appendPaymentIdentifierToExtensions,
  generatePaymentId,
} from "@x402/extensions/payment-identifier";
import { privateKeyToAccount } from "viem/accounts";

const baseUrl = process.env.X402_BASE_URL ?? "https://x402.tickerlayer.com";
const network = process.env.X402_NETWORK ?? "eip155:8453";
const privateKey = process.env.X402_AGENT_PRIVATE_KEY;
if (!privateKey) throw new Error("X402_AGENT_PRIVATE_KEY is required");

const account = privateKeyToAccount(privateKey);
const client = new x402Client((version, requirements) => {
  if (version !== 2) throw new Error("Unsupported x402 version");
  const selected = requirements.find((requirement) => {
    const amount = BigInt(requirement.amount);
    return requirement.scheme === "exact" &&
      requirement.network === network && amount > 0n && amount <= 100_000n;
  });
  if (!selected) throw new Error("No approved payment requirement");
  return selected;
});

client.register(network, new ExactEvmScheme(account));
const paymentId = generatePaymentId("tl_agent_");
client.onBeforePaymentCreation(async ({ paymentRequired }) => {
  if (!paymentRequired.extensions) throw new Error("Payment ID not declared");
  appendPaymentIdentifierToExtensions(paymentRequired.extensions, paymentId);
});

const paidFetch = wrapFetchWithPayment(fetch, client);
const response = await paidFetch(baseUrl + "/v1/stocks/quote/US:KO");
if (!response.ok) throw new Error(`x402 request failed: ${response.status}`);
console.log(await response.json());

Point it at the sandbox first: set X402_BASE_URL=https://x402-testnet.tickerlayer.com and X402_NETWORK=eip155:84532, fund a throwaway wallet with test USDC, and the same code pays with play money. A successful call prints the same JSON shape the REST quote endpoint returns:

{"symbol":"US:KO","bid":88.11,"ask":88.3,"bid_size":400,"ask_size":200,"timestamp":1790590887491}

Production and sandbox gateways

Both gateways publish /ready for health and /catalog for every resource with its price policy. A readiness result describes the gateway at the moment you checked; it is not a promise of uninterrupted availability, and it does not replace reading the 402 challenge before you pay.

What each call costs

Settlement happens only after the gateway has prepared a valid response. Bad parameters, upstream failures, invalid JSON and empty data stop before any charge, and a retry that reuses the same payment identifier gets the stored response rather than a second bill. Using that identifier for a different request is rejected.

x402, an API key plan or MCP: pick the right door

The deciding comparison is cost at volume. 250,000 quote calls through x402 cost $2,500. An Individual crypto plan includes 250,000 REST calls a month for $49, and the free tier includes 3,000 REST requests a month with no card. x402 wins when calls are rare, bursty or made by software that has a wallet and no account; a plan wins the moment usage is steady. And if the agent is a chat assistant you use yourself, connecting Claude through MCP with a key or an OAuth sign-in is simpler than giving it a wallet.

Whichever door you use, the same engineering applies: the gateway enforces per-endpoint rate limits, so an agent that fans out needs 429 handling with backoff, and it needs to understand the fields it buys. The market data API guide explains quotes, snapshots, bars and timestamp semantics.

Guardrails before you give an agent a wallet

In an agent, x402 belongs inside a tool your code owns, not in the model. The model asks for data; the tool reads the challenge, applies your policy and pays or refuses:

1. 1Model requests dataThe agent calls your paid_get tool with a path such as /v1/forex/quote/EURUSD.
2. 2Tool reads the priceThe unpaid request returns 402; the tool decodes the amount and network.
3. 3Policy decidesScheme, network, per-call cap and the remaining daily budget are checked in code.
4. 4Pay, cache, returnThe tool pays, stores the response and hands the JSON back to the model.

The same principle runs through the AI trading bot tutorial: a model can propose, but deterministic code decides what actually happens, whether that is a paper order or a payment.

Selling an API over x402: what the server must get right

From the seller side, API monetization with x402 looks simple: return 402, verify, settle. The details decide whether buyers trust it. These are the choices the TickerLayer gateway makes, and they are a reasonable bar for any paid API:

• Price per route, not per account. A quote and a 1,000-bar history do not cost the same to serve, so the price scales with the work, and a bulk request prices each extra item.
• Prepare first, settle second. Fetch and validate the data before taking the money. An empty or malformed response should never be billed.
• Idempotent retries. Networks drop responses. Binding a payment identifier to one canonical request lets a client retry safely and get the stored answer.
• A separate sandbox. Test money on a test network, same paths and prices, so integrations are proven before real funds move.
• Public readiness and catalog. Buyers, and their agents, should be able to see what is for sale and whether the gateway is healthy before they sign anything.

Why HTTP 402 sat unused for so long

HTTP/1.1 listed 402 as "reserved for future use" and never said what a payment should look like. Card payments need accounts and cost more to process than a one-cent request is worth, so APIs built monetization around keys and monthly plans instead. Stablecoins on low-fee networks made a one-cent transfer practical, and x402 standardized the headers around it.

Nothing in the protocol is specific to market data. Any HTTP API can price a route this way, which is why x402 keeps coming up in API monetization and agentic payments discussions. What a data API adds is the validation step: a buyer should only pay for a response that is correct and complete, and a gateway that settles before checking the data gets that backwards. TickerLayer data stays derived and indicative whichever way you pay; see the market data disclaimer.