Give Your AI Agent a Wallet — x402 Payment Protocol in Practice

The x402 protocol is simple: when an agent calls a paid API without payment, the server returns HTTP 402 with a payment invoice. The agent pays the invoice, retries with a payment proof header, and gets the result.

That's it. Three steps. No API keys, no signup, no monthly subscription. Here's how to implement it from scratch.

The Protocol in 3 Steps

Step 1: Agent calls → Server returns 402

curl -s https://minia2a.uk/x402/captcha-solve

Response (HTTP 402):

{
  "error": "Payment Required",
  "type": "x402",
  "network": "base",
  "token": "USDC",
  "priceCents": 5,
  "recipient": "0xf16F0882de08315B438E9f3a2Abfb2d2E5d94ECA",
  "chainId": 8453
}

The 402 response carries all the information an agent needs to pay: how much (5 cents USDC), to whom (the contract address), and on which chain (Base L2).

Step 2: Agent pays

You could send USDC on-chain and wait for confirmation. That works but takes ~15 seconds. The practical path: use free trials for exploration, Coinbase CDP for production.

Step 3: Agent retries with payment proof

curl -s https://minia2a.uk/x402/captcha-solve \
  -H "X-Wallet: 0xYOUR_WALLET" \
  -H "X-Payment-Signature: $SIGNATURE"

Response (HTTP 200):

{
  "solved": true,
  "token": "recaptcha_v3_token_here",
  "cost": 5,
  "x-receipt": "rcpt_abc123def456"
}

Building a Real Agent with x402

class PayingAgent {
  constructor(walletAddress, signer) {
    this.wallet = walletAddress;
    this.signer = signer;
  }

  async call(serviceId, params = {}) {
    const url = `https://minia2a.uk/x402/${serviceId}`;
    let res = await fetch(url);

    if (res.status === 200) {
      return res.json(); // Free trial used
    }

    if (res.status === 402) {
      const invoice = await res.json();
      return this.payAndRetry(url, invoice);
    }
  }

  async payAndRetry(url, invoice) {
    const signature = await this.signer({
      recipient: invoice.recipient,
      amount: invoice.priceCents,
      chainId: invoice.chainId
    });

    const res = await fetch(url, {
      headers: {
        'X-Wallet': this.wallet,
        'X-Payment-Signature': signature,
      }
    });

    return res.json();
  }
}

Multi-Language Support

Python

import requests

def call_x402(service_id, params, wallet, signer):
    url = f"https://minia2a.uk/x402/{service_id}"
    resp = requests.get(url, params=params)

    if resp.status_code == 200:
        return resp.json()

    if resp.status_code == 402:
        invoice = resp.json()
        sig = signer(invoice['recipient'], invoice['priceCents'])
        resp = requests.get(url, params=params, headers={
            'X-Wallet': wallet,
            'X-Payment-Signature': sig,
        })
        return resp.json()

Go

func (a *Agent) CallX402(serviceID string, params url.Values) ([]byte, error) {
    u := fmt.Sprintf("https://minia2a.uk/x402/%s?%s", serviceID, params.Encode())
    resp, _ := http.Get(u)

    if resp.StatusCode == 402 {
        var invoice X402Invoice
        json.NewDecoder(resp.Body).Decode(&invoice)
        sig := a.SignPayment(invoice)
        req, _ := http.NewRequest("GET", u, nil)
        req.Header.Set("X-Wallet", a.WalletAddr)
        req.Header.Set("X-Payment-Signature", sig)
        resp, _ = http.DefaultClient.Do(req)
    }

    return io.ReadAll(resp.Body)
}

Why HTTP 402 Instead of API Keys

The Receipt Layer

Every x402 call returns a cryptographic receipt:

{
  "id": "rcpt_x402_captcha_2026-08-07T14-22-11Z_abc123",
  "type": "trial",
  "service_id": "x402-captcha-solve",
  "hmac": "sha256:9f86d081884c7d..."
}

Receipts are publicly verifiable — agents can prove they called a service, service providers can resolve disputes, and multi-agent systems can track spending across sub-agents.

What I'd Build Next

1. A wallet-aware agent framework — LangChain, CrewAI, ElizaOS should ship with agent.wallet as a first-class primitive.
2. Service discovery via natural language — "I need to check if this smart contract is safe" → agent searches, finds, calls, pays.
3. Reputation on-chain — services accumulate on-chain reputation scores. Did the CAPTCHA solver actually solve it?
4. Budget constraints as code — agent.setDailyBudget(5.00, 'USDC') and the agent self-regulates.

The Numbers (Real Data, August 2026)

From a live marketplace with 323 services:

• #1 most-called service: CAPTCHA solving (1,280 calls, 133 users)
• #2: Persistent memory/key-value store (1,401 calls)
• Conversion: 16.5% of trial users register wallets
• Credit utilization: 2.8% of free credits used
• 322 unique agents, 53 wallets, 14 paid transactions

The market is small but real. The infrastructure works. The habits haven't caught up yet.

Code examples use the minia2a.uk marketplace (323 services, 15 free trials per endpoint, USDC on Base). The x402 protocol is an open standard being formalized as an IETF draft. Implementations exist in Go, Node.js, and Python.

Originally published on DEV.to · minia2a — agent-to-agent API marketplace