How to pay an x402 API from Claude Code (with a spending limit)

Claude Code can pay x402 APIs on its own: it requests a URL, gets 402 Payment Required, and pays a few cents of USDC to get the answer. This guide sets that up with a hard limit. Claude Code gets one tool, fetch_paid, and every payment it makes is checked against a daily cap, a maximum per payment and a list of hosts you choose, before anything is signed.

You need Node.js 20 or later, Claude Code, a Burnbound account (free) and a wallet with a small USDC balance on Base. To try it without real money first, see Test it on Base Sepolia first.

What you will build

At the end, you can ask Claude Code something like "search the web for recent x402 news with Exa" and it will:

1. call get_budget to see what it may spend today;
2. call fetch_paid on https://api.exa.ai/search;
3. get the seller's price (0.007 USDC per search when we last verified it), have Burnbound check it against your rules, have your wallet sign it, and return the search results.

A payment that breaks a rule is denied before it is signed, and the reason comes back to Claude Code as a tool error. Every decision is in the dashboard audit log.

Step 1: Create an agent with small caps

Sign up at app.burnbound.dev. The onboarding creates your first agent. Pick numbers that would not hurt if the agent spent all of them:

Allowed hosts are exact hosts (api.exa.ai) or wildcards (*.example.com). Add only the APIs you want this agent to buy from. You can browse verified x402 sellers, with their hosts and prices, in the x402 API catalog.

Step 2: Connect the wallet that signs

Burnbound decides; your wallet signs. Pick one of the two modes in the dashboard:

• Coinbase CDP: paste your CDP API credentials and the wallet address. The key stays at Coinbase and Claude Code never holds anything that can sign.
• Client-side signing: create a wallet on your machine and register only its address.

npx -y @burnbound/mcp wallet init

The command prints an address. Paste it in the dashboard, then send a few dollars of USDC on Base to it. The wallet needs no ETH: in x402 the seller's facilitator submits the transfer and pays the gas.

Client-side signing is cooperative: Claude Code can run shell commands, so in theory it could read the local key and sign outside Burnbound. If that matters to you, use CDP. Agent wallets: Coinbase CDP vs a local key explains the trade-off.

Step 3: Add the MCP server to Claude Code

The dashboard shows an install command with your agent key already in it. It looks like this:

claude mcp add burnbound --scope user -e BURNBOUND_KEY=bb_agent_… -- npx -y @burnbound/mcp

--scope user makes the server available in every project. Check that it is registered:

claude mcp list

Then start Claude Code and ask: "What is my Burnbound budget?". It calls get_budget and answers with today's spend, the daily cap, the maximum per payment, the allowed hosts and the network. If that works, the key and the connection are fine. The Claude Code integration page covers project scope, permissions and troubleshooting.

Step 4: Make the first paid request

Exa's x402 search takes a POST with a JSON body. Ask Claude Code in plain words, or be explicit:

Use fetch_paid to POST https://api.exa.ai/search with the JSON body
{"query": "x402 payments for AI agents", "numResults": 5}
and the header Content-Type: application/json, with maxAmountUsd "0.02".

maxAmountUsd is a per-call ceiling the MCP server checks on top of your policy. If the price is higher, the call fails with amount_exceeds_max and nothing is paid.

A successful call returns status: "paid" with amountUsd, network, intentId, a receipt and the response body. The body is marked as untrusted third-party content, so text inside it cannot pass itself off as instructions from you. The payment appears in the dashboard with its on-chain transaction.

Step 5: Watch the limit work

Ask for something the policy does not allow, for example a host that is not on the list:

Use fetch_paid to GET https://pro-api.coingecko.com/api/v3/x402/onchain/search/pools?query=weth&network=eth

The MCP server refuses before sending anything: host_not_allowed. If you add the host and the price is over the maximum per payment, you get policy_denied with amount_exceeds_per_transaction. Once the day's spend would pass the daily cap, every payment gets policy_denied with daily_cap_exceeded until midnight UTC. In each case nothing was signed.

Test it on Base Sepolia first

To run the whole flow with test USDC that has no value:

1. Set the agent's network to Base Sepolia in the onboarding, or later in the agent's Red (network) tab.
2. Fund the wallet with test USDC from the Circle faucet.
3. Add demo.burnbound.dev to the allowed hosts.
4. Ask Claude Code: Use fetch_paid to GET https://demo.burnbound.dev/premium with maxAmountUsd "0.05".

Our demo seller charges 0.01 USDC for /premium, 0.50 for /report and 2.00 for /dataset. With the onboarding defaults (1 USD per payment), /premium is paid and /dataset is denied with amount_exceeds_per_transaction; /report waits for approval if the agent's approval threshold is 0.50 USD or lower. It only sells on Base Sepolia. When you are done, switch the agent back to Base and fund the wallet with real USDC on Base.

Let Claude Code find APIs by itself

search_paid_apis searches Burnbound's catalog of verified x402 APIs and tells the agent, for each result, whether its policy would let fetch_paid pay it:

Use search_paid_apis to find an API for crypto prices on Base.

Each result has the host, an example request, the price, and allowedByPolicy with the blockers, such as host_not_allowed. The catalog never widens what the agent may pay: a human still has to add the host. The same catalog is public at /apis.

Next steps

• Make payments above a threshold wait for you: Human approval for agent payments with Slack.
• Understand every limit you can set: How to limit an AI agent's spending.
• Full tool reference: MCP tools.
• Start from scratch with the Quickstart.