Protocol

What is x402?

x402 is a payment protocol that leverages HTTP status code 402 (Payment Required) to enable real-time, per-request micropayments for AI agents and APIs. Instead of traditional subscription models, x402 allows services to charge exactly for what is consumed.

Per-request micropayments

Session key authentication

On-chain USDC settlement

No wallet popups after setup

Transparent pricing headers

Works with any HTTP API

Standard

Why HTTP 402 Payment Required matters

HTTP 402 was reserved in the HTTP/1.1 specification for “future use” as a payment mechanism. For decades, it sat unused while the web relied on cookies, API keys, and subscription billing.

With the rise of AI agents and programmable money, HTTP 402 finally has its purpose: a native, machine-readable payment layer for the internet.

http

HTTP/1.1 402 Payment Required
X-Price: 0.05
X-Currency: USDC
X-Network: Base
X-Recipient: 0xAgentWallet...7eF2
X-Payment-Protocol: x402/1.0

{
  "message": "Payment required to execute agent",
  "price": "0.05 USDC",
  "accepts": ["session-key", "direct-payment"]
}

Authentication

Session Key Flow

Session keys eliminate the need for wallet popups on every request. The user signs once, and subsequent requests are authenticated automatically.

User connects wallet

Standard Web3 wallet connection via RainbowKit or ConnectKit.

Sign session key

User signs a message that creates a scoped session key with spending limits and expiry.

Attach to requests

Session key is included in X-Session-Signature header on every subsequent request.

Auto-settlement

x402 protocol validates the session and settles USDC on-chain automatically.

Lifecycle

Payment Lifecycle

text

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Frontend   │────▶│  Cloudflare  │────▶│    Agent     │
│   (Next.js)  │     │   Worker     │     │   Engine     │
└──────────────┘     └──────────────┘     └──────────────┘
       │                    │                     │
       │  1. Send request   │  2. Validate        │
       │  + session key     │  session + Turnstile │
       │                    │                     │
       │                    │  3. Forward to      │
       │                    │  agent engine        │
       │                    │                     │
       │                    │  4. Execute AI      │
       │                    │  command ◀──────────│
       │                    │                     │
       │                    │  5. x402 settlement │
       │                    │  USDC → Agent Wallet│
       │                    │                     │
       │  6. Return result  │                     │
       │◀───────────────────│                     │
       │  + payment proof   │                     │
       │                    │                     │

Infrastructure

Cloudflare Worker Example

typescript

// Cloudflare Worker - x402 Payment Gateway
export default {
  async fetch(request: Request, env: Env) {
    // 1. Validate Turnstile token
    const turnstileToken = request.headers.get("cf-turnstile-response");
    const turnstileValid = await validateTurnstile(turnstileToken, env);
    if (!turnstileValid) {
      return new Response("Bot detected", { status: 403 });
    }

    // 2. Validate session key
    const sessionSig = request.headers.get("x-session-signature");
    const userWallet = request.headers.get("x-user-wallet");
    const session = await validateSession(sessionSig, userWallet);
    if (!session.valid) {
      return new Response(JSON.stringify({
        message: "Payment required",
        price: "0.05 USDC",
        network: "base",
      }), { status: 402 });
    }

    // 3. Forward to agent engine
    const agentResponse = await fetch(env.AGENT_ENGINE_URL, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-session-signature": sessionSig,
        "x-user-wallet": userWallet,
        "x-price": "0.05",
      },
      body: request.body,
    });

    // 4. Return result with payment proof
    const result = await agentResponse.json();
    return new Response(JSON.stringify({
      ...result,
      payment: {
        status: "settled",
        amount: "0.05 USDC",
        txHash: result.txHash,
      },
    }), {
      headers: { "Content-Type": "application/json" },
    });
  },
};

API

API Reference

POST/run-agent

Execute an AI agent command with x402 payment.

Headers

x-session-signaturestringSigned session key from wallet

x-user-walletstringUser's wallet address

x-pricestringAgreed price in USDC

cf-turnstile-responsestringCloudflare Turnstile token

bash

curl -X POST https://api.clawoud.com/run-agent \
  -H "Content-Type: application/json" \
  -H "x-session-signature: 0xSIGNATURE..." \
  -H "x-user-wallet: 0x1a2B...9cD4" \
  -H "x-price: 0.05" \
  -d '{"command": "Analyze market trends for ETH"}'

json

{
  "success": true,
  "result": {
    "output": "ETH market analysis complete...",
    "tokensUsed": 342,
    "latency": "45ms"
  },
  "payment": {
    "status": "settled",
    "amount": "0.05 USDC",
    "network": "base",
    "txHash": "0xabc123..."
  }
}