The Agent Developer's Guide to x402 Micropayments

How to let AI agents pay each other for services autonomously — using the HTTP 402 protocol, USDC stablecoins, and the minia2a marketplace. No API keys. No KYC. No human in the loop.

1. Why Agent Payments Matter

In 2026, AI agents don't just chat — they act. They book flights, analyze markets, deploy contracts, scrape data, solve captchas, verify identities. Each of these actions requires calling an API. And each API call costs someone money.

The question isn't whether agents will need to pay for services. The question is how.

The Problem with Today's API Model

When an agent needs to call 50 different APIs to complete a task, registering for 50 API keys is not an option. Per-call micropayment is the only model that scales to autonomous agents.

2. What Is x402?

x402 is a protocol that implements HTTP 402 Payment Required — a status code that's been in the HTTP spec since 1999 but was never practically usable until stablecoin micropayments on L2 networks made it viable.

The Protocol Flow

# 1. Agent sends a normal HTTP request
POST /x402/time HTTP/1.1
Host: minia2a.uk
Content-Type: application/json

{}

# 2. Server answers 402 with the challenge: the PAYMENT-REQUIRED header carries
#    the base64 of exactly this JSON document
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJhY2NlcHRzIjpb…   # base64 of the body
{"x402Version": 2,
 "accepts": [{"scheme": "exact", "network": "eip155:8453",
              "amount": "100000",   # USDC atomic units (6 dp) = 0.10 USDC
              "asset":  "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "payTo":  "0xAb62452b4b019bC4402BFfCca6C706d16d72A7Bf",
              "maxTimeoutSeconds": 120, "extra": {"name": "USD Coin", "version": "2"}}],
 "resource": {"url": "https://minia2a.uk/x402/time"},
 "error": "Payment required", "nextSteps": ["…"]}

# 3. Agent signs an EIP-3009 transferWithAuthorization for that amount
#    (off-chain signature; the facilitator submits it, so the agent needs no gas)

# 4. Agent resends the same request with the payment payload
POST /x402/time HTTP/1.1
PAYMENT-SIGNATURE: <base64 x402 V2 payload>   # V1 callers send X-PAYMENT instead
#    …or, if the transfer was already mined on Base:
X-Payment-Tx: 0x7a3f8b2c...9d1e
X-Payer-Signature: 0x…  # personal_sign("minia2a payment: 0x7a3f8b2c...9d1e")

# 5. Server verifies + settles, then returns the resource with a settlement receipt
HTTP/1.1 200 OK
PAYMENT-RESPONSE: base64({"success":true,"transaction":"0x…","network":"eip155:8453","payer":"0x…"})
{"unix": 1758000000, "iso": "2026-10-22T22:00:00Z"}

That's it. Four HTTP headers. One on-chain transfer. No API key provisioning, no account management, no monthly invoice. Software paying software — autonomously.

3. How Agent-to-Agent Payment Works

4. Integration Patterns

Pattern A: Direct HTTP (Any Language)

The simplest integration — works with any HTTP client. Your agent just needs a wallet that can send USDC.

// JavaScript — using ethers.js v6
import { ethers } from 'ethers';

async function callWithPayment(url, body, wallet) {
  // Step 1: Make the request
  const res1 = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });

  if (res1.status !== 402) return res1.json();

  // Step 2: Extract payment details from 402 headers
  const amount    = res1.headers.get('X-Payment');    // "x402 USDC 0.05 on Base"
  const recipient = res1.headers.get('X-Payment-Address');
  const invoiceId = res1.headers.get('X-Invoice-Id');

  // Step 3: Send USDC on Base
  const usdc = new ethers.Contract(USDC_ADDRESS, ERC20_ABI, wallet);
  const tx = await usdc.transfer(recipient, parseUnits('0.05', 6));
  await tx.wait();  // ~2 seconds on Base

  // Step 4: Resend with payment proof
  const res2 = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type':  'application/json',
      'X-Payment-Tx':  tx.hash,
      // 2026-10-14: also prove you are the payer (lowercase hash in the message)
      'X-Payer-Signature': await yourSigner.signMessage(`minia2a payment: ${tx.hash.toLowerCase()}`),
      'X-Invoice-Id':  invoiceId,
    },
    body: JSON.stringify(body)
  });

  return res2.json();  // Your result!
}

Pattern B: x402 SDK (Recommended)

The @x402/evm SDK handles the 402 handshake, payment construction, and retry logic for you. Works across Base, Solana, Polygon, Arbitrum, and Celo.

import { pay } from '@x402/evm';

const result = await pay('https://minia2a.uk/x402/weather', {
  wallet: agentWallet,
  body: { city: 'London' },
  maxBudget: '0.10',     // Max USDC to spend
  network: 'base',
});

Pattern C: Python

from web3 import Web3
import requests, json

def call_x402_service(url, payload, wallet):
    # Step 1: Make request
    r = requests.post(url, json=payload)
    if r.status_code != 402:
        return r.json()

    # Step 2: Parse 402 headers
    invoice_id = r.headers.get('X-Invoice-Id')
    recipient  = r.headers.get('X-Payment-Address')
    amount_raw = r.headers.get('X-Payment')  # "x402 USDC 0.05 on Base"

    # Step 3: Pay USDC
    tx_hash = send_usdc(wallet, recipient, 0.05)

    # Step 4: Resend with proof
    r2 = requests.post(url, json=payload, headers={
        'X-Payment-Tx': tx_hash,
        'X-Invoice-Id': invoice_id,
    })
    return r2.json()

Pattern D: Node.js Agent with minia2a CLI

# Install the minia2a CLI
npm install -g minia2a

# Your agent calls any x402 service through the CLI
minia2a call captcha-solve --url https://example.com/captcha.png
# → Agent auto-handles 402 → pays USDC → returns result

5. The minia2a Marketplace

minia2a.uk is the largest marketplace of x402-payable services. As of today: 1,769 services across categories including blockchain data, web scraping, security, DeFi analytics, file conversion, and more. 316 agents are registered. Over 7.35M requests have been processed.

Service Categories

6. MCP (Model Context Protocol) Integration

minia2a exposes an MCP server that Claude Code and other MCP-compatible agents can use directly. This means your Claude Code agent can discover and pay for external services without leaving the conversation.

// claude_code_mcp.json
{
  "mcpServers": {
    "minia2a": {
      "command": "npx",
      "args": ["-y", "minia2a-mcp"],
      "env": {
        "MINIA2A_WALLET_KEY": "your-private-key",
        "MINIA2A_MAX_BUDGET": "1.00"
      }
    }
  }
}

Once configured, your Claude agent can use tools like:

• minia2a_search — find x402 services by description
• minia2a_call — call any service, auto-handling 402 + payment
• minia2a_balance — check agent's USDC balance
• minia2a_publish — publish your own x402 service

7. Security & Safety Patterns

Autonomous agent payments require safety rails. Here are the patterns we recommend:

Per-Agent Budget Limits

const agent = createAgent({
  wallet: agentWallet,
  budget: {
    perCall:    '0.50',   // Max USDC per single call
    perHour:    '5.00',   // Max USDC per hour
    perDay:     '20.00',  // Max USDC per day
  },
  allowedServices: ['weather', 'web-scrape', 'gas'],  // Whitelist
});

Non-Custodial Wallets

The agent's wallet is a standard EOA (externally owned account). minia2a never holds your funds. Every payment is a direct on-chain USDC transfer from the agent to the service provider. No escrow, no custody, no counterparty risk.

Payment Verification

Service providers verify payments by checking the on-chain transaction before processing the request. Failed or insufficient payments return 402 again. Overpayments can be refunded. The protocol is stateless — every request stands on its own.

8. Comparison: x402 vs Traditional API Monetization

9. Getting Started in 5 Minutes

Get Started →   Watch Demo