Quickstart: Claude Code and Cursor

This guide takes you from a new Burnbound account to your agent's first fetch_paid call. You create an agent with spending rules, connect the wallet that signs its payments, add the Burnbound MCP server to Claude Code or Cursor, and make a first request.

What do I need before I start?

You need Node.js 20 or later (with npx on the PATH of your MCP client), Claude Code or Cursor, and a Burnbound account. To pay for something, you also need a wallet with a small USDC balance on the agent's network: Base for real payments, or Base Sepolia to test with free test USDC. Burnbound never holds funds: payments come from your own wallet.

• Node.js 20 or later: check with node --version.
• An MCP client: Claude Code or Cursor. Any other MCP client that runs stdio servers works the same way.
• A Burnbound account: create one at app.burnbound.dev.

Step 1: How do I create an agent and its key?

Create the agent in the Burnbound dashboard; the onboarding starts right after you register. An agent has a name, a daily cap, a maximum per payment, a list of allowed hosts and the network it pays on. Keep the caps small at first: x402 calls usually cost cents.

1. Open the onboarding in the dashboard and create the agent.
2. Set the daily cap, the maximum per payment and the hosts the agent may pay, for example api.example.com or *.example.com.
3. Choose the network: Base for real payments (the default) or Base Sepolia to test with test USDC. See Which network should my agent use?.
4. Continue to the wallet step (Step 2). The key is created in the step after it.

The agent key starts with bb_agent_. The dashboard shows it only once, inside a ready-to-paste install command. Burnbound stores only a hash of it, so a lost key cannot be shown again: revoke it and create a new one.

Which network should my agent use?

Each agent pays USDC on one network. The seller's x402 API must charge on that same network; if it asks for another one, the payment is denied with network_not_allowed and nothing is signed.

You choose the network when you create the agent in the onboarding. To change it later, open the agent in the dashboard and use its Red (network) tab. The change applies to the agent's next payment. Fund the wallet on the network you chose: USDC on Base Sepolia cannot pay a seller on Base, and the other way round.

Step 2: How do I connect the wallet that signs?

Every agent needs a wallet that signs its payments. Burnbound decides whether a payment is allowed; the wallet signs it. You choose one of two modes in the dashboard. See Concepts for the trade-offs.

Coinbase CDP. Paste your Coinbase Developer Platform credentials (API key ID, API key secret, wallet secret) and the wallet address. The private key stays with Coinbase.

Wallet on your machine (client-side signing). Create the wallet locally and register only its public address:

npx -y @burnbound/mcp wallet init

The command prints the address. Paste it in the dashboard. The private key stays in your OS keychain (or a file only your user can read) and is never sent to Burnbound.

Then fund the wallet with a small USDC balance on the agent's network: real USDC on Base, or test USDC from the Circle faucet on Base Sepolia. It needs no ETH: in x402 the seller's facilitator submits the transfer and pays the gas.

Step 3: How do I add Burnbound to Claude Code?

Run claude mcp add with your agent key in BURNBOUND_KEY. The dashboard shows this exact line with your key already filled in; copy it from there.

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

Check that the server is registered:

claude mcp list

How do I add Burnbound to Cursor?

Add the server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project, with your agent key in env:

{
  "mcpServers": {
    "burnbound": {
      "command": "npx",
      "args": ["-y", "@burnbound/mcp"],
      "env": {
        "BURNBOUND_KEY": "bb_agent_…"
      }
    }
  }
}

Do not commit a file that contains the key. Restart Cursor or reload its MCP servers after you edit the file.

Using Claude Desktop, the Vercel AI SDK, LangChain.js or Mastra? The integrations have the exact setup for each, and the Claude Code and Cursor pages cover project-level config, permissions and troubleshooting.

Step 4: How do I check that the agent is connected?

Ask your agent: "What is my Burnbound budget?". It calls get_budget, which returns what the agent spent today, its daily cap, what remains, the maximum per payment, its approval threshold, when the daily spend resets, its network and its allowed hosts. If that works, the key and the connection to Burnbound are fine.

If the server does not start, read its log on stderr (in Claude Code, claude mcp list shows it as failed):

• BURNBOUND_KEY is required.: the key is missing from the MCP config.
• BURNBOUND_KEY has an invalid format.: the value was pasted with extra characters.

If it starts but every tool answers unauthorized, the key was revoked or mistyped. Create a new one in the dashboard.

Step 5: How do I make the first paid request?

Ask the agent to fetch a URL of an x402 API on one of its allowed hosts, with a small maxAmountUsd. The API must charge on the agent's network: for a first test without real money, use an agent on Base Sepolia and an x402 API that charges on Base Sepolia. The agent calls fetch_paid; if the URL answers HTTP 402, Burnbound checks the payment against your rules, the wallet signs it, and the agent gets the paid response.

A prompt like this is enough:

Use fetch_paid to GET https://api.example.com/v1/report with maxAmountUsd "0.05".

The result tells you what happened:

• paid: the payment was signed and sent. It includes amountUsd, intentId and a receipt. The payment appears in the dashboard.
• ok: the URL did not ask for payment, so nothing was paid.
• pending_approval: the amount is at or above the agent's approval threshold. A human approves it in the dashboard, then the agent retries (see Concepts).
• A tool error with a code, such as policy_denied or host_not_allowed: nothing was paid. A denial is also a good first test: it proves the rules are enforced. Denials are listed in the dashboard audit with their reason.

Try it against our demo seller (Base Sepolia)

To try the whole flow without a real seller, use our demo x402 seller at https://demo.burnbound.dev. It is testnet only: it sells on Base Sepolia (eip155:84532) for test USDC, and nothing it serves has real value. Never pay it from a wallet that holds real funds.

Before you start, add demo.burnbound.dev to the agent's allowed hosts and fund its wallet with Base Sepolia USDC from Circle's faucet. The agent's policy must allow Base Sepolia: an agent that allows Base mainnet only, the default for new agents, gets policy_denied with network_not_allowed, and nothing is paid. Give fetch_paid a maxAmountUsd at or above the price, for example:

Use fetch_paid to GET https://demo.burnbound.dev/premium with maxAmountUsd "0.05".

What can go wrong on the first call?

Most first-call errors come from the agent's rules or its wallet, and every one means nothing was paid. The table lists the common ones; the MCP tools reference has the full list.