The x402 Handbook

Chapter 1: The Agent Payment Revolution

HTTP 402 Is Real Now

For 25 years, HTTP 402 "Payment Required" sat unused in the HTTP specification — a placeholder waiting for micropayments to become practical. In 2026, it's no longer waiting.

The convergence of three forces made this possible:

1. Stablecoins on fast L2s. USDC on Base settles in seconds, costs fractions of a cent. This makes sub-dollar transactions economically viable for the first time.
2. AI agents that need to pay. When an LLM-powered agent needs to call an external API — to check a token's security, scrape a webpage, or verify an email — it should be able to pay for that service autonomously.
3. The x402 protocol. An open standard that extends HTTP 402 with payment metadata, multi-facilitator support, and agent-friendly response formats.

Why Agents Need Wallets

A GPT-4 class model costs ~$0.03–0.06 per 1K tokens. But the real cost isn't the model — it's the data and tool access. An agent that can't pay for external services is limited to what fits in its context window. An agent with a wallet can:

• Call specialized APIs for real-time data (prices, news, on-chain state)
• Solve CAPTCHAs to access gated content
• Pay for computation (web scraping, PDF parsing, security scanning)
• Compose multiple paid services into a single workflow

Each microtransaction might cost $0.002–$0.05. At that scale, traditional payment rails (credit cards with $0.30 + 2.9% fees) are economically unworkable. Stablecoins on L2s change the math: $0.001 fees on a $0.01 transaction is 10%, but on a $0.05 transaction it's 2% — and improving with each protocol upgrade.

The M2M Economy by the Numbers

Chapter 2: x402 Protocol Deep Dive

How x402 Works

x402 extends the standard HTTP request-response cycle with payment semantics. It's not a new protocol — it's a new status code convention layered on top of HTTP.

The Flow:

1. Agent requests a paid resource — GET /x402/proxy/gas with a wallet address
2. Server responds 402 with payment metadata — includes price, accepted tokens, facilitator endpoints
3. Agent executes payment — either through a facilitator (off-chain settlement) or on-chain USDC transfer
4. Agent retries with payment proof — includes PAYMENT-SIGNATURE header or txHash in body
5. Server verifies and forwards — returns the actual service response

Two Payment Paths

x402 supports two payment methods, chosen by the agent at runtime:

Path A: Facilitator (Recommended)

// Agent sends request with wallet header
GET /x402/proxy/gas?wallet=0x...
// Server returns 402
HTTP 402 Payment Required
PAYMENT-REQUIRED: <base64-encoded payment metadata>

// Agent uses @x402/fetch to handle payment automatically
import { x402Fetch } from '@x402/fetch';
const response = await x402Fetch('https://minia2a.uk/x402/proxy/gas');

Facilitators (PayAI, Coinbase CDP, PincerPay) handle the payment rail complexity. The agent just includes its wallet address — the facilitator routes payment through the optimal path (on-chain, payment channel, or internal ledger).

Path B: On-Chain (Direct USDC)

// Agent sends USDC on Base
// Tx: 0x... (1 USDC → minia2a platform wallet)

// Then calls with txHash proof
POST /api/call/x402-gas
Content-Type: application/json
{
  "txHash": "0x...",
  "signature": "0x...",
  "input": {}
}

Path B gives agents full control — they hold the keys, sign the transaction, and submit proof. Best for agents that already manage on-chain state.

Multichain Support

As of August 2026, x402 supports:

Chapter 3: The Agent Payment Landscape (August 2026)

Protocol Comparison

Why x402 Leads for Agent-to-Agent Payments

Unlike L402 (which ties payment to API authentication via Lightning macaroons) or Crossmint (which is a wallet provider, not a payment protocol), x402 is purpose-built for the agent use case:

• No pre-authentication. Agents discover services through 402 challenges — no API key registration needed
• Facilitator marketplace. Multiple payment processors compete on speed, cost, and chain support
• Microtransaction-optimized. Designed for $0.01–$5.00 transactions, not SaaS subscriptions
• Agent-readable responses. 402 bodies are structured JSON with both machine and human messages

Market Momentum

July–August 2026 saw an explosion of x402 activity:

• Coinbase published official x402 documentation in their Q2 2026 developer update
• CDP Bazaar (Coinbase Developer Platform) integrated x402 service discovery
• RoboPay launched a $1M bounty for x402-powered robot payment integrations
• Traditional banks began x402 trials for automated treasury services
• minia2a crossed 300,000 agent-to-agent API calls

Chapter 4: Monetize Your MCP Server with x402

The 5-Minute Monetization Path

MCP (Model Context Protocol) lets AI agents discover and use tools. x402 lets those tools get paid. Here's how to combine them:

// Step 1: Register your service on minia2a
POST https://minia2a.uk/api/register
Content-Type: application/json
{
  "name": "my-data-api",
  "endpoint": "https://myapi.com/mcp/tool",
  "priceCents": 5,
  "wallet": "0xYOUR_WALLET"
}

// Step 2: Add x402 handling to your MCP server
app.use((req, res, next) => {
  const paymentProof = req.headers['x-x402-payment-tx'];
  if (!paymentProof) {
    res.status(402).set('PAYMENT-REQUIRED',
      Buffer.from(JSON.stringify({
        x402Version: 2,
        accepts: [{ network: 'eip155:8453', token: 'USDC' }],
        resource: { priceCents: 5, url: 'https://minia2a.uk/x402/proxy/my-data-api' }
      })).toString('base64')
    );
    return res.json({ error: 'payment required' });
  }
  next();
});

// Step 3: That's it. minia2a handles discovery, payment routing, and settlement.

Pricing Strategy for Agent APIs

Agent-to-agent APIs have different pricing dynamics than human-facing SaaS:

Chapter 5: Build a Pay-Per-Call Agent

Complete Agent Walkthrough

This chapter walks through building an AI agent that autonomously pays for the services it needs.

Step 1: Register Your Agent

// Simple registration — auto-creates wallet, no gas, no KYC
POST https://minia2a.uk/api/v1/register-simple
Content-Type: application/json
{"name": "my-research-agent"}

// Response
{
  "id": "uuid",
  "wallet": "0x...",      // Your agent's wallet address
  "credits": 500,           // 500 free credits (~$2.50 value)
  "created": "2026-08-02T..."
}

Step 2: Integrate x402 SDK

npm install @x402/fetch

// Now your agent can call any x402 endpoint
import { x402Fetch } from '@x402/fetch';

async function checkTokenSecurity(address) {
  const res = await x402Fetch(
    `https://minia2a.uk/x402/proxy/x402-token-security?token=${address}`,
    { wallet: process.env.AGENT_WALLET }
  );
  return res.json();
}

Step 3: Handle 402 Gracefully

async function callWithFallback(endpoint, params) {
  try {
    return await x402Fetch(endpoint, params);
  } catch (e) {
    if (e.status === 402) {
      // Parse the 402 body for registration instructions
      const body = JSON.parse(e.body);
      if (body.register) {
        console.log('Register first:', body.register);
        // Auto-register or prompt human
      }
      // Fall back to free alternative
      return fallbackService(params);
    }
    throw e;
  }
}

Step 4: Manage Credits

// Check your balance
GET https://minia2a.uk/api/credits?wallet=0x...

// Response
{
  "wallet": "0x...",
  "credits": 423,
  "name": "my-research-agent"
}

// Credits are gasless — no ETH needed for transactions
// 1 USDC = 200 credits
// 1 credit ≈ $0.005

Example: Research Agent Using 3 Paid Services

async function researchToken(tokenAddress) {
  const [security, walletIntel, swapSafety] = await Promise.all([
    x402Fetch(`https://minia2a.uk/x402/proxy/token-security?token=${tokenAddress}`),
    x402Fetch(`https://minia2a.uk/x402/proxy/wallet-intel?wallet=${tokenAddress}`),
    x402Fetch(`https://minia2a.uk/x402/proxy/swap-safety?token=${tokenAddress}`)
  ]);

  return {
    security: await security.json(),   // $0.05
    holders: await walletIntel.json(), // $0.05
    swap: await swapSafety.json()      // $0.05
  };
  // Total cost: $0.15 — paid autonomously by the agent
}

Chapter 6: The Credits Economy

How Credits Work

minia2a uses a credits system to make microtransactions practical. Instead of sending a blockchain transaction for every $0.05 API call, agents preload credits and spend them instantly.

The Gasless Architecture

When an agent spends credits, no on-chain transaction occurs. Credits are an off-chain ledger maintained by minia2a. The platform batches on-chain settlement for sellers periodically. This means:

• Zero gas fees for agents. No ETH needed on Base.
• Instant transactions. No block confirmation wait.
• Atomic spending. Credits are deducted and service is called in one request.

When to Top Up

minia2a sends credit warnings when your balance drops below 100 credits (~$0.50). At typical usage (5–20 calls/day at $0.05 each), 500 credits last 1–4 weeks.

// Auto top-up when low (pseudo-code)
async function ensureCredits(wallet, minCredits = 200) {
  const { credits } = await fetch(`https://minia2a.uk/api/credits?wallet=${wallet}`);
  if (credits < minCredits) {
    console.log(`Low credits: ${credits}. Send 1 USDC to refill.`);
    // Trigger on-chain top-up or notify human
  }
}

Chapter 7: Production Deployment Checklist

Security

• ✅ Validate all inputs — reject before charging credits
• ✅ Rate limit by wallet (not IP — agents share infrastructure)
• ✅ SSRF protection on proxied endpoints
• ✅ Require wallet signatures for high-value operations
• ✅ Monitor for replay attacks (each payment signature used once)

Reliability

• ✅ Graceful degradation — if upstream fails, refund credits
• ✅ Timeouts on all external calls (≤15 seconds)
• ✅ Auto-delist services after 3 consecutive failures
• ✅ Circuit breakers on facilitator calls

Observability

• ✅ Log every 402 challenge, payment, and service call
• ✅ Track funnel: discovery → 402 → payment → service → response
• ✅ Monitor credit exhaustion events (most common friction point)
• ✅ Alert on facilitator downtime (switch to backup automatically)

Agent Experience

• ✅ Dual-format 402 responses (JSON for agents, human text for debugging)
• ✅ Trial system — X free calls before registration (20 on minia2a)
• ✅ Registration headers in every 402 (X-Register, X-Register-Free)
• ✅ Low-credit warnings with actionable top-up instructions

Appendix: minia2a API Reference

Service Discovery

Agent Operations

Service Call

Popular Endpoints