Build Your First x402-Powered AI Agent

You've built an AI agent. It can reason, use tools, and interact with the world. But there's one thing it can't do: pay for the APIs it needs. Every useful API — weather, crypto prices, captcha solving, web scraping — requires an API key that a human had to register, verify, and fund.

x402 changes this. It's a protocol that lets your agent pay for API calls automatically, in USDC, at the moment of use. No API keys. No monthly subscriptions. No human in the loop.

In this tutorial, you'll build an agent that discovers services on minia2a.uk (a marketplace of 1,600+ x402 services), signs trial calls with a self-custody wallet to get 5 free calls, and falls through to real x402 settlement when they run out. All running on your machine.

How x402 Works (30-Second Version)

That's it. Five steps. No OAuth dance, no credit card form, no email verification. Machine-to-machine payments, fully automated.

minia2a has two rails, and they are not interchangeable. Trial: every signed wallet gets 5 free calls, shared across all services, with no registration — you sign the request itself. Paid: real x402 settlement in USDC, with no wallet param at all. For production, drive the second rail with @x402/fetch.

What You'll Build

An agent that:

• Discovers services via /api/services
• Signs a trial request with a self-custody wallet → 5 free calls, no registration
• Falls through to a real 402 challenge when the trial is spent, and pays on-chain
• Wraps it all in a reusable Python loop

Prerequisites

• Python 3.9+
• An Ethereum wallet (any EOA — you hold the private key, minia2a never sees it)
• requests and eth-account (for signing your registration message)

Step 1: Discover Services on minia2a

import requests

d = requests.get("https://minia2a.uk/api/services").json()
print(f"{d['count']} services available")

for s in d['services'][:5]:
    print(f"  {s['id']}: ${s['price']:.2f} — {s['description'][:60]}")
    # reliability label: excellent / good / fair / poor / unproven
    print(f"      reliability: {s['reliabilityLabel']} ({s['reliability']})")

Step 2: Try It Free (5 Free Trial Calls)

curl -s https://minia2a.uk/x402/time
# HTTP 402
# {"error": "Payment required",
#  "message": "Free trial calls are wallet-based — attach your wallet with a signature to get
#              5 free trial calls (no registration), or pay via x402.",
#  "nextSteps": [
#    "1. Trial: add ?wallet=0xYOUR_WALLET plus headers X-Wallet-Signature=sign(\"minia2a
#        trial:\"+wallet+\":\"+service+\":\"+ts) and X-Trial-Timestamp=ts (unix sec, ±5min)
#        — 5 free calls per wallet, no registration",
#    "2. Pay: include PAYMENT-SIGNATURE (V2) or X-PAYMENT (V1) header", ...],
#  "accepts": [{"amount": "100000", "network": "eip155:8453", "payTo": "0xAb62…", ...}]}

Step 3: Register a Wallet → 5 Free Trials

import os
from eth_account import Account
from eth_account.messages import encode_defunct

PRIVATE_KEY = os.environ["AGENT_WALLET_KEY"]   # never hardcode
account = Account.from_key(PRIVATE_KEY)

# EIP-191 personal_sign of the exact message:
message = f"minia2a register: {account.address}"
signature = account.sign_message(encode_defunct(text=message)).signature.hex()

resp = requests.post("https://minia2a.uk/api/v1/register-simple", json={
    "name": "my-first-agent",
    "wallet": account.address,
    "signature": signature,
})
body = resp.json()
print(body["ok"], body["message"])
# → True Registered. No credits included — pay per call via x402. (Free trials are
#   wallet-based: any signed wallet gets 5 trial calls, no registration needed.)

Step 4: Call Services With a Signed Trial

import time

def trial_call(service_id: str, **params):
    """One signed trial call — spends one of the wallet's 5 free calls."""
    ts = int(time.time())
    message = f"minia2a trial:{account.address}:{service_id}:{ts}"
    signature = account.sign_message(encode_defunct(text=message)).signature.hex()

    return requests.get(
        f"https://minia2a.uk/x402/{service_id.removeprefix('x402-')}",
        params={"wallet": account.address, **params},
        headers={
            "X-Wallet-Signature": signature,
            "X-Trial-Timestamp": str(ts),
        },
    )

r = trial_call("x402-time")
print(r.status_code, r.headers.get("x-trial-remaining"), r.json())
# → 200 4 {'ok': True, 'utc': '2026-09-12T12:25:21.940Z', 'unix': 1789215921,
#          'ms': 1789215921940, 'iso': '2026-09-12T12:25:21.940Z', 'timezone': 'UTC'}

The Complete Agent Loop

Wrap this in a reusable helper your agent can call whenever it needs a service:

import os, time, requests
from eth_account import Account
from eth_account.messages import encode_defunct

class X402Agent:
    """An AI agent that pays for x402 APIs automatically: signed trial, then on-chain."""

    BASE = "https://minia2a.uk"

    def __init__(self, private_key: str):
        self.account = Account.from_key(private_key)

    def call(self, service_id: str, **params) -> dict:
        """Signed trial call. Returns a 402 challenge once the trial is spent."""
        ts = int(time.time())
        message = f"minia2a trial:{self.account.address}:{service_id}:{ts}"
        signature = self.account.sign_message(encode_defunct(text=message)).signature.hex()

        resp = requests.get(
            f"{self.BASE}/x402/{service_id.removeprefix('x402-')}",
            params={"wallet": self.account.address, **params},
            headers={"X-Wallet-Signature": signature, "X-Trial-Timestamp": str(ts)},
        )
        if resp.status_code == 200:
            return {"ok": True, "data": resp.json()}
        # 402 = trial spent, or the endpoint is payment-only. Settle on-chain to continue.
        return {"ok": False, "status": resp.status_code, "body": resp.json()}


# --- Usage ---
agent = X402Agent(os.environ["AGENT_WALLET_KEY"])

# Discover what's available
services = requests.get(f"{X402Agent.BASE}/api/services").json()
print(f"Connected to minia2a — {services['count']} services available")

# Call a service
result = agent.call("x402-time")
print(result["data"] if result["ok"] else f"Error: {result}")

Go Production: Real x402 On-Chain Payments

For production agents that settle in real USDC on-chain (no prepaid credits), use the official @x402/fetch SDK. It detects the 402, reads the accepts[] offers, settles through a facilitator, and retries with the proof header — your code never sees a payment:

npm install @x402/fetch @x402/evm viem

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);

const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{
    network: "eip155:8453",   // Base mainnet
    client: new ExactEvmScheme(account),
  }],
});

// fetchWithPayment handles 402 → settle → retry automatically
const gas = await fetchWithPayment("https://minia2a.uk/x402/gas");
console.log(await gas.json());

What Services Can Your Agent Use?

minia2a.uk has 1,600+ services across 20 categories — crypto data, AI inference, web scraping, security, finance, dev tools, and more. Every listing shows its exact price. Here are a few examples:

Browse all 1,600+ services →

Why This Matters

The traditional API economy runs on monthly subscriptions and API keys — a model designed for humans. But AI agents don't have email addresses. They can't sign up for Stripe. They can't click "I am not a robot."

x402 is the payment layer for the machine economy. When your agent can pay for API calls directly, you unlock:

• Composability — agents chain multiple paid services together
• No vendor lock-in — pay per call, switch anytime
• Zero onboarding friction — no forms, no KYC, no approval
• Global by default — USDC works everywhere, instantly

Next Steps

1. Make a signed trial call — any wallet gets 5 free calls with no registration (Step 4). Register when you want a name on the marketplace
2. Explore the marketplace — find services your agent can use
3. List your own API — if you've built something useful, monetize it with x402
4. Read the x402 spec at x402.org for the full protocol details