x402 Agent Payments: The Developer's Guide to HTTP-Native Micropayments

The x402 protocol is the breakout infrastructure for agent-to-agent payments in 2026. With 119 million transactions on Base, 35 million on Solana, and approximately $600 million in annualized volume, x402 has become the de facto standard for how AI agents pay for services.

This guide covers what x402 is, how to implement it, and why it matters for anyone building agent-facing services.

What x402 Actually Is

x402 uses the HTTP 402 status code -- "Payment Required" -- that has been in the HTTP specification since 1997 but was never widely implemented. The protocol is simple:

1. An agent sends a GET request to a service
2. The service responds with HTTP 402 and payment details (price, wallet address, chain)
3. The agent sends payment (USDC stablecoin) on-chain
4. The agent re-sends the request with a payment receipt header
5. The service verifies payment and returns the response

// Step 1: Agent discovers service
GET /api/analyze HTTP/1.1

// Step 2: Service responds with payment requirements
HTTP/1.1 402 Payment Required
Content-Type: application/json
X-Payment-Required: 0.10 USDC
X-Payment-Protocol: x402
X-Payment-Chain: base
X-Payment-Address: 0x1234...

{
  "error": "Payment required",
  "protocol": "x402",
  "price_usdc": 0.10,
  "pay_to": "0x1234...",
  "chain": "base",
  "description": "Code quality analysis"
}

// Step 3: Agent pays on-chain, gets receipt

// Step 4: Agent retries with payment proof
POST /api/analyze HTTP/1.1
X-Payment: {"receipt": "0xabc...", "chain": "base", "amount": "0.10"}

// Step 5: Service verifies and responds
HTTP/1.1 200 OK
{"result": { ... }}

Why x402 Matters for Agent Builders

The key insight: x402 separates payment from identity. Traditional APIs require you to sign up for an account, provide an email, agree to terms of service, and get an API key. This works for humans. It does not work for AI agents that need to access hundreds of APIs autonomously.

With x402:

No account required. The agent just pays. No signup, no API key, no enterprise agreement.
Instant settlement. Average settlement time is approximately 2 seconds on Base.
Sub-cent costs. Transaction fees on Layer 2 chains (Base, Arbitrum) are fractions of a cent.
Zero protocol fees. x402 itself charges nothing. You pay network gas only.
Self-discoverable. An agent can find and use your service just by hitting your URL. The 402 response tells it everything it needs to know.


Implementing x402 on Cloudflare Workers

Here is a complete x402 implementation for a Cloudflare Worker. This is production-ready code from a live agent service:

// wrangler.toml
// [vars]
// PAY_TO = "0xYourWalletAddress"

export interface Env {
  PAY_TO: string;
  API_KEYS?: KVNamespace; // Optional: also accept traditional API keys
}

interface RouteConfig {
  handler: (body: any) => any;
  price_usdc: number;
  description: string;
}

const routes: Record<string, RouteConfig> = {
  '/api/analyze': {
    handler: analyzeCode,
    price_usdc: 0.10,
    description: 'Analyze code for quality issues',
  },
  '/api/decompose': {
    handler: decomposeTask,
    price_usdc: 0.05,
    description: 'Break a task into atomic subtasks',
  },
};

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const route = routes[url.pathname];

    if (!route) {
      return new Response('Not found', { status: 404 });
    }

    // GET requests return payment requirements (self-discovery)
    if (request.method === 'GET') {
      return new Response(JSON.stringify({
        error: 'Payment required',
        protocol: 'x402',
        price_usdc: route.price_usdc,
        pay_to: env.PAY_TO,
        chain: 'base',
        description: route.description,
      }), {
        status: 402,
        headers: {
          'Content-Type': 'application/json',
          'X-Payment-Required': route.price_usdc + ' USDC',
          'X-Payment-Protocol': 'x402',
          'X-Payment-Chain': 'base',
          'X-Payment-Address': env.PAY_TO,
        },
      });
    }

    // POST requests must include payment or API key
    const paymentHeader = request.headers.get('X-Payment');
    const apiKey = request.headers.get('X-API-Key');

    if (paymentHeader) {
      const verified = await verifyPayment(paymentHeader, route.price_usdc);
      if (!verified) {
        return new Response('Payment verification failed', { status: 402 });
      }
    } else if (apiKey && env.API_KEYS) {
      const keyData = await env.API_KEYS.get(apiKey);
      if (!keyData) {
        return new Response('Invalid API key', { status: 401 });
      }
    } else {
      return new Response(JSON.stringify({
        error: 'Payment or API key required',
        protocol: 'x402',
        price_usdc: route.price_usdc,
        pay_to: env.PAY_TO,
      }), { status: 402 });
    }

    const body = await request.json();
    const result = route.handler(body);
    return new Response(JSON.stringify(result), {
      headers: { 'Content-Type': 'application/json' },
    });
  },
};

The Economics of x402 Services

Here is the unit economics for a typical x402-enabled agent service:


Metric
Value
Price per call
$0.10
LLM API cost per call (routed)
$0.02
Cloudflare Workers cost
$0.00 (free tier: 100K req/day)
x402 protocol fee
$0.00
Network gas (Base L2)
~$0.001
Profit per call
$0.079 (79% margin)


At 100 calls per day, that is $237/month revenue on $60/month in LLM costs. At 1,000 calls/day, it is $2,370/month revenue.

The critical cost optimization: use model routing to keep LLM costs under $0.02/call. Route 80% of requests to cheaper models (Haiku at $0.25/MTok) and only 20% to expensive models (Sonnet at $3/MTok).

Agent Wallet Infrastructure

For your agent to PAY via x402 (not just receive), it needs a wallet. The current stack:


ERC-8004: Trust and identity for AI agents via three on-chain registries (Identity, Reputation, Validation)
EIP-7702: Allows wallet accounts to temporarily transform into smart contract wallets
HD Wallets: Hierarchical Deterministic wallets for key management
Programmable spending limits: Your agent can only spend up to N USDC per day/week/month


In a 14-week beta, over 1,000 participants created 9,500+ agents executing 187,000 autonomous transactions.

The Agent Marketplace Landscape (2026)

Where agents are actually earning money right now:


Circle Agent Marketplace: 32 services, 349 endpoints, x402-native
BuildMVPFast: 80 services, 894 agents, 31,000 transactions per week
execution.market: On-chain USDC escrow on Base, microtasks at $0.05-0.50
dealwork.ai: Task marketplace, $1-200 per task
opentask.ai: USDC escrow, $5-400+ tasks


Reality check: the ecosystem processed approximately $165M+ in total x402 transaction volume, but individual agent earnings remain modest. The profitable layer today is selling infrastructure to agents, not being an agent.

Dual Revenue Strategy: x402 + Stripe

The smart approach is not x402 OR Stripe -- it is both:


x402: Captures agent callers who need instant, no-signup access. This is the growth bet.
Stripe: Captures human developers who want monthly subscriptions. This is the revenue now.


// Dual payment validation
async function validateAccess(request: Request, env: Env): Promise<boolean> {
  // Check x402 payment (agent callers)
  const payment = request.headers.get('X-Payment');
  if (payment) {
    return await verifyX402Payment(payment);
  }

  // Check API key (Stripe subscribers)
  const apiKey = request.headers.get('X-API-Key');
  if (apiKey) {
    return await verifyApiKey(apiKey, env.API_KEYS);
  }

  return false;
}

This dual approach means you are not betting on x402 adoption alone. If agent payments scale as projected ($3-5 trillion by 2030 according to McKinsey), your x402 endpoint is ready. If they do not, your Stripe revenue sustains the service.

Getting Started


Deploy a Cloudflare Worker with the x402 payment flow above
Set up a Base wallet (Coinbase Wallet or any EVM wallet)
Configure your PAY_TO address in wrangler.toml
Add your service to the Circle Agent Marketplace
Test with the x402 CLI tool or a simple curl request


The total cost to launch: $0. Cloudflare Workers free tier, Base wallet free, x402 protocol free. You start earning from the first verified payment.

Building an agent service? The Complete Guide to Agent Orchestration Patterns covers the 15 patterns you need for production reliability.