x402 Protocol Explained: How to Build a Paid API That AI Agents Can Use

HTTP has a status code that's been sitting unused for over 30 years. Status 402: Payment Required. The spec reserved it for "future use." In 2025, Coinbase activated it. x402 turns that dormant status code into an actual payment protocol — an API returns 402 instead of 200, the caller pays in USDC, the payment settles on-chain, and the API delivers the response. No API keys, no signup forms, no billing dashboards.

I run a paid API built on x402 — KR Crypto Intelligence, serving Korean exchange data to AI trading bots. It's earned $1.19 in real USDC from agents across six continents. This post explains how the protocol works and what building on it actually looks like.

How x402 Works in 60 Seconds

The flow is four steps. Every x402 transaction follows this exact sequence:

# Step 1: Agent calls the API
GET /api/v1/kimchi-premium?symbol=BTC
→ Response: 402 Payment Required
→ Header includes: price ($0.001), wallet address, supported chains

# Step 2: Agent pays
Agent sends $0.001 USDC to the specified wallet
Transaction settles on Base (or Polygon, or Solana)

# Step 3: Agent proves payment
Agent calls the same endpoint again
Includes payment proof in the request header

# Step 4: API delivers data
Server verifies payment via CDP facilitator
→ Response: 200 OK + the actual data

The entire exchange happens in one HTTP round-trip from the agent's perspective. No account creation. No OAuth tokens. No monthly invoices. The agent finds the API, pays, receives data, moves on.

Why this matters for AI agents: Traditional APIs require a human to sign up, generate an API key, enter a credit card, and configure billing. An autonomous AI agent can't do any of that. x402 removes the human from the payment loop. The agent pays directly from its own USDC wallet, per call, at the moment it needs the data. This is what makes x402 "agent-native" — the payment protocol was designed for software paying software.

What You Need to Build an x402 API

The infrastructure requirements are lighter than you'd expect:

A web server that returns 402 responses. Any framework works. I use FastAPI on Python. The x402 Python SDK handles the 402 response format — you configure the price per endpoint and the SDK generates the correct headers.

A USDC wallet address. This is where payments arrive. I use a MetaMask wallet on Base. You can use any EVM-compatible wallet. The address goes into your server configuration; x402 payments settle directly to it.

A CDP facilitator connection. Coinbase's facilitator service verifies payments and settles transactions. The SDK handles this connection. You don't interact with the blockchain directly — the facilitator confirms that the payment happened and tells your server to release the data.

An Oracle Cloud free tier instance (or any VPS). The API runs on a normal server. Mine handles 11 paid endpoints on a single free instance.

What an x402 Endpoint Looks Like in Code

A minimal x402 endpoint in Python with FastAPI:

from x402.http import x402_fastapi
from x402 import PaymentRequirements

app = FastAPI()

# Configure x402 middleware
x402_fastapi(
    app,
    payment_config={
        "GET /api/v1/kimchi-premium": {
            "price": "$0.001",
            "network": "base-mainnet",
            "address": "0xYourWalletHere",
        }
    }
)

@app.get("/api/v1/kimchi-premium")
async def kimchi_premium(symbol: str = "BTC"):
    # This code only runs after payment is verified
    return calculate_premium(symbol)

The SDK middleware intercepts requests, returns 402 to unpaid callers, verifies payment proofs, and only lets paid requests through to your endpoint function. Your business logic doesn't change — you write a normal API endpoint and the SDK handles the payment layer.

What My x402 API Earns (Real Numbers)

KR Crypto Intelligence has been live for about five weeks. The numbers are small but real:

# Revenue as of May 2026
Total paid calls:        67
Total revenue:           $1.19 USDC
Unique paying agents:    9 (from 6 continents)
Infrastructure cost:     $0/month
AI cost (Haiku):         ~$0.003/sentiment call
Margin per call:         >95%

# Endpoint pricing
kimchi-premium:          $0.001
kr-prices:               $0.001
exchange-alerts:         $0.01
arbitrage-scanner:       $0.01
market-movers:           $0.01
kr-sentiment:            $0.05
divergence-light:        $0.05
divergence-deep:         $0.10
market-read:             $0.10

$1.19 isn't a business. But the unit economics are clean — every additional call adds revenue at near-zero marginal cost. The infrastructure is already built. The pricing scales linearly with usage. And I know the payments are real because they settle on-chain, verifiable on BaseScan.

The x402 Ecosystem Right Now

x402 isn't a single company's product. In April 2026, Coinbase and the Linux Foundation launched the x402 Foundation with backing from AWS, Google, Microsoft, Visa, Mastercard, Stripe, and Circle. AWS published a Bedrock reference architecture for building agents that pay via x402.

The ecosystem as of May 2026:

Services: Over 36,000 indexed on the CDP Bazaar discovery API. Categories include market data, search, computation, content generation, and infrastructure tooling.

Chains: Base, Polygon, Solana, and Arbitrum. Base is where most of the activity lives.

Discovery: Agents find x402 services through Agentic.market (Coinbase's discovery layer), MCP server directories, and direct URL sharing. My service is listed on 10+ platforms for maximum discoverability.

The market is early. Real paid usage is growing but still small relative to the number of registered services. Wash trading accounts for a meaningful portion of reported transaction volume. The protocol infrastructure works; the demand side is catching up.

Who Should Build on x402

x402 works best for data and computation services where the value is per-call, not per-subscription. If your API answers a question that changes over time — price data, sentiment analysis, search results, translation, image generation — per-call pricing makes sense.

It works less well for services where the value comes from ongoing access — a database you query regularly, a tool you use all day. For those, traditional API keys with monthly billing are a better fit.

The sweet spot is niche data that's hard to get elsewhere. My Korean exchange data works because English-speaking developers don't crawl Upbit documentation, and AI agents operating globally need that data to make trading decisions. The $0 infrastructure stack means the cost of being wrong is zero — if nobody pays, I lose nothing except my time.

The Gotcha Nobody Mentions

Building the API is the easy part. Getting it discovered is the hard part.

x402 services are found through catalog systems — CDP Bazaar, MCP directories, curated lists like awesome-x402. Your service has to be indexed correctly for agents to find it. The indexing process has its own set of problems: schema validation that fails silently, discovery extensions with strict JSON requirements, and no error messages when something's wrong.

I spent six weeks thinking my indexing issue was a version compatibility problem. It wasn't. It was three small schema errors that the system rejected without telling me. The fix took 45 minutes once I found the real cause. That debugging story is documented separately — read it before you submit your first service.

Related guides:

Disclaimer: This blog documents practical workflows based on personal experience. Nothing here is financial, legal, or professional advice.

Search This Blog

PrintMoneyLab - Automate & Earn