x402: the HTTP payment protocol
agents actually need

The problem: human payment flows do not work for machines

Every major payment flow built over the last 20 years assumes a human being is sitting at a browser. Stripe Checkout, PayPal, Open Banking — they all redirect to a page, ask for credentials, wait for a human to click approve, and redirect back. That model breaks completely when the buyer is an autonomous AI agent.

Agents cannot fill forms. They cannot solve CAPTCHAs. They cannot read SMS codes. They cannot click “confirm” in a mobile banking app. If you ask an agent to pay for an API call using a conventional payment flow, it will fail — not because the agent lacks capability, but because the infrastructure was never designed for non-human actors.

The gap is architectural. What agents need is a payment mechanism that lives entirely inside the HTTP request/response cycle, requires no browser, no human interaction, works at fractions-of-a-cent scale, and completes in under a second. Until 2025, that mechanism did not exist as a standard.

The 402 status code: dormant for 30 years

HTTP status codes are defined in RFC 7231. Most are familiar: 200 OK, 404 Not Found, 500 Internal Server Error. Less familiar is 402: Payment Required. It has appeared in the HTTP specification since 1996 with the following note: “reserved for future use.”

For nearly three decades, 402 sat unused — a placeholder in the spec with no agreed implementation. In 2025, Coinbase published an open protocol that finally defines what 402 actually means in practice. The specification — called x402 — describes a machine-readable payment handshake that any HTTP client can respond to programmatically. No browser. No human. Just HTTP.

The protocol is network and token agnostic. The reference implementation uses USDC on Base (Ethereum L2), but the spec supports any payment rail. It is open source under Apache 2.0.

How x402 works: the six-step flow

The complete x402 exchange happens in six steps. Steps 1 and 2 are a standard HTTP request and error response. Steps 3 and 4 are an on-chain payment signed and submitted by the agent's wallet. Steps 5 and 6 are the paid retry and data delivery. Total elapsed time is typically under one second.

Where x402 sits in the stack

x402 is a protocol layer — it sits between the application (an API endpoint or MCP tool) and the payment rail (USDC on Base). The AI agent consumes the application layer and has no direct knowledge of the settlement layer below x402. This separation of concerns is what makes x402 composable: you can swap the payment rail without changing the API or the agent.

The HTTP exchange: what the messages actually look like

Below is the full HTTP exchange. The initial request is indistinguishable from any API call. The 402 response carries all payment parameters in its body. The paid retry attaches the signed payment payload in the X-Payment header. The 200 response can optionally include a receipt in X-Payment-Receipt.

GET /api/data HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "version": "1",
  "scheme": "exact",
  "network": "base",
  "maxAmountRequired": "1000000",
  "asset": "0x833589...2913",
  "payTo": "0x1234...abcd",
  "description": "API access",
  "maxTimeoutSeconds": 300
}

GET /api/data HTTP/1.1
Host: api.example.com
X-Payment: {
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "payload": {
    "from": "0x5678...efgh",
    "to": "0x1234...abcd",
    "value": "1000000",
    "signature": "0xabc...def"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
X-Payment-Receipt: { "txHash": "..." }

{
  "data": { ... },
  "usage": {
    "charged": "0.001 USDC",
    "remaining_budget": "9.999 USDC"
  }
}

A few things worth noting about this exchange. The maxAmountRequired field is in the asset's base unit — USDC has 6 decimal places, so 1000000 = 1.00 USDC, and 1000 = 0.001 USDC. The asset field is the ERC-20 contract address of the token on the specified network. The payTois the API provider's wallet address.

Why this is the right primitive for agentic payments

x402 has five properties that make it uniquely suited to agent-to-API payments, none of which are shared by any existing payment standard.

Implementation: a minimal Python client

The following is a minimal Python function that handles the full x402 flow — initial request, 402 handling, payment signing, and paid retry. It uses Coinbase's CDP SDK for wallet management and ERC-3009 transfer signing.

import requests, json
from cdp_sdk import Wallet

wallet = Wallet.fetch("your-wallet-id")

def fetch_with_x402(url: str, max_usdc: float = 0.01) -> dict:
    """Fetch any URL, auto-handling x402 payment if required."""

    response = requests.get(url, headers={"Accept": "application/json"})

    if response.status_code == 402:
        details = response.json()

        # Guard: only pay if within budget
        amount_usdc = int(details["maxAmountRequired"]) / 1e6
        assert amount_usdc <= max_usdc, f"Cost {amount_usdc} USDC exceeds budget"

        # Sign an ERC-3009 transfer (no gas, signed off-chain)
        payment = wallet.sign_erc3009_transfer(
            to=details["payTo"],
            amount=details["maxAmountRequired"],
            asset=details["asset"],
            valid_for_seconds=details["maxTimeoutSeconds"],
        )

        # Retry with payment proof in header
        response = requests.get(url, headers={
            "Accept": "application/json",
            "X-Payment": json.dumps({
                "x402Version": 1,
                "scheme": "exact",
                "network": details["network"],
                "payload": payment,
            }),
        })

    response.raise_for_status()
    return response.json()

# Usage — agent calling a paid API
data = fetch_with_x402("https://api.example.com/market-data")
print(f"Fetched {len(data)} records")

The key detail is the ERC-3009 signed transfer on line 16. ERC-3009 is a standard for gasless, off-chain token authorisations — the agent signs a transfer instruction without broadcasting a transaction. The server (or a verification service) validates the signature and settles on-chain. This is what keeps latency under a second: no waiting for transaction confirmation before the API responds.

Reference architecture: x402 on AWS

The diagram below shows how x402 maps onto a production AWS stack — validated against the aws-samples reference repositories. The agent side runs on Amazon Bedrock AgentCore with a Strands-based Python agent. The service side uses CloudFront as the entry point, WAF for bot control and price header injection, and a pair of Lambda@Edge functions to intercept the 402 handshake and settle payment on-chain before forwarding the request to S3.

The x402 Facilitator is a lightweight verification service that sits between Lambda@Edge and Base L2. It handles the cryptographic verification of ERC-3009 signatures and submits the on-chain settlement, so the Lambda functions themselves stay stateless. The dashed verify loop from the Facilitator back to Lambda@Edge on the left represents the async confirmation path — the response is only forwarded once payment is confirmed on-chain.

This architecture is production-ready out of the box. CloudFront handles global edge caching and DDoS protection; WAF gives you bot labelling and the ability to inject dynamic pricing headers before the request reaches Lambda; and the x402 Facilitator decouples payment verification from your origin logic entirely. The agent — built on any framework — only needs to implement the six-step x402 client loop shown earlier.