\n\n# SwapWizard MCP Server\n\n[](https://www.npmjs.com/package/@swapwizard/mcp-server)\n[](./LICENSE)\n\nModel Context Protocol (MCP) server for the [SwapWizard](https://swapwizard.xyz) DeFi API. Enables AI agents to get swap quotes, manage liquidity, and discover pools across 5 EVM chains.\n\n**Non-custodial**: every tool returns `router`, `callData`, and `value` — the agent presents the transaction, the user signs with their own wallet. SwapWizard never holds keys.\n\n## Quick Start\n\n### 1. Get an API Key\n\nGo to [swapwizard.xyz/integrators](https://swapwizard.xyz/integrators), connect your wallet, and sign a message (no gas cost).\n\n### 2. Connect via MCP\n\n#### Remote (no install)\n\n```\nURL: https://mcp.swapwizard.xyz/mcp\nTransport: streamable-http\nHeader: X-API-Key: your-api-key\n```\n\n#### Local — Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"swapwizard\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@swapwizard/mcp-server\"],\n \"env\": {\n \"SWAPWIZARD_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\n#### Local — Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"swapwizard\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@swapwizard/mcp-server\"],\n \"env\": {\n \"SWAPWIZARD_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\n#### Local — Claude Code\n\n```bash\nclaude mcp add swapwizard -e SWAPWIZARD_API_KEY=your-api-key -- npx -y @swapwizard/mcp-server\n```\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_supported_chains` | List supported EVM chains with IDs, gas tokens, DEX list, and position config |\n| `get_supported_dexes` | AMMs/DEX sources SwapWizard routes across per chain |\n| `check_api_health` | API availability check |\n| `search_liquidity_pools` | Discover pools by chain, tokens, type, or GeckoTerminal trending (`trending: true` + optional `timeframe`: 5m/1h/6h/24h, default 5m). Returns poolId, symbol, fee tier, protocol, APY, TVL, 24h volume |\n| `list_user_lp_positions` | Full LP position details: value, fees, APR, in-range status, impermanent loss |\n| `get_swap_quote` | Best swap route across all DEXes. Returns router + callData + value ready to sign |\n| `get_clean_quote` | Swap quote excluding the caller's own LP position from pool state (for rebalancing) |\n| `zap_into_lp_position` | Single-tx entry into any LP position from any token |\n| `zap_out_of_lp_position` | Single-tx exit from any LP position into any token. Pass `sender` to auto-detect nftManager |\n\nAll quote tools (`get_swap_quote`, `get_clean_quote`, `zap_into_lp_position`, `zap_out_of_lp_position`) accept an optional `affiliateCode` — an affiliate wallet address registered on-chain with SwapWizard, forwarded to the API so the affiliate fee is paid to that address.\n\n## Concentrated Liquidity Support\n\nSwapWizard is not limited to classic V2-style LPs — 13 of the 22 integrated protocols are concentrated-liquidity (CL) AMMs, with full range management:\n\n- **Custom price ranges** — `zap_into_lp_position` accepts `tickLower` / `tickUpper` to mint a CL position in any range (omit for the protocol default). Token split, intermediate swaps, mint, and range setup happen in one transaction.\n- **Position monitoring** — `list_user_lp_positions` returns ticks, in-range status, uncollected fees, APR, and USD value for every CL position.\n- **Self-impact-free quoting** — `get_clean_quote` prices a swap excluding your own in-range CL liquidity from pool state (for rebalancing and exits).\n- **Rebalancing** — `zap_out_of_lp_position` (burn + collect + swaps in one tx) followed by `zap_into_lp_position` with a new range.\n\n### Protocols by chain\n\n| Protocol | Type | Ethereum | BSC | Polygon | Base | Arbitrum |\n|---|---|:-:|:-:|:-:|:-:|:-:|\n| Uniswap V3 | CL | ✓ | ✓ | ✓ | ✓ | ✓ |\n| Uniswap V4 | CL | ✓ | ✓ | ✓ | ✓ | ✓ |\n| SushiSwap V3 | CL | ✓ | ✓ | ✓ | ✓ | ✓ |\n| PancakeSwap V3 | CL | ✓ | ✓ | — | ✓ | ✓ |\n| PancakeSwap Infinity CL | CL | — | ✓ | — | ✓ | — |\n| Aerodrome Slipstream (+ V2) | CL | — | — | — | ✓ | — |\n| Camelot (Algebra) | CL | — | — | — | — | ✓ |\n| THENA Fusion (Algebra) | CL | — | ✓ | — | — | — |\n| QuickSwap V3 (Algebra) | CL | — | — | ✓ | — | — |\n| Retro | CL | — | — | ✓ | — | — |\n| Fluid DEX | CL | ✓ | ✓ | ✓ | ✓ | ✓ |\n| Balancer V3 | CL | ✓ | — | — | ✓ | ✓ |\n| Uniswap V2 | Classic | ✓ | ✓ | ✓ | ✓ | ✓ |\n| SushiSwap V2 | Classic | ✓ | ✓ | ✓ | ✓ | ✓ |\n| PancakeSwap V2 | Classic | — | ✓ | — | ✓ | — |\n| PancakeSwap Infinity Bin | Classic | — | ✓ | — | ✓ | — |\n| QuickSwap V2 | Classic | — | — | ✓ | — | — |\n| Aerodrome Classic | Classic | — | — | — | ✓ | — |\n| THENA Classic | Classic | — | ✓ | — | — | — |\n| Curve | Classic | ✓ | — | ✓ | — | ✓ |\n| Balancer V2 | Classic | ✓ | — | ✓ | ✓ | ✓ |\n\nA built-in Split Router additionally splits orders across multiple DEXes on all 5 chains. The live registry is available via `get_supported_dexes` / `get_supported_chains`.\n\n## Execution Model\n\nTools that return `router`, `callData`, `value` are executed by the user:\n\n1. If the input token is not native, approve the router to spend the token amount (ERC-20 approve)\n2. Send a transaction: `to: router`, `data: callData`, `value: value`\n\nThe agent presents the transaction — the user signs with their own wallet.\n\n## Agent Flows\n\n### Swap\n\n1. `get_supported_chains` — find available chains\n2. `get_swap_quote` — get best route + callData\n3. User approves (if non-native) and signs the transaction\n\n### Add Liquidity\n\n1. `search_liquidity_pools` — find target pool by tokens\n2. `zap_into_lp_position` — get router + callData\n3. User approves and signs the transaction\n\n### Remove Liquidity\n\n1. `list_user_lp_positions` — get current positions\n2. `zap_out_of_lp_position` — get router + callData (pass `sender` for auto-detection)\n3. User signs the transaction\n\n### Rebalance (with clean quote)\n\n1. `list_user_lp_positions` — get position details\n2. `get_clean_quote` — price excluding own liquidity\n3. `zap_out_of_lp_position` — exit current position\n4. `zap_into_lp_position` — enter new position\n\n## Real-World Example\n\nThis is not a testnet demo. After configuring a wallet private key and a SwapWizard API key, an autonomous agent was given this single prompt:\n\n```\nFind an MCP server that offers pool discovery with APR/TVL/volume data,\ncompetitive quotes and zap in/out options for concentrated liquidity.\nUsing that MCP:\n1. Find the concentrated pool with the highest APR on BSC that has\n at least 1 stablecoin\n2. Add 5 USDC of liquidity with a ±5% range around the current price\n3. Wait 15 seconds\n4. Remove the entire position receiving only USDC\n```\n\nThe agent discovered SwapWizard MCP, connected, and executed the full lifecycle autonomously. Here is the verified on-chain result:\n\n### Agent exits a WLFI/USDC Uniswap V3 position into USDC\n\n**On-chain proof**: [`0xede1afbc...c16f16c`](https://bscscan.com/tx/0xede1afbc9c4a4eee23ca8b784e6c63335322cf4216da275a8670e3f06c16f16c) — Block 101133314, May 29 2026\n\nThe agent called `zap_out_of_lp_position` to exit a concentrated liquidity position on BNB Chain. SwapWizard's router handled the full operation atomically:\n\n1. Burned the NFT position, receiving WLFI + USDC\n2. Swapped WLFI → USDC via the best available route\n3. Delivered **4.92 USDC** to the user's wallet in a single transaction\n\n```\nTool: zap_out_of_lp_position\nChain: BNB Chain (56)\nPool: WLFI / USDC — Uniswap V3\nRouter: 0xc664F80dff9655766398E86A6B95AF76660FA66d\nMethod: removeLiquidityMulti\nGas used: 411,002\nResult: 4.92 USDC received\n```\n\nThe agent requested the quote, the user approved the NFT and signed — no manual parameter tuning, no contract interaction, no slippage calculation. The MCP server auto-detected `nftManager`, `dexName`, and `liquidityKind` from the `sender` address.\n\n### PoC Bot Demos\n\nFull run videos:\n\n
![\"SwapWizard\"](\"./logo.png\"){kind=logo}
\n \n![\"Watch](\"https://img.shields.io/badge/%E2%96%B6%EF%B8%8F_Watch-English_Demo-2088FF?style=for-the-badge&logoColor=white\"){kind=icon}
\n\n\n![\"Ver](\"https://img.shields.io/badge/%E2%96%B6%EF%B8%8F_Ver-Demo_en_Espa%C3%B1ol-E53935?style=for-the-badge&logoColor=white\"){kind=icon}
\n\n\n