# SwapWizard — DeFi Execution Layer for AI Agents
> Quote the market, not your own footprint.
> Non-custodial atomic DeFi execution: swap, zap in/out of LP positions, and route across multiple AMMs in one transaction on 5 EVM chains.
## What SwapWizard does
SwapWizard is a DeFi execution layer that returns signable transaction data — it never signs or broadcasts. An AI agent calls SwapWizard to get the best swap route or liquidity operation, receives `router`, `callData`, and `value`, and presents the transaction to the user's wallet for signing.
## Supported chains
Ethereum (1), Arbitrum (42161), Base (8453), Polygon (137), BNB Chain (56).
`GET /chains` returns full chain metadata: chainId, name, core contract, WETH address, canonical stablecoin, DEX list (name, kind, enabled), position config (V3 NFT managers, Algebra, V4, Balancer, Aerodrome, THENA), liquidity router address, and pool count. Use this to discover available DEXes and resolve NFT position manager addresses for concentrated liquidity operations.
## Available tools (11)
`get_setup_guide`, `get_swap_quote`, `get_clean_quote`, `zap_into_lp_position`, `zap_out_of_lp_position`, `search_liquidity_pools`, `analyze_pool`, `list_user_lp_positions`, `get_supported_chains`, `get_supported_dexes`, `check_api_health`.
After connecting the MCP, call `get_setup_guide` first to receive this same guide within the MCP session.
## Key capabilities
- **Swap quoting**: Best route across Uniswap V2/V3/V4, Curve, Balancer, SushiSwap, PancakeSwap, Aerodrome, and others. Returns callData ready to sign.
- **Clean quote**: Price a swap excluding the caller's own LP position from pool state — eliminates self-impact for rebalancing agents.
- **Zap into LP**: Single-transaction entry into any LP position from ANY input token — it does not have to be one of the pool's tokens. SwapWizard handles all intermediate swaps, LP mint, and price-range setup in a single transaction.
- **Zap out of LP**: Single-transaction exit from any LP position into ANY output token — you can withdraw into any token, not just the pool's underlying tokens. SwapWizard handles LP burn, fee collection, and intermediate swaps in a single transaction. Always pass `sender` (the wallet that owns the position) to enable automatic detection of `nftManager`, `dexName`, and `liquidityKind`.
- **Pool discovery**: Search pools by chain, tokens, type, and trending status. Returns id, poolId, symbol, fee tier, protocol, APY, TVL (USD), and 24h volume (USD). Pass `trending=true` to filter for pools currently trending on GeckoTerminal.
- **Pool analysis**: Real-time momentum data for any pool — multi-timeframe volume (5m–6h), price changes (5m–24h), buy/sell transaction counts, unique traders, and reserve in USD. Data refreshed from GeckoTerminal every 10 minutes.
- **Position tracking**: Full details of every LP position a wallet holds — value, fees, APR, in-range status, impermanent loss.
## Setup requirements
- **SwapWizard API key** — sign in with your wallet at https://swapwizard.xyz/integrators (SIWE, no gas cost).
- **Alchemy RPC URL** — pass as rpcUrl to list_user_lp_positions and get_clean_quote. Without it, position discovery is slower and recently created positions may not appear.
- **Private key or wallet signer** — required to sign and broadcast on-chain transactions (approvals and the main tx). SwapWizard never signs or broadcasts on your behalf.
- **MCP client config** — when creating a `.mcp.json` file for the remote endpoint, set `"type": "streamable-http"` and `"url": "https://mcp.swapwizard.xyz/mcp"` with an `"X-API-Key"` header.
- **Security: use environment variables** — NEVER hardcode secrets in code or config files. Store API keys, private keys, and RPC URLs in environment variables (e.g. `SWAPWIZARD_API_KEY`, `WALLET_PRIVATE_KEY`, `ALCHEMY_RPC_URL`) and reference them from your configuration.
## poolId rule
- `search_liquidity_pools` returns a `poolId` field (string) → pass it **as-is** to `zap_into_lp_position` and `zap_out_of_lp_position`. Do NOT construct, modify, or guess poolId values.
- `search_liquidity_pools` returns an `id` field (number) → use it **only** for `analyze_pool`.
## Operational flows
- **Swap**: get_supported_chains → get_swap_quote → approve router → wait for on-chain confirmation → get_swap_quote again (fresh quote) → send tx to router.
- **Zap in**: search_liquidity_pools → zap_into_lp_position → approve router → wait for on-chain confirmation → zap_into_lp_position again (fresh quote) → send tx to router. The `deposits` array accepts ANY token.
- **Zap out**: list_user_lp_positions → zap_out_of_lp_position → setApprovalForAll(router, true) on the nftManager → wait for on-chain confirmation → zap_out_of_lp_position again (fresh quote) → send tx to router. The `withdrawals` array accepts ANY output token.
- **Analyze**: search_liquidity_pools → analyze_pool with the numeric id.
## Transaction execution
- Quote tools return `router`, `callData`, and `value`.
- Send the transaction to the `router` contract address with `data: callData` and `value: value`. This requires a private key or wallet signer.
- ALWAYS fetch a fresh quote after the approval is confirmed — the previous quote expires and its callData becomes stale.
## Approval rules
- **ERC-20 tokens** (swaps, zap in): call `approve(router, amount)` on the input token contract.
- **NFT-based positions** (zap out): call `setApprovalForAll(router, true)` on the `nftManager` contract. Do NOT use `approve(router, tokenId)` — most position managers only check operator approval.
- **PCS Infinity BIN positions**: call `approveForAll(router, true)` on the `nftManager`.
- **Classic LP pools** (Curve, Balancer, Uniswap V2, Solidly): approve the LP token as a standard ERC-20.
## Integration
### MCP Server (recommended for AI agents)
```
npx -y @swapwizard/mcp-server
```
Remote endpoint: `https://mcp.swapwizard.xyz/mcp` (streamable-http transport, pass API key via `X-API-Key` header).
npm: https://www.npmjs.com/package/@swapwizard/mcp-server
### REST API
Base URL: `https://api.swapwizard.xyz/api/v2.0`
Authentication: `X-API-Key` header or `?apikey=` query parameter.
Rate limit: 60 requests/minute per API key.
API docs: https://swapwizard.xyz/api-docs
### Widget (for web integrations)
```html
```
Configurator: https://swapwizard.xyz/developers
## Affiliate program
Pass `affiliateCode` (a registered wallet address) in swap and liquidity tools to earn on-chain fees. Configure at https://swapwizard.xyz/developers.
## Links
- Website: https://swapwizard.xyz
- API docs: https://swapwizard.xyz/api-docs
- MCP server card: https://swapwizard.xyz/.well-known/mcp-server-card.json
- AI agent docs: https://swapwizard.xyz/ai-agents
- Widget configurator: https://swapwizard.xyz/developers
- npm: https://www.npmjs.com/package/@swapwizard/mcp-server
- Contact: contact@swapwizard.xyz