x402-mcp 0.4.0
MCP tools for AI agents — HTTP requests with automatic x402 micropayments
Requires Python: >=3.11

# x402-mcp

[![PyPI](https://img.shields.io/pypi/v/x402-mcp)](https://pypi.org/project/x402-mcp/)
[![CI](https://github.com/dsr-restyn/x402-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/dsr-restyn/x402-mcp/actions)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/x402-mcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

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

x402-mcp is an [MCP](https://modelcontextprotocol.io/) server that adds HTTP request tools with automatic [x402](https://www.x402.org/) 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

```bash
# 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. Output the MCP config JSON, ready to paste

### Add to your MCP client

Paste the config into `~/.claude/mcp.json` (Claude Code) or your Cursor MCP settings:

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

Your agent now has two tools:

| Tool | Description |
|---|---|
| `x402_fetch` | HTTP requests to any URL — shows payment details for confirmation, then pays on approval |
| `wallet_info` | Returns your wallet's public address for funding/verification |

## 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:**
```
wallet_info()
```

## 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

```bash
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:
```bash
EVM_PRIVATE_KEY=0x... X402_TEST_URL=https://some-x402-api.com/endpoint \
  uv run python scripts/test_e2e.py
```

## License

MIT