The x402 basic gate: a reference implementation on Cloudflare Workers

Why x402

AI agents cannot use credit cards. They cannot create accounts, pass KYC, or wait for ACH settlement. When an autonomous agent — running inside Claude, a custom LLM pipeline, or a Cloudflare Worker — needs to pay for API access, it has no mechanism to do so with conventional payment rails. The transaction either doesn’t happen or requires a human in the loop, which defeats the purpose of agent autonomy.

x402 is the answer. The protocol revives HTTP 402, a status code reserved since 1995 for “Payment Required” but never standardized. The x402 Foundation, co-stewarded by Coinbase and Cloudflare, defines a machine-readable header format — PAYMENT-REQUIRED — that encodes everything an agent needs to pay for a resource: network, asset, amount, recipient wallet, and facilitator. An x402-aware client receives the 402, constructs a stablecoin payment on Base, and retries with a PAYMENT-SIGNATURE header. Settlement happens in under 200ms. No accounts. No API keys. No human intervention.

The V2 protocol flow

The x402 V2 handshake is five steps.

Step 1 — Unauthenticated request. The client sends a standard HTTP GET to the protected resource. No special headers.

GET /gate HTTP/1.1
Host: api.stable402.com

Step 2 — 402 response with PAYMENT-REQUIRED header. The server returns HTTP 402. The PAYMENT-REQUIRED header value is a Base64-encoded JSON object describing the payment requirements:

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:84532",
    "maxAmountRequired": "1000",
    "resource": "https://api.stable402.com/gate",
    "description": "Access to the x402 basic gate reference endpoint.",
    "mimeType": "application/json",
    "payTo": "0xYourWalletAddress",
    "maxTimeoutSeconds": 60,
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "extra": { "name": "USDC", "version": "2" }
  }]
}

network: "eip155:84532" is Base Sepolia testnet. maxAmountRequired: "1000" is 1000 USDC base units — $0.001 USDC. The asset address is USDC on Base Sepolia.

Step 3 — Payment construction. An x402-aware client (the Coinbase CDP SDK, a custom agent, or any wallet library) decodes the header, signs a USDC transfer to payTo for maxAmountRequired on the specified network, and encodes the signed transaction as a PAYMENT-SIGNATURE header.

Step 4 — Facilitator verification. The Worker forwards the payment signature to the Coinbase CDP facilitator:

POST https://api.cdp.coinbase.com/platform/v2/x402/verify
Content-Type: application/json

{
  "paymentHeader": "<PAYMENT-SIGNATURE value>",
  "paymentRequirements": { ... }
}

The CDP facilitator verifies the on-chain transaction and returns a settlement receipt.

Step 5 — 200 response with payload. On successful verification, the Worker returns HTTP 200 with the resource payload and a PAYMENT-RESPONSE header containing the Base64-encoded settlement receipt.

{
  "message": "Payment verified. Welcome to the x402 basic gate.",
  "endpoint": "api.stable402.com/gate",
  "protocol": "x402 V2",
  "facilitator": "Coinbase CDP",
  "network": "Base Sepolia (testnet)",
  "timestamp": "2026-03-12T00:00:00.000Z",
  "documentation": "https://stable402.com/demos/gate"
}

The Worker implementation

The Worker is a single TypeScript file deployed to the api.stable402.com route via Wrangler. Here is a walkthrough of each section.

The PAYMENT-REQUIRED payload is defined as a constant at module scope. The payTo wallet address and the Bazaar extension metadata live here. The bazaar extension registers the endpoint with the x402 Bazaar discovery layer — making it machine-queryable via the Coinbase CDP /list endpoint and findable by AI agents before they make API calls:

const PAYMENT_REQUIRED_PAYLOAD = {
  x402Version: 2,
  accepts: [{
    scheme: "exact",
    network: "eip155:84532",
    maxAmountRequired: "1000",
    resource: "https://api.stable402.com/gate",
    payTo: process.env.WALLET_ADDRESS,
    extensions: {
      bazaar: {
        discoverable: true,
        outputSchema: { /* JSON Schema for the 200 payload */ }
      }
    }
  }]
};

The 402 branch handles requests with no PAYMENT-SIGNATURE header. The payload is Base64-encoded with a single btoa() call — no external dependencies required:

if (!paymentSignature) {
  const encoded = btoa(JSON.stringify(PAYMENT_REQUIRED_PAYLOAD));
  return new Response(null, {
    status: 402,
    headers: { 'PAYMENT-REQUIRED': encoded, ...CORS_HEADERS },
  });
}

The verification branch forwards the payment to the CDP facilitator and handles failure gracefully. If the facilitator rejects the payment, the Worker returns 402 again — not 500. Payment failure is a valid protocol state, not an application error:

const verifyResponse = await fetch(
  'https://api.cdp.coinbase.com/platform/v2/x402/verify',
  { method: 'POST', body: JSON.stringify({ paymentHeader, paymentRequirements }) }
);

if (!verifyResponse.ok) {
  return new Response(JSON.stringify({ error: 'Payment verification failed' }), {
    status: 402, headers: CORS_HEADERS
  });
}

CORS headers are set to Access-Control-Allow-Origin: * so the endpoint is callable directly from browser clients — including the live demo at stable402.com/demos/gate.

Running it yourself

Clone, configure, and deploy against Base Sepolia testnet in three commands:

# 1. Clone and install
git clone https://github.com/[your-repo]/stable402
cd stable402/api && npm install

# 2. Set your wallet address as a Wrangler secret
npx wrangler secret put WALLET_ADDRESS

# 3. Deploy
npx wrangler deploy

You will need a Cloudflare account with the api.stable402.com subdomain configured as a Worker route. The testnet requires no real funds — Base Sepolia USDC is available from the Circle faucet.

Live endpoint

The live endpoint is at api.stable402.com/gate. Call it directly to see the 402 response:

curl -i https://api.stable402.com/gate

The PAYMENT-REQUIRED response header is the full x402 V2 contract, Base64-encoded. Decode it with base64 -d or the interactive demo at stable402.com/demos/gate.

Stable402.com is part of the StableClarity vocabulary portfolio for on-chain finance infrastructure. Contact: [email protected]