SwapWizard MCP

Servidor MCP de SwapWizard

Servidor de Model Context Protocol (MCP) para la API DeFi de SwapWizard. Permite a los agentes de IA obtener cotizaciones de swaps, gestionar liquidez y descubrir pools en 5 cadenas EVM.

Sin custodia: cada herramienta devuelve router, callData y value — el agente presenta la transacción, el usuario firma con su propia wallet. SwapWizard nunca retiene claves.

Inicio Rápido

1. Obtén una Clave de API

Ve a swapwizard.xyz/integrators, conecta tu wallet y firma un mensaje (sin costo de gas).

2. Conéctate vía MCP

Remoto (sin instalación)

URL: https://mcp.swapwizard.xyz/mcp
Transport: streamable-http
Header: X-API-Key: your-api-key

Local — Claude Desktop

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "swapwizard": {
      "command": "npx",
      "args": ["-y", "@swapwizard/mcp-server"],
      "env": {
        "SWAPWIZARD_API_KEY": "your-api-key"
      }
    }
  }
}

Local — Cursor

Añade a .cursor/mcp.json:

{
  "mcpServers": {
    "swapwizard": {
      "command": "npx",
      "args": ["-y", "@swapwizard/mcp-server"],
      "env": {
        "SWAPWIZARD_API_KEY": "your-api-key"
      }
    }
  }
}

Local — Claude Code

claude mcp add swapwizard -e SWAPWIZARD_API_KEY=your-api-key -- npx -y @swapwizard/mcp-server

Herramientas Disponibles

Herramienta	Descripción
get_supported_chains	Lista las cadenas EVM compatibles con IDs, tokens de gas, lista de DEX y configuración de posición
get_supported_dexes	Fuentes AMM/DEX por las que SwapWizard enruta por cadena
check_api_health	Verificación de disponibilidad de la API
search_liquidity_pools	Descubre pools por cadena, tokens, tipo o tendencias de GeckoTerminal (trending: true + timeframe opcional: 5m/1h/6h/24h, por defecto 5m). Devuelve poolId, símbolo, nivel de comisión, protocolo, APY, TVL, volumen de 24h
list_user_lp_positions	Detalles completos de la posición LP: valor, comisiones, APR, estado dentro del rango, pérdida impermanente
get_swap_quote	Mejor ruta de swap en todos los DEX. Devuelve router + callData + value listos para firmar
get_clean_quote	Cotización de swap excluyendo la propia posición LP del llamante del estado del pool (para rebalanceo)
zap_into_lp_position	Entrada en una sola transacción a cualquier posición LP desde cualquier token
zap_out_of_lp_position	Salida en una sola transacción de cualquier posición LP a cualquier token. Pasa sender para auto-detectar nftManager

Todas las herramientas de cotización (get_swap_quote, get_clean_quote, zap_into_lp_position, zap_out_of_lp_position) aceptan un affiliateCode opcional — una dirección de wallet de afiliado registrada en cadena con SwapWizard, reenviada a la API para que la comisión de afiliado se pague a esa dirección.

Soporte de Liquidez Concentrada

SwapWizard no se limita a LPs clásicos estilo V2 — 13 de los 22 protocolos integrados son AMM de liquidez concentrada (CL), con gestión completa de rango:

• Rangos de precio personalizados — zap_into_lp_position acepta tickLower / tickUpper para acuñar una posición CL en cualquier rango (omítelos para el valor por defecto del protocolo). La división de tokens, los swaps intermedios, la acuñación y la configuración del rango ocurren en una sola transacción.
• Monitoreo de posiciones — list_user_lp_positions devuelve ticks, estado dentro del rango, comisiones no cobradas, APR y valor en USD para cada posición CL.
• Cotización sin auto-impacto — get_clean_quote cotiza un swap excluyendo tu propia liquidez CL dentro del rango del estado del pool (para rebalanceo y salidas).
• Rebalanceo — zap_out_of_lp_position (quemado + cobro + swaps en una sola tx) seguido de zap_into_lp_position con un nuevo rango.

Protocolos por cadena

Protocolo	Tipo	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	Clásico	✓	✓	✓	✓	✓
SushiSwap V2	Clásico	✓	✓	✓	✓	✓
PancakeSwap V2	Clásico	—	✓	—	✓	—
PancakeSwap Infinity Bin	Clásico	—	✓	—	✓	—
QuickSwap V2	Clásico	—	—	✓	—	—
Aerodrome Classic	Clásico	—	—	—	✓	—
THENA Classic	Clásico	—	✓	—	—	—
Curve	Clásico	✓	—	✓	—	✓
Balancer V2	Clásico	✓	—	✓	✓	✓

Un Split Router integrado además divide las órdenes entre múltiples DEX en las 5 cadenas. El registro en vivo está disponible vía get_supported_dexes / get_supported_chains.

Modelo de Ejecución

Las herramientas que devuelven router, callData, value son ejecutadas por el usuario:

1. Si el token de entrada no es nativo, aprueba al router para gastar la cantidad del token (aprobación ERC-20)
2. Envía una transacción: to: router, data: callData, value: value

El agente presenta la transacción — el usuario firma con su propia wallet.

Flujos de Agente

Swap

1. get_supported_chains — encuentra cadenas disponibles
2. get_swap_quote — obtén la mejor ruta + callData
3. El usuario aprueba (si no es nativo) y firma la transacción

Añadir Liquidez

1. search_liquidity_pools — encuentra el pool objetivo por tokens
2. zap_into_lp_position — obtén router + callData
3. El usuario aprueba y firma la transacción

Retirar Liquidez

1. list_user_lp_positions — obtén posiciones actuales
2. zap_out_of_lp_position — obtén router + callData (pasa sender para auto-detección)
3. El usuario firma la transacción

Rebalancear (con cotización limpia)

1. list_user_lp_positions — obtén detalles de la posición
2. get_clean_quote — cotiza excluyendo la propia liquidez
3. zap_out_of_lp_position — sal de la posición actual
4. zap_into_lp_position — entra en la nueva posición

Ejemplo del Mundo Real

Esto no es una demo de testnet. Después de configurar una clave privada de wallet y una clave de API de SwapWizard, a un agente autónomo se le dio este único prompt:

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

El agente descubrió SwapWizard MCP, se conectó y ejecutó el ciclo de vida completo de forma autónoma. Aquí está el resultado verificado en cadena:

El agente sale de una posición WLFI/USDC de Uniswap V3 hacia USDC

Prueba en cadena: 0xede1afbc...c16f16c — Bloque 101133314, 29 de mayo de 2026

El agente llamó a zap_out_of_lp_position para salir de una posición de liquidez concentrada en BNB Chain. El router de SwapWizard manejó la operación completa de forma atómica:

1. Quemó la posición NFT, recibiendo WLFI + USDC
2. Intercambió WLFI → USDC vía la mejor ruta disponible
3. Entregó 4.92 USDC a la wallet del usuario en una sola transacción

Tool:     zap_out_of_lp_position
Chain:    BNB Chain (56)
Pool:     WLFI / USDC — Uniswap V3
Router:   0xc664F80dff9655766398E86A6B95AF76660FA66d
Method:   removeLiquidityMulti
Gas used: 411,002
Result:   4.92 USDC received

El agente solicitó la cotización, el usuario aprobó el NFT y firmó — sin ajuste manual de parámetros, sin interacción con contratos, sin cálculo de deslizamiento. El servidor MCP auto-detectó nftManager, dexName y liquidityKind desde la dirección sender.

Demos del Bot PoC

Videos completos de ejecución:

English	Español

Cadenas Compatibles

Ethereum (1), Arbitrum (42161), Base (8453), Polygon (137), BNB Chain (56)

Variables de Entorno

Variable	Requerida	Por defecto	Descripción
SWAPWIZARD_API_KEY	Sí	—	Clave de API de swapwizard.xyz/integrators
SWAPWIZARD_API_URL	No	https://api.swapwizard.xyz	URL base de la API

Integración de Afiliados

Gana comisiones integrando SwapWizard en tu sitio:

<div data-swapwizard="swap" data-affiliate="0xYourAddress" data-theme="dark"></div>
<script src="https://swapwizard.xyz/widget.js" async></script>

Modos de widget: swap, pools o full. Configúralo en swapwizard.xyz/developers.

Límites de Tasa

60 solicitudes por minuto por clave de API.

Desarrollo

npm install
npm run dev          # run with tsx (hot reload)
npm run build        # compile TypeScript
npm test             # run tests

Consulta CONTRIBUTING.md para las pautas.

Enlaces

• Sitio web
• Documentación de la API
• Documentación para Agentes de IA
• npm
• Configurador de Widgets
• Registro de cambios

Licencia

MIT