Full agent: natural-language question → paid data → answer

💸 AI x402 Paying Agent

An AI agent with its own crypto wallet that pays for the data it needs — no API keys, no subscriptions, no signup.

Ask a question in plain English. Claude decides which paid API answers it and calls a fetch tool. The API responds 402 Payment Required with a price quote; the agent automatically pays it in USDC via the open x402 standard (now under the Linux Foundation) and answers from the data it just bought.

Everything in this tutorial is free and self-contained. You run the paid API yourself (seller.py, ~60 lines), payments settle in testnet USDC on Base Sepolia through the public x402.org facilitator, and the buyer wallet is funded from a free faucet. You are both the buyer and the seller, so you watch the full payment loop with zero real money involved. The exact same agent code works on mainnet against any live x402 API.

Features

• Agent-driven tool use — Claude picks the right paid endpoint for the question and quotes the returned data
• Automatic 402 payment — the x402 SDK signs a USDC payment when an API challenges; the demo endpoints cost $0.001–0.002 in testnet USDC
• Hard budget cap — a per-call price ceiling (MAX_PRICE_USDC, default $0.05) so a misconfigured agent can never overspend
• No-LLM mode — --direct <URL> pays and fetches any x402 URL with just a wallet, so you can see the payment flow in isolation
• Your own seller — seller.py is a complete pay-per-call API in ~60 lines of FastAPI; reprice it, add endpoints, or point the agent at any other x402 seller

How to get Started?

1. Clone the GitHub repository

git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git
cd awesome-llm-apps/starter_ai_agents/ai_x402_paying_agent

2. Install the required dependencies:

pip install -r requirements.txt

3. Create two throwaway wallets (buyer and seller)

Any EVM wallet works (MetaMask, or python -c "from eth_account import Account; a=Account.create(); print(a.address, a.key.hex())"). You need:

• a buyer wallet the agent spends from — export its private key
• a seller address that receives the payments — any second address you control (it only receives; it needs no funds and no key on the server)

export X402_PRIVATE_KEY='0x...'   # buyer wallet private key
export SELLER_ADDRESS='0x...'     # seller receive address

⚠️ Use dedicated throwaway wallets for this — never your main wallet.

4. Fund the buyer with free testnet USDC

Go to faucet.circle.com, pick Base Sepolia, paste the buyer address. You get test USDC instantly; no gas token is needed anywhere (x402 payments are gasless for both sides).

5. Start your paid API (terminal 1)

uvicorn seller:app --port 4021

Try it unpaid and watch the 402 challenge: curl -i http://localhost:4021/api/fortune

6. Set your Anthropic API key (skip for --direct mode)

export ANTHROPIC_API_KEY='your-api-key-here'

7. Run the agent (terminal 2)

# Full agent: natural-language question → paid data → answer
python x402_paying_agent.py "Roll me a d20 and read me my fortune"

# Payment flow only, no LLM needed:
python x402_paying_agent.py --direct "http://localhost:4021/api/fortune"

How it works

you ──question──▶ Claude ──tool call──▶ GET your local paid API
                                          │ 402 Payment Required ($0.001)
                                          ▼
                                   x402 SDK signs USDC payment
                                          │ retry with payment header
                                          ▼
                              facilitator verifies + settles on Base Sepolia
                                          │
                                     200 OK + data ──▶ Claude answers

The whole payment negotiation is 3 HTTP requests and settles on-chain in seconds — and because you run the seller, you can watch both sides of it.

Beyond the demo

• Point it at the real economy — swap the URL for any live x402-enabled API on a mainnet network; the agent code is identical. Directories of live x402 endpoints are linked from x402.org.
• Going to production: managed wallets — this demo keeps the wallet as a raw private key so you can see every moving part. For a production agent, Coinbase's CDP x402 SDK wraps the same open standard with managed wallets (no private key to store), client-side spend controls (per-payment caps, rolling daily limits, payee allowlists), and hosted settlement. The MAX_PRICE_USDC guard in this tutorial is a minimal version of the same idea — cap what an autonomous spender can spend before it spends it.