How AI Agents Use x402 for Payments

The Challenge

AI agents are autonomous programs that take actions on behalf of users. They browse the web, call APIs, and chain services together to complete tasks. But most paid APIs require account creation, API keys, and billing setup: steps that assume a human in the loop. An agent that needs a new API mid-task hits a wall.

x402 removes that wall. Because payment instructions are embedded in HTTP responses, an agent with a funded wallet can discover, evaluate, and pay for any x402 service without human intervention.

Step-by-Step Flow

Here is how an AI agent interacts with an x402-enabled API:

Step 1: Discovery. The agent finds a service endpoint, either from a directory like the x402 List service directory, a search engine, or a tool manifest. It sends a standard HTTP request.

Step 2: Payment Required. The server returns HTTP 402. In x402 v2, decode the base64-encoded JSON in the PAYMENT-REQUIRED response header; in v1, read the JSON response body. Each entry in the accepts array is one accepted payment option: the scheme, the network, the amount in atomic units of the asset (USDC has 6 decimals, so 1000 means $0.001), the asset contract address, and the payTo address. The decoded v2 JSON looks like this:

{
  "x402Version": 2,
  "resource": { "url": "https://translate-402.example.com/api/translate?text=hello&lang=fr" },
  "error": "Payment required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "1000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xabc...def",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}

Step 3: Evaluate. The agent parses accepts[] and picks an option it can pay: a network and asset its wallet holds. Then it checks its budget policy. Is the price within the per-request limit? Is the total spend for this task within budget? If so, it proceeds. If not, it skips the service or asks the user for approval.

Step 4: Sign. The agent constructs a signed payment payload for the chosen option. On EVM networks this is an EIP-3009 transferWithAuthorization signature: an off-chain authorization that lets the exact amount move from the agent's wallet to the payTo address. The agent does not broadcast a transaction itself.

Step 5: Retry with payment. The agent retries the original request with the signed payload, base64-encoded, in PAYMENT-SIGNATURE for x402 v2 or X-PAYMENT for v1. This example uses v2:

GET /api/translate?text=hello&lang=fr HTTP/1.1
Host: translate-402.example.com
PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6Miwi...

Step 6: Receive data. The server verifies the payload, settles the payment on-chain through its facilitator, and returns the requested data with a 200 response. Settlement details are in PAYMENT-RESPONSE for x402 v2 or X-PAYMENT-RESPONSE for v1.

Code Example

Here is a simplified agent loop in pseudo-code:

async function x402_request(url, options) {
  // 1. Make the initial request
  let response = await fetch(url, options);

  // 2. Check if payment is required
  if (response.status !== 402) {
    return response;
  }

  // 3. Read v2 terms from the header or v1 terms from the body
  const requiredHeader = response.headers.get("PAYMENT-REQUIRED");
  const requirements = requiredHeader
    ? JSON.parse(atob(requiredHeader))
    : await response.json();
  const { x402Version, accepts } = requirements;
  const paymentHeader = x402Version === 2 ? "PAYMENT-SIGNATURE"
    : x402Version === 1 ? "X-PAYMENT" : null;
  if (!paymentHeader) {
    throw new Error("Unsupported x402 version");
  }

  // 4. Pick an option the wallet can pay (network + asset)
  let option = accepts.find((o) =>
    wallet.supports(o.network, o.asset)
  );

  // 5. Check agent budget policy (amount is in atomic units)
  if (!option || !budget.allows(option)) {
    throw new Error("No payable option within budget");
  }

  // 6. Use a version-aware signing helper to construct the payload
  //    (EVM: EIP-3009 transferWithAuthorization)
  let payload = await wallet.signPayment(requirements, option);

  // 7. Retry with the signed payload, base64-encoded
  const headers = new Headers(options?.headers);
  headers.set(paymentHeader, btoa(JSON.stringify(payload)));
  return await fetch(url, { ...options, headers });
}

Budget Controls

Responsible agent design includes spending limits. Agents should enforce per-request caps, per-task budgets, and per-session maximums. The x402 flow makes this straightforward because every cost is declared upfront in the 402 response, before any money moves. The agent always knows the price before it pays.

Why This Matters

x402 turns the web into a marketplace that machines can navigate autonomously. An agent can chain ten different paid APIs in a single task (translation, image generation, code review, data lookup) without any of them sharing an account system. Each interaction is an independent, atomic HTTP exchange. This composability is what makes x402 a foundational protocol for the agentic web. Developers can also integrate with the x402 List API to programmatically discover services.