x402-mcp

Give your AI agent a wallet. It pays for APIs automatically.

x402-mcp is an MCP server that adds HTTP request tools with automatic x402 micropayments to any AI agent. When a request hits a 402-gated endpoint, payment happens automatically — no API keys, no accounts, no billing dashboards.

Works with any x402-enabled service. Not locked to a single provider.

How it works

Agent calls x402_fetch("https://some-api.com/data")
    → Server responds 402 Payment Required
    → x402-mcp returns payment details (amount, network, recipient)
    → Agent shows details to user, user approves
    → Agent calls x402_fetch(url, confirm_payment=True)
    → x402-mcp signs a gasless EIP-712 payment authorization
    → Agent gets the response ✓

By default, your agent confirms payments with the user before paying. Set X402_CONFIRM_PAYMENTS=false to auto-pay without confirmation (original behavior).

Quick start

# Install and run the setup wizard
uvx x402-mcp-setup

The wizard will:

1. Generate a fresh EVM wallet (or use your existing key with --key)
2. Show a QR code for your wallet address
3. Print funding instructions (testnet USDC is free)
4. Offer to write the MCP config directly to ~/.claude/mcp.json (press Enter to accept)
5. Offer to watch for your first USDC deposit and confirm when it arrives

Then restart Claude Code or Cursor — the server loads automatically.

{
  "mcpServers": {
    "x402-mcp": {
      "command": "uvx",
      "args": ["x402-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0xYourPrivateKey",
        "X402_CONFIRM_PAYMENTS": "true"
      }
    }
  }
}

Your agent now has two tools:

Usage examples

Fetch from an x402-gated API (with payment confirmation):

# Step 1: Agent makes request, gets payment details
x402_fetch(url="https://api.example.com/data")
# → Returns: {payment_required: True, human_readable: {amount: "1000000", ...}}

# Step 2: After user approves, agent confirms payment
x402_fetch(url="https://api.example.com/data", confirm_payment=True)
# → Returns: {status: 200, body: "..."}

POST with JSON body:

x402_fetch(
    url="https://api.example.com/submit",
    method="POST",
    headers={"Content-Type": "application/json"},
    body='{"query": "hello"}'
)

Check your wallet address and balances:

wallet_info()
# → Returns: {address: "0x...", balances: {Base: {ETH: "0.001000", USDC: "5.000000", ...}, ...}}

Architecture

src/x402_mcp/
├── mcp_server.py   # FastMCP server — x402_fetch + wallet_info tools
└── setup.py        # Wallet generation wizard, prints MCP config JSON

Two entry points:

• x402-mcp — MCP stdio server (what your agent connects to)
• x402-mcp-setup — Interactive setup wizard

The server lazy-initializes an x402HttpxClient on first tool call. Payments are gasless EIP-712 signed authorizations — no on-chain transaction per request. Binary responses (images, etc.) are returned as base64-encoded data.

Development

uv sync --extra dev    # Install deps
uv run ruff check src/ # Lint
uv run pytest tests/ -v # Test

E2E test against a real x402 endpoint:

EVM_PRIVATE_KEY=0x... X402_TEST_URL=https://some-x402-api.com/endpoint \
  uv run python scripts/test_e2e.py

License

MIT