minia2a

Posted on Aug 10 Originally published at minia2a.uk

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

#x402 #aiagents #python #tutorial

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 has processed over $50 billion in volume across 200 million transactions. Your agent can use it today.

What We Are Building

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

Registers itself and gets a wallet + 500 free credits
Discovers available APIs from a marketplace of 328 services
Makes free trial calls (up to 5 per endpoint, no registration needed)
Spends credits when trials are exhausted
Handles 402 responses gracefully

Step 1: Register Your Agent (30 seconds)

This creates a wallet, grants 500 free credits, and returns everything your agent needs. No signature. No gas. No KYC.

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

Response:

{
  "wallet": "0x...",
  "credits": 500,
  "message": "500 free credits granted (~$2.50). Start calling any /x402/* endpoint.",
  "usage": "GET /x402/gas?wallet=0x..."
}

Save the wallet address. That is your agent is identity and payment method.

Step 2: Discover What is Available

328 services are live. Here is how your agent finds the ones it needs:

# 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 details
curl https://minia2a.uk/api/services/x402-gas

The most popular endpoints (by trial volume):

x402-recall — 1,740 trials — Agent memory / key-value store
x402-gas — 1,236 trials — Multi-chain gas oracle
x402-captcha — 1,202 trials — CAPTCHA solver for agents
x402-find — 1,123 trials — Semantic search
x402-polymarket — 615 trials — Prediction market data

Step 3: Make Free Trial Calls

Every endpoint gives 5 free trial calls per IP address. No registration needed. Your agent can try before committing.

# Free trial — no wallet, no registration
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"}"

Each response includes trial status with trials_used and trials_remaining.

Step 4: Spend Credits When Trials Run Out

After 5 free calls, the endpoint returns HTTP 402. Append your wallet address to spend credits instead:

# Spend credits (1 credit = ~$0.005 at the standard rate)
curl "https://minia2a.uk/x402/gas?wallet=0xYOUR_WALLET"

Response includes credits_remaining field so your agent always knows its balance.

When credits run low, the response automatically includes a warning with a link to buy more.

The Complete Python Agent

Here is a production-ready agent that discovers APIs, tries them, and spends credits. Full source at: https://minia2a.uk/blog-build-agent-that-pays-august-2026.html

Key Design Decisions

Why wallet in query params instead of headers?

Query parameters work everywhere: curl, browsers, Python requests, AI SDKs. The ?wallet= pattern is the lowest-friction integration path.

Why free trials instead of pay-first?

Agents cannot 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.

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.

What is Next

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

Multi-step workflows: Call gas oracle → check price → execute trade
Budget guardrails: Add a .agent-budget file with daily spending limits
Receipt verification: Log every x402 response as audit trail
Fallback chains: If one data provider is down, discover and pay an alternative automatically

The agent economy does not need a new payment protocol. HTTP 402 has been in the spec since 1997. What is 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 500 calls are free.

DEV Community