tollboothswap-mcp

# tollboothswap-mcp — Token Swaps & Honeypot Checks for AI Agents (MCP Server)

MCP server for [Tollbooth](https://api.tollboothswap.xyz): non-custodial token
swap execution and token safety screening on **8 chains** — Solana, Base,
Ethereum, Arbitrum, Polygon, Optimism, BSC, Avalanche. Quotes and symbol
resolution are free; swap builds (~$0.005) and safety checks ($0.01) are paid
per-call in USDC via the [x402 protocol](https://www.x402.org) — no API keys,
no accounts, no subscriptions.

## Quick start

```bash
npx tollboothswap-mcp
```

### Claude Desktop / Cursor / any MCP client

```json
{
  "mcpServers": {
    "tollbooth": {
      "command": "npx",
      "args": ["-y", "tollboothswap-mcp"],
      "env": {
        "TOLLBOOTH_PAYER_KEY": "0x<EVM private key holding USDC on Base>"
      }
    }
  }
}
```

`TOLLBOOTH_PAYER_KEY` is optional: without it the free tools
(`resolve_token`, `get_quote`, `get_service_info`, `get_receipt`) work fully,
and paid tools return x402 payment instructions instead of results. With it,
tolls are paid automatically and gaslessly (EIP-3009 — the key never spends
gas, only USDC).

## Tools

| Tool | Cost | What it does |
| --- | --- | --- |
| `resolve_token` | free | Ticker symbol → contract addresses, ranked by DEX liquidity |
| `get_quote` | free | Fee-inclusive indicative swap quote |
| `check_token` | $0.01 | Honeypot / rug-pull / freeze-authority / sell-tax screening with verdict + findings |
| `build_swap` | ~$0.005 | Unsigned, ready-to-sign swap transaction + HMAC-signed receipt (`safeMode` screens both tokens first) |
| `get_receipt` | free | Verify a past build receipt by id |
| `get_service_info` | free | Service manifest: chains, fees, pricing |

## Trust model

Tollbooth is non-custodial: it builds transactions but never holds keys or
funds. Your agent signs and submits everything with its own wallet. Every
paid build returns a signed receipt for audit trails.

## Links

- Full tutorial: https://api.tollboothswap.xyz/guides/agent-swaps.md
- Agent usage guide: https://api.tollboothswap.xyz/skill.md
- Runnable HTTP examples: https://github.com/soundsparkaudiolab/tollbooth-examples

## License

MIT