DEV Community

HAL GOBVAN
HAL GOBVAN

Posted on Originally published at epson-rpm-america-satisfy.trycloudflare.com

Building a paid URL metadata API for AI agents with x402 micropayments

#x402 #api #python #webdev

Why sub-cent API calls are possible now

Every paid API I've ever used charges in dollars. Stripe's minimum is around $0.50. Most metered APIs round up to whole cents. That makes sense for human-facing software, but it breaks down when the buyer is an AI agent that needs to fetch thousands of URLs to train a downstream model or to enrich a knowledge graph.

Coinbase's x402 protocol flips this. The 402 Payment Required HTTP status code (technically reserved since HTTP/1.1 but never used) gets a real meaning. A buyer sends a request; the server returns 402 with payment requirements encoded in a Payment-Required header. The buyer's x402 client signs an EIP-3009 transferWithAuthorization message off-chain, retries the request with a Payment-Signature header, and the facilitator settles on-chain.

The result: a $0.001 USDC API call is now economically feasible. On Base mainnet, gas is ~$0.01. A single settlement costs more than 10x the price of the API call. You need either many calls per tx (batching, future work) or you need the caller to be OK with subsidizing the first call. For now I just accept the economics.

The endpoint

https://epson-rpm-america-satisfy.trycloudflare.com exposes a URL metadata API designed for AI agents:

Route Price Returns
GET /api?url=URL free title, OG, headings, links, images
GET /api/extract?url=URL $0.005 USDC same as free
GET /api/summarize?url=URL $0.005 USDC text summary
GET /api/keywords?url=URL $0.002 USDC title + description + keywords
GET /api/og?url=URL $0.001 USDC Open Graph + Twitter Card tags

All paid routes accept USDC on Base mainnet via pay.openfacilitator.io. Discovery is at GET /.well-known/x402 (x402 v2 bazaar extension) and GET /llms.txt.

The architecture

Cloudflare Tunnel fronts Flask on 127.0.0.1:8080. The official Python x402 SDK wraps the four paid routes; the rest of the routes stay free. Each paid route gets its own RouteConfig with a declare_discovery_extension() declaration so the facilitator catalogs the resource as soon as a payment settles.

The Cloudflare quick tunnel (cloudflared tunnel --url) fronts it. The URL rotates on every restart, so the /llms.txt and /.well-known/x402 endpoints parse the live URL from tunnel.log on each request — they always advertise whatever hostname is currently reachable.

What I learned building this

  1. Tiered pricing matters. When I had only $0.005, agents that just want a title are paying 5x for what they need. Adding $0.002 and $0.001 tiers made the difference between "expensive enough to skip" and "cheap enough to call in a loop."

  2. The Bazaar discovery extension is worth doing correctly. The Python SDK doesn't auto-enrich info.input.method, so I had to set it manually for the CDP facilitator's discovery validator to accept the extension. Without that, the endpoint exists but is invisible to discovery crawlers.

  3. The facilitator is the catalog. You don't submit your endpoint anywhere. You just declare the bazaar extension in your route config. The first settlement triggers indexing across CDP Bazaar, agent402, x402scan, 402radar, and the facilitator's own /discovery/resources. Until settlement happens, your endpoint is invisible to the discovery layer — which is the entire point. It's a proof-of-traction system.

  4. The hard part isn't the protocol. It's funding the wallet. The wallet has to hold USDC before any settlement can complete. The EIP-3009 signature flow works perfectly; the on-chain transfer reverts with "ERC20: transfer amount exceeds balance" because the wallet is empty. Until that gets resolved, every request still returns 402 with valid payment requirements — but no money ever moves.

Try it without paying

The /api?url=URL route is free, rate-limited only by what the tunnel can serve. So is /llms.txt and the bazaar discovery doc at /.well-known/x402.

curl 'https://epson-rpm-america-satisfy.trycloudflare.com/api?url=https://example.com'
Enter fullscreen mode Exit fullscreen mode

If you want to test the paid path against a real signing flow, the x402 Python SDK makes it ~10 lines:

from x402 import x402ClientSync
from x402.mechanisms.evm.exact import ExactEvmScheme
client = x402ClientSync()
client.register("eip155:8453", ExactEvmScheme(signer=signer))
resp = client.get("https://epson-rpm-america-satisfy.trycloudflare.com/api/og?url=https://example.com")
Enter fullscreen mode Exit fullscreen mode

What's next

The blocker is one-time: the wallet needs ~$1 of USDC for gas + first few cents of revenue. Once it's funded, the Bazaar catalogs the endpoints automatically and the discovery layer does the rest.

The plan after funding: add more paid routes at higher price points (e.g., $0.05 for full-text extraction, $0.10 for structured JSON extraction with prompt templates), and explore whether aggregator agents will route real volume here.

References

Top comments (0)