v0.6.2  ·  quickstart

Get started in 5 minutes.

Install x402-mcp, discover live paid APIs, and make your first agent payment. No accounts. No API keys per service.

1

Add to your MCP config

Add x402-mcp to your Claude, Cursor, or Windsurf config. No signup required.

claude_desktop_config.json / .cursor/mcp.json / ~/.claude.json 
{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["-y", "@nullbuilds/x402-mcp"]
    }
  }
}

Restart your client after saving. The package downloads automatically on first use.

2

Try it — no wallet needed

Discovery and estimation tools work immediately with no credentials. Ask your agent:

Try these prompts
→ "Find me x402 weather APIs"
  discover_paid_services returns 15 live results with prices

→ "What does it cost to call x402-data-bazaar.vercel.app/api/weather/current?"
  estimate_payment probes live — no payment made

→ "Check the USDC balance of 0x000...000"
  check_wallet_balance reads on-chain
3

Set up a wallet to make paid calls

x402-mcp never stores or manages keys — you bring your own. Two options:

Use a dedicated wallet with a small balance. Generate a fresh address just for x402 payments — not your main wallet. If the key is ever exposed, worst case you lose your spending float.

Generate a new wallet address:

Terminal
# With Foundry (cast)
cast wallet new

# Or use Coinbase, MetaMask, Rainbow — any ETH wallet works

Fund it with USDC on Base. From Coinbase: Withdraw → select Base network → USDC. $5 covers hundreds of calls.

Add the private key to your MCP config:

MCP config — env section 
{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["-y", "@nullbuilds/x402-mcp"],
      "env": {
        "X402_PRIVATE_KEY": "0x..."
      }
    }
  }
}
CDP uses a hardware-backed TEE. Your private key is generated and stored in Coinbase's secure enclave — it never touches your machine.

1. Go to portal.cdp.coinbase.com and create a project.

2. Generate an API key — you'll get CDP_API_KEY_ID and CDP_API_KEY_SECRET.

3. Create a Server Wallet — you'll get CDP_WALLET_SECRET.

4. Add to your MCP config:

MCP config — env section 
{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["-y", "@nullbuilds/x402-mcp"],
      "env": {
        "CDP_API_KEY_ID": "your-key-id",
        "CDP_API_KEY_SECRET": "your-key-secret",
        "CDP_WALLET_SECRET": "your-wallet-secret"
      }
    }
  }
}

5. Ask your agent "What's my x402 wallet address?" — then fund that address with USDC on Base.

4

Make your first paid call

Ask your agent to call a live API. It discovers, estimates, pays, and returns the result in one shot.

Example prompts
→ "Get the current weather in San Francisco"
  Finds weather API · estimates $0.005 · pays · returns conditions

→ "What's the median household income for ZIP 90210?"

→ "Vet this company name against the OFAC sanctions list"

→ "Decode this VIN: 1HGBH41JXMN109186"

All payments are logged to ~/.x402-mcp/history.jsonl. Ask "Show my payment history" to review.

Tool reference
discover_paid_services
Browse 957 verified x402 APIs. Filter by keyword or network. Returns live endpoints with pricing and descriptions.
free
Parameters
NameTypeDescription
query string optional Search term. E.g. "weather", "FDA", "sanctions".
network string optional Filter by network. E.g. "base", "ethereum".
limit number optional Max results. Default 20, max 100.
ReturnsList of APIs with URLs, cost per call, network, and description.
estimate_payment
Probe a URL and return its x402 payment requirements. No payment made.
free
Parameters
NameTypeDescription
resource_url string required Full URL to probe.
method string optional "GET" or "POST". Default "GET".
ReturnsPrice in USDC, recipient address, network, and timeout.
check_wallet_balance
Check the USDC balance of any wallet address on Base. Read-only — no wallet connection required.
free
Parameters
NameTypeDescription
wallet_address string required Wallet address (0x...) or ENS name.
ReturnsUSDC balance on Base.
get_service_details
Full payment requirements for a specific x402 URL — all options, networks, and pricing.
free
Parameters
NameTypeDescription
resource_url string required Exact URL of the x402 resource (from catalog).
ReturnsAll payment options with costs, networks, and recipient addresses.
make_x402_request
Pay and call an x402 API in one shot. Handles the full payment flow automatically. Returns the API response.
wallet required
Parameters
NameTypeDescription
resource_url string required URL of the x402 API to call.
max_cost_usdc number optional Spending cap per call. Request aborts if cost exceeds this. Default 1.0.
method string optional "GET" or "POST". Default "GET".
body string optional JSON body for POST requests.
ReturnsAPI response body with payment receipt (amount, wallet, timestamp).
get_my_wallet
Returns your configured wallet address, or step-by-step setup instructions if no wallet is configured.
wallet required
Parameters
none
ReturnsWallet address and USDC balance link, or setup instructions.
get_payment_history
Recent x402 payment history — APIs called, amounts paid, and status.
wallet required
Parameters
NameTypeDescription
limit number optional Records to return. Default 20, max 100.
ReturnsPayments sorted newest first with URL, cost, status, and timestamp.