Build an AI Agent That Pays for APIs — A Practical x402 Tutorial

August 10, 2026 · Iris · minia2a blog

Your AI agent can call APIs. But can it pay for them?

This tutorial walks through the complete flow: registering an agent wallet, discovering paid APIs, making free trial calls, and spending credits when trials run out. No API keys. No KYC. No credit card. Just HTTP.

The protocol is x402 — HTTP 402 Payment Required, repurposed for stablecoin micropayments. It's processed $50 billion in volume across 200 million transactions. Your agent can use it today.

What We're Building

By the end of this tutorial, you'll have a Python agent that:

1. Registers itself and gets a wallet + 5 free trial calls
2. Discovers available APIs from a marketplace of 328 services
3. Makes free trial calls (up to 5 total, per registered wallet)
4. Spends credits when trials are exhausted
5. Handles 402 responses gracefully

curl -X POST https://minia2a.uk/api/v1/register-simple \
  -H "Content-Type: application/json" \
  -d '{"name": "my-research-agent", "wallet": "0x...", "signature": "0x..."}'

# List all services
curl https://minia2a.uk/api/services

# Search for specific capabilities
curl "https://minia2a.uk/api/services?q=gas"

# Get a specific service's details
curl https://minia2a.uk/api/services/x402-gas

# Free trial — register a wallet
curl "https://minia2a.uk/x402/gas"

# Pass parameters
curl "https://minia2a.uk/x402/gas?chain=base"

# POST with JSON body
curl -X POST https://minia2a.uk/x402/find \
  -H "Content-Type: application/json" \
  -d '{"q": "bitcoin price prediction 2026"}'

# Spend a free trial call — a trial is two halves, wallet AND signature.
export WALLET=0xYOUR_WALLET SERVICE=x402-gas TS=$(date +%s)
export SIG=0xYOUR_SIGNATURE   # EIP-191 personal_sign of: minia2a trial:$WALLET:$SERVICE:$TS
curl "https://minia2a.uk/x402/gas?wallet=$WALLET" \
  -H "X-Wallet-Signature: $SIG" -H "X-Trial-Timestamp: $TS"
# -> 200

# There is no funding step. Keep the USDC in your own agent's wallet.
# Pay per call over x402 — the 402 names the price and payTo:
curl -i "https://minia2a.uk/x402/gas"
# -> HTTP 402 + base64 PAYMENT-REQUIRED header
# settle that offer, then retry the same URL with:
#   -H "PAYMENT-SIGNATURE: $SIGNATURE"

The Complete Python Agent

Here's a production-ready agent that discovers APIs, tries them, and spends credits:

#!/usr/bin/env python3
"""Agent that discovers, trials, and pays for x402 APIs."""

import requests
import json
import os

BASE = "https://minia2a.uk"
WALLET_FILE = os.path.expanduser("~/.agent-wallet.json")

class Agent:
    def __init__(self, name="research-agent"):
        self.name = name
        self.wallet = None
        self.credits = 0
        self._load_or_register()

    def _load_or_register(self):
        """Load existing wallet or register a new one."""
        if os.path.exists(WALLET_FILE):
            with open(WALLET_FILE) as f:
                data = json.load(f)
                self.wallet = data["wallet"]
                self.credits = data.get("credits", 0)
                print(f"Loaded wallet: {self.wallet[:10]}... "
                      f"({self.credits} credits)")
                return

        # Register new agent (V5 self-custody: wallet + EIP-191 signature)
        r = requests.post(f"{BASE}/api/v1/register-simple",
                          json={"name": self.name, "wallet": WALLET,
                                "signature": SIG})
        if r.status_code == 200:
            data = r.json()
            self.wallet = data["wallet"]
            self.trials = data.get("trials", 5)
            with open(WALLET_FILE, "w") as f:
                json.dump({"wallet": self.wallet,
                           "credits": self.credits}, f)
            print(f"Registered! Wallet: {self.wallet[:10]}... "
                  f"Credits: {self.credits}")
        else:
            raise Exception(f"Registration failed: {r.text}")

    def discover(self, query=None):
        """Find available APIs."""
        url = f"{BASE}/api/services"
        if query:
            url += f"?q={query}"
        r = requests.get(url)
        return r.json() if r.status_code == 200 else []

    def call(self, endpoint, method="GET", params=None, json_body=None):
        """Call an x402 endpoint. Uses trials first, then credits."""
        url = f"{BASE}/x402/{endpoint}"

        # If we have a wallet, always include it for credit tracking
        if self.wallet:
            if params is None:
                params = {}
            params["wallet"] = self.wallet

        if method == "GET":
            r = requests.get(url, params=params)
        else:
            r = requests.post(url, params=params, json=json_body)

        # Handle 402: trials exhausted, using credits
        if r.status_code == 402:
            data = r.json()
            if data.get("_trial"):
                remaining = data["_trial"].get("credits_remaining", 0)
                self.credits = remaining
                if remaining == 0:
                    raise Exception("No credits remaining. "
                                    "Buy credits at /buy.html")
            return data

        # Success or trial response
        result = r.json() if r.status_code == 200 else {"error": r.text}

        # Track credit usage from response
        cr = result.get("credits_remaining")
        if cr is not None:
            self.credits = cr
            # Update stored credits
            if os.path.exists(WALLET_FILE):
                with open(WALLET_FILE) as f:
                    data = json.load(f)
                data["credits"] = cr
                with open(WALLET_FILE, "w") as f:
                    json.dump(data, f)

        return result

    def run(self, task):
        """Execute a task by chaining API calls."""
        print(f"\n🤖 Agent '{self.name}' executing: {task}\n")

        # Step 1: Find relevant APIs
        services = self.discover(task.split()[0])
        if not services:
            print("No services found for this task.")
            return

        # Show top 3 matches
        print(f"Found {len(services)} services. Top 3:")
        for s in services[:3]:
            print(f"  • {s['id']}: {s.get('name', s['id'])} "
                  f"({s.get('priceCents', '?')}¢/call)")

        # Step 2: Call the best match
        best = services[0]["id"]
        print(f"\nCalling {best}...")
        result = self.call(best)
        print(f"Result: {json.dumps(result, indent=2)[:300]}")
        print(f"Credits remaining: {self.credits}")

# ── Usage ──
if __name__ == "__main__":
    agent = Agent("gas-tracker")

    # Discover gas-related APIs and call one
    agent.run("gas")

    # Call a specific endpoint with parameters
    result = agent.call("polymarket",
                        params={"market": "trump-2028"})
    print(json.dumps(result, indent=2))

Key Design Decisions

Why wallet in query params instead of headers?

Query parameters work everywhere: curl, browsers, Python requests, AI SDKs. Headers require SDK-specific configuration. The ?wallet= pattern is the lowest-friction integration path — your agent appends one parameter and it works.

Why free trials instead of pay-first?

Agents can't evaluate an API before calling it. Free trials let your agent test 5 different endpoints, find the one that returns the right data, then commit credits. It's the same model as SaaS free trials, adapted for machine consumers.

What happens when credits hit zero?

The endpoint returns HTTP 402 with credits_remaining: 0. Your agent can catch this and either switch to a free alternative, notify a human, or pause until credits are purchased. The protocol doesn't silently fail — it explicitly signals payment state.

What's Next

Once your agent can pay for APIs, the design space opens up:

• Multi-step workflows: Call gas oracle → check price → execute trade. Your agent chains paid API calls into autonomous workflows.
• Budget guardrails: Add a .agent-budget file with daily spending limits. Your agent checks it before each call.
• Receipt verification: Log every x402 response. The _trial field is your audit trail — credits spent, endpoint called, timestamp.
• Fallback chains: If one data provider is down, your agent discovers and pays an alternative automatically.

The agent economy doesn't need a new payment protocol. HTTP 402 has been in the spec since 1997. What's new is that it actually works now — USDC settlement on Base, 2-second finality, sub-cent fees, and 150,000 endpoints that accept it.

Your agent can join the economy today. The first 5 calls are free (per registered wallet).