Non-custodial DeFi for AI agents: swaps, concentrated liquidity (V3/V4) zaps + ranges, 5 EVM chains
SwapWizard MCP Server
This Model Context Protocol (MCP) server integrates the SwapWizard DeFi API for AI agents. It provides non-custodial functions for obtaining swap quotes, managing liquidity, and discovering pools across 5 EVM chains. The server exposes tools countable as 11, aligned with SwapWizard’s DeFi capabilities for swaps and concentrated liquidity.
🛠️ Key Features
Non-custodial DeFi for AI agents
Swap quotes
Concentrated liquidity support (V3/V4 zaps + ranges)
Pool discovery
Coverage for 5 EVM chains
11 tools
🚀 Use Cases
Retrieve swap quotes for cross-chain execution on supported EVM networks
Generate call data to manage concentrated liquidity positions
Discover pools on the 5 EVM chains accessible via SwapWizard
⚡ Developer Benefits
Non-custodial tool outputs that include router and callData (as stated in the excerpt)
⚠️ Limitations
Only supports swaps, liquidity management, and pool discovery via SwapWizard across 5 EVM chains
Captured live from the server via tools/list.
get_setup_guide
Returns the complete setup and usage guide for SwapWizard. Call this FIRST before using any other tool. Covers: required configuration (API key, Alchemy RPC URL, private key), how to use poolId correctly, step-by-step operational flows for swap/zap in/zap out/analyze, transaction execution details, and approval rules.
Returns the AMMs / DEX sources SwapWizard routes across per chain. Each DEX includes its display name and slug (e.g. "uniswap-v3") — use the slug as the 'project' filter in search_liquidity_pools to filter pools by protocol.
Parameters1
chainId
integer
optional
EVM chain ID to filter results. If omitted, returns protocols for all supported chains.
Raw schema
{
"type": "object",
"properties": {
"chainId": {
"description": "EVM chain ID to filter results. If omitted, returns protocols for all supported chains.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
search_liquidity_pools
Maps to GET /pools. Discovers liquidity pools across supported AMMs and chains, returning id, poolId, symbol, underlyingTokens (token addresses), fee tier, protocol, dexKind, APY, apyBase (fee-only APY excluding reward emissions), TVL (USD), 24h/7d volume (USD), stablecoin flags, and hooksAddress (custom hook contract for Uniswap V4 / PancakeSwap Infinity pools; null when the pool has no hook — hooks can add custom fees or transfer restrictions). KEY PARAMETERS: Use `trending: true` to get only pools currently trending, optionally with `timeframe` ("5m", "1h", "6h", "24h") to select the ranking window — default is 5m. Trending results include `feeAprEstimate`: fee APR (%) annualized from the selected timeframe's volume window over the pool reserve (null outside trending mode or when the fee tier is unknown). NOTE: `feeAprEstimate` extrapolates a short window to a year — for short timeframes on hot pools it can be extreme and short-lived; the `apy` field is the stable 24h-based metric.
MOMENTUM SIGNAL (1h/6h/24h windows, powered by on-chain DEX trade data): each trending pool carries `momentumSignal` — "entry" (volume accelerating with healthy LP flow — a pool worth entering), "watch" (in the ranking but not yet actionable), or "exit" (dying volume or LPs leaving). Supporting fields: `momentumScore` (composite acceleration x size x flow quality), `momentumRatioH1/H6/H24` (volume vs the previous equal window), `momentumTakersH6` (unique traders 6h), `lpMintsH6/lpBurnsH6` and `lpNetFlowH6` (inflow/outflow/flat — are LPs adding or pulling liquidity). The 5m window carries the signal as HOURLY CONTEXT (last hourly cycle, not the last 5 minutes), since 5m is real-time GeckoTerminal data. Each pool also carries `suggestedRangePct`: a suggested concentrated-liquidity range (± percent) balancing fee density against time-in-range — ~0.5% for stable pairs, tens of percent for volatile/memecoin pairs — pass it to zap_into_lp_position. To ENTER the hottest profitable pool: `trending: true, timeframe: "6h", signal: "entry", sortBy: "signal", sortOrder: "desc"` returns entry-signal pools ranked by APR. (Use timeframe "6h" for sustained traction / LP-yield strategies, "1h" for faster reaction.) To check whether to EXIT, read `momentumSignal` on list_user_lp_positions instead.
Use `hookless: true` to exclude pools with a custom hook contract. Use `sortBy` ("apy", "tvl", "volume1d", "volume7d", "signal") with `sortOrder` to control ranking — default is tvl desc. Use `topPerVenue` to limit to top N pools per DEX by APY. Supports filtering by protocol/DEX, tokens, pool type, stablecoin status, and free-text search, with pagination. Required upstream step before zap_into_lp_position. IMPORTANT: The response contains two ID fields — `poolId` (string) must be passed AS-IS to zap_into_lp_position and zap_out_of_lp_position (do NOT construct or modify it), and `id` (number) is used only for analyze_pool.
Parameters17
chainId
integer
required
EVM chain ID (e.g. 56 for BSC, 1 for Ethereum)
project
string
optional
Filter by protocol/DEX name (e.g. uniswap-v3, pancakeswap-v3, aerodrome-v2)
dexKind
string
optional
Filter by DEX kind (e.g. UNIV3_SR02)
tokens
string
optional
Comma-separated token addresses to filter pools by
search
string
optional
Search by symbol or project name
poolType
string
optional
Filter by pool type
hookless
boolean
optional
If true, exclude pools with a custom hook contract (Uniswap V4 / PancakeSwap Infinity). Hooks can add custom fees or transfer restrictions.
stableOnly
boolean
optional
Show only stablecoin pairs
semiStableOnly
boolean
optional
Show only pools with exactly one stablecoin
sortBy
string
optional
Sort field (default: tvl). 'signal' (trending only) groups pools by momentum signal entry→watch→exit (sortOrder=asc reverses) and within each group by APR descending — i.e. the entry pools with the highest APR first.
sortOrder
string
optional
Sort direction (default: desc)
signal
string
optional
Filter by momentum signal. Comma-separated list allowed (e.g. 'entry' or 'entry,watch'). Only effective with trending=true. Combine with sortBy=signal&sortOrder=desc to get entry pools ranked by APR.
topPerVenue
integer
optional
Limit to top N pools per venue by APY
trending
boolean
optional
If true, return only currently trending pools (with momentumSignal and suggestedRangePct on each result)
timeframe
string
optional
Trending ranking window (default: 5m). Only applies with trending=true. Sent to the API as trendingDuration; also selects the volume window for feeAprEstimate. Use 6h for sustained LP-yield traction, 1h for faster reaction; 5m is real-time GeckoTerminal with the signal as hourly context.
page
integer
optional
Page number, 0-based (default: 0)
pageSize
integer
optional
Results per page, max 200 (default: 50)
Raw schema
{
"type": "object",
"properties": {
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "EVM chain ID (e.g. 56 for BSC, 1 for Ethereum)"
},
"project": {
"description": "Filter by protocol/DEX name (e.g. uniswap-v3, pancakeswap-v3, aerodrome-v2)",
"type": "string"
},
"dexKind": {
"description": "Filter by DEX kind (e.g. UNIV3_SR02)",
"type": "string"
},
"tokens": {
"description": "Comma-separated token addresses to filter pools by",
"type": "string"
},
"search": {
"description": "Search by symbol or project name",
"type": "string"
},
"poolType": {
"description": "Filter by pool type",
"type": "string",
"enum": [
"classic",
"concentrated"
]
},
"hookless": {
"description": "If true, exclude pools with a custom hook contract (Uniswap V4 / PancakeSwap Infinity). Hooks can add custom fees or transfer restrictions.",
"type": "boolean"
},
"stableOnly": {
"description": "Show only stablecoin pairs",
"type": "boolean"
},
"semiStableOnly": {
"description": "Show only pools with exactly one stablecoin",
"type": "boolean"
},
"sortBy": {
"description": "Sort field (default: tvl). 'signal' (trending only) groups pools by momentum signal entry→watch→exit (sortOrder=asc reverses) and within each group by APR descending — i.e. the entry pools with the highest APR first.",
"type": "string",
"enum": [
"apy",
"tvl",
"volume1d",
"volume7d",
"signal"
]
},
"sortOrder": {
"description": "Sort direction (default: desc)",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"signal": {
"description": "Filter by momentum signal. Comma-separated list allowed (e.g. 'entry' or 'entry,watch'). Only effective with trending=true. Combine with sortBy=signal&sortOrder=desc to get entry pools ranked by APR.",
"type": "string"
},
"topPerVenue": {
"description": "Limit to top N pools per venue by APY",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"trending": {
"description": "If true, return only currently trending pools (with momentumSignal and suggestedRangePct on each result)",
"type": "boolean"
},
"timeframe": {
"description": "Trending ranking window (default: 5m). Only applies with trending=true. Sent to the API as trendingDuration; also selects the volume window for feeAprEstimate. Use 6h for sustained LP-yield traction, 1h for faster reaction; 5m is real-time GeckoTerminal with the signal as hourly context.",
"type": "string",
"enum": [
"5m",
"1h",
"6h",
"24h"
]
},
"page": {
"description": "Page number, 0-based (default: 0)",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"pageSize": {
"description": "Results per page, max 200 (default: 50)",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"chainId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
analyze_pool
Maps to GET /pools/analyze/:id. Returns real-time momentum data for a specific pool from GeckoTerminal: multi-timeframe volume (5m, 15m, 30m, 1h, 6h), price changes (5m–24h), buy/sell transaction counts, unique traders (24h), and reserve in USD. Data is cached for 10 minutes; stale entries are refreshed on-demand. Use the numeric id field returned by search_liquidity_pools.
Parameters1
id
integer
required
Pool numeric ID (from the id field in search_liquidity_pools response)
Raw schema
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Pool numeric ID (from the id field in search_liquidity_pools response)"
}
},
"required": [
"id"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
list_user_lp_positions
Maps to GET /positions. Reads all LP positions a wallet holds on a given chain by calling the SwapWizard API, which discovers positions across all supported protocols: Uniswap V2/V3/V4, Aerodrome, Thena, SushiSwap, PancakeSwap, Algebra, Balancer, Curve, and all Solidly forks. Each position includes positionId, nftManager, dexName, liquidityKind, token addresses, amounts, fees, in-range status, APR, and USD values. EXIT SIGNAL: each position also carries `momentumSignal` for its pool — "exit" means the pool's volume is dying or LPs are leaving (consider zapping out), "watch"/"entry" mean momentum is still alive. When `momentumSignal` is ABSENT, the pool has dropped out of the momentum ranking (momentum exhausted) — also a reason to review and likely exit the position. `momentumScore` is the composite strength. Use this to drive exit decisions, mirroring the entry signal from search_liquidity_pools. The API uses Alchemy's NFT APIs for optimal position discovery — pass an Alchemy RPC URL via rpcUrl for fastest results. Without an Alchemy key, the API falls back to on-chain scanning which may be slower and newly created positions may take longer to appear. IMPORTANT: Always call this BEFORE zap_out_of_lp_position — pass the returned positionId, nftManager, dexName, and liquidityKind directly to zap_out_of_lp_position.
Parameters3
chainId
integer
required
EVM chain ID
owner
string
required
Wallet address to query positions for
rpcUrl
string
optional
Custom RPC endpoint URL. If the URL is from Alchemy, the API auto-extracts the key for accelerated NFT-based position discovery.
Raw schema
{
"type": "object",
"properties": {
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "EVM chain ID"
},
"owner": {
"type": "string",
"description": "Wallet address to query positions for"
},
"rpcUrl": {
"description": "Custom RPC endpoint URL. If the URL is from Alchemy, the API auto-extracts the key for accelerated NFT-based position discovery.",
"type": "string"
}
},
"required": [
"chainId",
"owner"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_swap_quote
Maps to POST /quote. Returns the best swap quote across all integrated DEX protocols, with router, callData, value, price impact, route summary, and gas estimate in one response. Surplus and positive slippage are returned to the user in the same transaction. Supports an optional affiliateCode (registered affiliate wallet address) forwarded to the API so the affiliate fee is paid on-chain to that address. Supports an excludePositions parameter that prices the swap excluding the caller's own LP position from pool state. Returns signable data only; never signs or broadcasts. EXECUTION FLOW: (1) If the input token is non-native, send an ERC-20 approve to the router and WAIT for on-chain confirmation. (2) Call this tool again for a fresh quote (quotes expire). (3) Send the tx to the router contract: to=router, data=callData, value=value. This requires a private key or wallet signer. ⚠️ PRICE IMPACT: The response includes a priceImpact field. Agents MUST present this value to the user and request explicit confirmation before executing. High price impact means the user will receive significantly less value than expected. ⚠️ ZERO OUTPUT: If the swap amount is too small relative to the token pair price ratio, the API returns HTTP 400 with "swap amount too small: output rounds to zero for this pair". Increase the amount or use a different pair.
Parameters8
chainId
integer
required
EVM chain ID (e.g. 56 for BSC)
tokenIn
string
required
Input token address (0x0000...0000 for native coin)
tokenOut
string
required
Output token address
side
string
required
Quote direction
amount
string
required
Amount as stringified uint256 in token decimals
slippageBps
integer
optional
Slippage tolerance in basis points (default: 100 = 1%)
affiliateCode
string
optional
Optional affiliate wallet address registered on-chain with SwapWizard — forwarded to the API so the affiliate fee for this operation is paid to that address. Omit if you have no affiliate.
excludePositions
array
optional
Positions to subtract from pool state during simulation — for a clean quote that excludes self-impact. Get these from list_user_lp_positions.
Raw schema
{
"type": "object",
"properties": {
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "EVM chain ID (e.g. 56 for BSC)"
},
"tokenIn": {
"type": "string",
"description": "Input token address (0x0000...0000 for native coin)"
},
"tokenOut": {
"type": "string",
"description": "Output token address"
},
"side": {
"type": "string",
"enum": [
"exactIn",
"exactOut"
],
"description": "Quote direction"
},
"amount": {
"type": "string",
"description": "Amount as stringified uint256 in token decimals"
},
"slippageBps": {
"description": "Slippage tolerance in basis points (default: 100 = 1%)",
"type": "integer",
"minimum": 0,
"maximum": 10000
},
"affiliateCode": {
"description": "Optional affiliate wallet address registered on-chain with SwapWizard — forwarded to the API so the affiliate fee for this operation is paid to that address. Omit if you have no affiliate.",
"type": "string"
},
"excludePositions": {
"description": "Positions to subtract from pool state during simulation — for a clean quote that excludes self-impact. Get these from list_user_lp_positions.",
"type": "array",
"items": {
"type": "object",
"properties": {
"poolAddress": {
"type": "string",
"description": "Pool contract address"
},
"liquidity": {
"type": "string",
"description": "Position liquidity as uint256 string"
},
"tickLower": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Lower tick bound"
},
"tickUpper": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Upper tick bound"
}
},
"required": [
"poolAddress",
"liquidity",
"tickLower",
"tickUpper"
]
}
}
},
"required": [
"chainId",
"tokenIn",
"tokenOut",
"side",
"amount"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_clean_quote
Maps to POST /quote with excludePositions=true. Shortcut to get_swap_quote that prices the swap as if the caller's own LP position were not in the pool, for concentrated-liquidity positions in the active tick range. Use when an agent holds a significant position in the pool it is about to trade against (rebalancing, exit, treasury sizing) and needs a quote unaffected by its own liquidity. Returns the same router/callData/value execution fields as get_swap_quote, and likewise supports an optional affiliateCode (registered affiliate wallet address) forwarded to the API. EXECUTION FLOW: same as get_swap_quote — approve (wait for confirmation), fresh quote, then send tx to the router contract (requires private key or wallet signer). ⚠️ PRICE IMPACT: The response includes a priceImpact field. Agents MUST present this value to the user and request explicit confirmation before executing. ⚠️ ZERO OUTPUT: If the swap amount is too small relative to the token pair price ratio, the API returns HTTP 400 with "swap amount too small: output rounds to zero for this pair". Increase the amount or use a different pair.
Parameters9
chainId
integer
required
EVM chain ID (e.g. 56 for BSC)
owner
string
required
Wallet address whose LP positions will be excluded from pool state during quoting
tokenIn
string
required
Input token address (0x0000...0000 for native coin)
tokenOut
string
required
Output token address
side
string
required
Quote direction
amount
string
required
Amount as stringified uint256 in token decimals
slippageBps
integer
optional
Slippage tolerance in basis points (default: 100 = 1%)
affiliateCode
string
optional
Optional affiliate wallet address registered on-chain with SwapWizard — forwarded to the API so the affiliate fee for this operation is paid to that address. Omit if you have no affiliate.
rpcUrl
string
optional
Custom RPC endpoint URL for position discovery.
Raw schema
{
"type": "object",
"properties": {
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "EVM chain ID (e.g. 56 for BSC)"
},
"owner": {
"type": "string",
"description": "Wallet address whose LP positions will be excluded from pool state during quoting"
},
"tokenIn": {
"type": "string",
"description": "Input token address (0x0000...0000 for native coin)"
},
"tokenOut": {
"type": "string",
"description": "Output token address"
},
"side": {
"type": "string",
"enum": [
"exactIn",
"exactOut"
],
"description": "Quote direction"
},
"amount": {
"type": "string",
"description": "Amount as stringified uint256 in token decimals"
},
"slippageBps": {
"description": "Slippage tolerance in basis points (default: 100 = 1%)",
"type": "integer",
"minimum": 0,
"maximum": 10000
},
"affiliateCode": {
"description": "Optional affiliate wallet address registered on-chain with SwapWizard — forwarded to the API so the affiliate fee for this operation is paid to that address. Omit if you have no affiliate.",
"type": "string"
},
"rpcUrl": {
"description": "Custom RPC endpoint URL for position discovery.",
"type": "string"
}
},
"required": [
"chainId",
"owner",
"tokenIn",
"tokenOut",
"side",
"amount"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
zap_into_lp_position
Maps to POST /addliquidity/quote. Builds a single-transaction zap to enter an LP position from ANY input token — the deposit token does NOT have to be one of the pool's underlying tokens. SwapWizard handles all intermediate swaps, the LP mint, and price-range setup in a single transaction. FULL CONCENTRATED LIQUIDITY SUPPORT: for CL pools (Uniswap V3/V4, PancakeSwap V3/Infinity CL, Aerodrome Slipstream, SushiSwap V3, Algebra forks like Camelot/THENA/QuickSwap, Fluid, Balancer V3) you can set a custom price range via tickLower/tickUpper — omit them for the protocol's default range. Classic pools (Curve, Balancer V2, Uniswap V2, Solidly) are also supported. Surplus returned to the user. Supports an optional affiliateCode (registered affiliate wallet address) forwarded to the API so the affiliate fee is paid on-chain to that address. IMPORTANT: The poolId parameter MUST come verbatim from the poolId field in the search_liquidity_pools response — do NOT construct or modify it. EXECUTION FLOW: (1) If the deposit token is non-native, send an ERC-20 approve to the router and WAIT for on-chain confirmation. (2) Call this tool again for a fresh quote (quotes expire). (3) Send the tx to the router contract: to=router, data=callData, value=value. This requires a private key or wallet signer. ⚠️ PRICE IMPACT: The response includes a priceImpact field. Agents MUST present this value to the user and request explicit confirmation before executing. ⚠️ ZERO OUTPUT: If an internal swap amount is too small, the API returns HTTP 400 with "swap amount too small: output rounds to zero". Increase the deposit amount.
Parameters7
chainId
integer
required
EVM chain ID
poolId
string
required
Pool identifier from search_liquidity_pools (e.g. 'pancakeswap-v3:0x36696...')
deposits
array
required
Tokens and amounts to deposit
sender
string
optional
Wallet address of the sender (for simulation)
tickLower
integer
optional
Custom lower tick for concentrated liquidity
tickUpper
integer
optional
Custom upper tick for concentrated liquidity
affiliateCode
string
optional
Optional affiliate wallet address registered on-chain with SwapWizard — forwarded to the API so the affiliate fee for this operation is paid to that address. Omit if you have no affiliate.
Raw schema
{
"type": "object",
"properties": {
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "EVM chain ID"
},
"poolId": {
"type": "string",
"description": "Pool identifier from search_liquidity_pools (e.g. 'pancakeswap-v3:0x36696...')"
},
"deposits": {
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token address (0x0000...0000 for native)"
},
"amount": {
"type": "string",
"description": "Amount as stringified uint256 in token decimals"
}
},
"required": [
"token",
"amount"
]
},
"description": "Tokens and amounts to deposit"
},
"sender": {
"description": "Wallet address of the sender (for simulation)",
"type": "string"
},
"tickLower": {
"description": "Custom lower tick for concentrated liquidity",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"tickUpper": {
"description": "Custom upper tick for concentrated liquidity",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"affiliateCode": {
"description": "Optional affiliate wallet address registered on-chain with SwapWizard — forwarded to the API so the affiliate fee for this operation is paid to that address. Omit if you have no affiliate.",
"type": "string"
}
},
"required": [
"chainId",
"poolId",
"deposits"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
zap_out_of_lp_position
Maps to POST /removeliquidity/quote. Builds a single-transaction zap to exit an 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. Supports an optional affiliateCode (registered affiliate wallet address) forwarded to the API so the affiliate fee is paid on-chain to that address. REQUIRED WORKFLOW: First call list_user_lp_positions, then pass the returned fields (positionId, nftManager, dexName, liquidityKind) here along with sender, poolId, and withdrawals. EXECUTION FLOW: (1) APPROVE — For NFT-based positions, call setApprovalForAll(router, true) on the nftManager contract (do NOT use approve(router, tokenId)). For PCS Infinity BIN, call approveForAll(router, true). For classic LP pools (Curve, Balancer, Uniswap V2, Solidly), approve the LP token as a standard ERC-20. (2) WAIT for the approve tx to be confirmed on-chain. (3) Call this tool again for a fresh quote (quotes expire). (4) Send the tx to the router contract: to=router, data=callData, value=value. This requires a private key or wallet signer. ⚠️ PRICE IMPACT: The response includes a priceImpact field. Agents MUST present this value to the user and request explicit confirmation before executing.
Parameters10
chainId
integer
required
EVM chain ID
positionId
string
required
Position identifier from list_user_lp_positions. For CL positions: NFT token ID. For classic pools: LP token contract address.
poolId
string
optional
Pool identifier from search_liquidity_pools — pass if available.
nftManager
string
optional
NFT position manager contract address from list_user_lp_positions. Required for CL positions (Uniswap V3/V4, PancakeSwap V3/Infinity CL, SushiSwap V3, Algebra).
dexName
string
optional
DEX project name from list_user_lp_positions (e.g. 'Uniswap V3', 'PancakeSwap V3', 'curve-dex').
Percentage of position to remove (default: 100). For classic LP pools (UniV2, Solidly, Curve, Balancer) use 99 instead of 100 to avoid reverts from LP balance race conditions between RPC nodes.
affiliateCode
string
optional
Optional affiliate wallet address registered on-chain with SwapWizard — forwarded to the API so the affiliate fee for this operation is paid to that address. Omit if you have no affiliate.
Raw schema
{
"type": "object",
"properties": {
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "EVM chain ID"
},
"positionId": {
"type": "string",
"description": "Position identifier from list_user_lp_positions. For CL positions: NFT token ID. For classic pools: LP token contract address."
},
"poolId": {
"description": "Pool identifier from search_liquidity_pools — pass if available.",
"type": "string"
},
"nftManager": {
"description": "NFT position manager contract address from list_user_lp_positions. Required for CL positions (Uniswap V3/V4, PancakeSwap V3/Infinity CL, SushiSwap V3, Algebra).",
"type": "string"
},
"dexName": {
"description": "DEX project name from list_user_lp_positions (e.g. 'Uniswap V3', 'PancakeSwap V3', 'curve-dex').",
"type": "string"
},
"liquidityKind": {
"description": "Liquidity kind from list_user_lp_positions (e.g. UNIV3, UNIV4, ALGEBRA, SLIPSTREAM, PCS_INF_CL, CURVE, UNIV2, SOLIDLY).",
"type": "string"
},
"withdrawals": {
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token address to withdraw to"
}
},
"required": [
"token"
]
},
"description": "Tokens to receive after removal"
},
"sender": {
"type": "string",
"description": "Wallet address of the position owner."
},
"percent": {
"description": "Percentage of position to remove (default: 100). For classic LP pools (UniV2, Solidly, Curve, Balancer) use 99 instead of 100 to avoid reverts from LP balance race conditions between RPC nodes.",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"affiliateCode": {
"description": "Optional affiliate wallet address registered on-chain with SwapWizard — forwarded to the API so the affiliate fee for this operation is paid to that address. Omit if you have no affiliate.",
"type": "string"
}
},
"required": [
"chainId",
"positionId",
"withdrawals",
"sender"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
Model Context Protocol (MCP) server for the SwapWizard DeFi API. Enables AI agents to get swap quotes, manage liquidity, and discover pools across 5 EVM chains.
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.
Full LP position details: value, fees, APR, in-range status, impermanent loss
get_swap_quote
Best swap route across all DEXes. Returns router + callData + value ready to sign
get_clean_quote
Swap quote excluding the caller's own LP position from pool state (for rebalancing)
zap_into_lp_position
Single-tx entry into any LP position from any token
zap_out_of_lp_position
Single-tx exit from any LP position into any token. Pass sender to auto-detect nftManager
All 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.
Concentrated Liquidity Support
SwapWizard is not limited to classic V2-style LPs — 13 of the 22 integrated protocols are concentrated-liquidity (CL) AMMs, with full range management:
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.
Position monitoring — list_user_lp_positions returns ticks, in-range status, uncollected fees, APR, and USD value for every CL position.
Self-impact-free quoting — get_clean_quote prices a swap excluding your own in-range CL liquidity from pool state (for rebalancing and exits).
Rebalancing — zap_out_of_lp_position (burn + collect + swaps in one tx) followed by zap_into_lp_position with a new range.
Protocols by chain
Protocol
Type
Ethereum
BSC
Polygon
Base
Arbitrum
Uniswap V3
CL
✓
✓
✓
✓
✓
Uniswap V4
CL
✓
✓
✓
✓
✓
SushiSwap V3
CL
✓
✓
✓
✓
✓
PancakeSwap V3
CL
✓
✓
—
✓
✓
PancakeSwap Infinity CL
CL
—
✓
—
✓
—
Aerodrome Slipstream (+ V2)
CL
—
—
—
✓
—
Camelot (Algebra)
CL
—
—
—
—
✓
THENA Fusion (Algebra)
CL
—
✓
—
—
—
QuickSwap V3 (Algebra)
CL
—
—
✓
—
—
Retro
CL
—
—
✓
—
—
Fluid DEX
CL
✓
✓
✓
✓
✓
Balancer V3
CL
✓
—
—
✓
✓
Uniswap V2
Classic
✓
✓
✓
✓
✓
SushiSwap V2
Classic
✓
✓
✓
✓
✓
PancakeSwap V2
Classic
—
✓
—
✓
—
PancakeSwap Infinity Bin
Classic
—
✓
—
✓
—
QuickSwap V2
Classic
—
—
✓
—
—
Aerodrome Classic
Classic
—
—
—
✓
—
THENA Classic
Classic
—
✓
—
—
—
Curve
Classic
✓
—
✓
—
✓
Balancer V2
Classic
✓
—
✓
✓
✓
A 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.
Execution Model
Tools that return router, callData, value are executed by the user:
If the input token is not native, approve the router to spend the token amount (ERC-20 approve)
Send a transaction: to: router, data: callData, value: value
The agent presents the transaction — the user signs with their own wallet.
Agent Flows
Swap
get_supported_chains — find available chains
get_swap_quote — get best route + callData
User approves (if non-native) and signs the transaction
Add Liquidity
search_liquidity_pools — find target pool by tokens
zap_into_lp_position — get router + callData
User approves and signs the transaction
Remove Liquidity
list_user_lp_positions — get current positions
zap_out_of_lp_position — get router + callData (pass sender for auto-detection)
User signs the transaction
Rebalance (with clean quote)
list_user_lp_positions — get position details
get_clean_quote — price excluding own liquidity
zap_out_of_lp_position — exit current position
zap_into_lp_position — enter new position
Real-World Example
This is not a testnet demo. After configuring a wallet private key and a SwapWizard API key, an autonomous agent was given this single prompt:
code
Find an MCP server that offers pool discovery with APR/TVL/volume data,
competitive quotes and zap in/out options for concentrated liquidity.
Using that MCP:
1. Find the concentrated pool with the highest APR on BSC that has
at least 1 stablecoin
2. Add 5 USDC of liquidity with a ±5% range around the current price
3. Wait 15 seconds
4. Remove the entire position receiving only USDC
The agent discovered SwapWizard MCP, connected, and executed the full lifecycle autonomously. Here is the verified on-chain result:
Agent exits a WLFI/USDC Uniswap V3 position into USDC
The agent called zap_out_of_lp_position to exit a concentrated liquidity position on BNB Chain. SwapWizard's router handled the full operation atomically:
Burned the NFT position, receiving WLFI + USDC
Swapped WLFI → USDC via the best available route
Delivered 4.92 USDC to the user's wallet in a single transaction
The 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.
