paladin-swap-mcp

Cliente abierto y especificación de API para PaladinFi Swap — un router de intercambio multi-agregador competitivo para agentes de IA en Base. Este repositorio contiene la especificación pública de la API REST y MCP, ejemplos de código funcionales y envoltorios de cliente ligero. El backend alojado en swap.paladinfi.com es propietario.

Alcance del enrutamiento. PaladinFi Swap consulta un conjunto limitado de agregadores ascendentes integrados (actualmente 0x y Velora; 1inch y Odos están planificados) en paralelo y devuelve el que ofrece una mayor cantidad de compra después de comisiones. No representamos ninguna ruta devuelta como la mejor disponible, de menor costo u óptima en el mercado DeFi más amplio. Frases como "mejor ejecución" son términos con significado reservado en la ley de valores de EE. UU. y deliberadamente no se utilizan aquí.

¿Qué es PaladinFi Swap?

Un router de intercambio creado para agentes de IA que necesitan ejecutar intercambios en cadena. Tu agente llama a una única herramienta; el servicio devuelve calldata lista para ejecutar que tu billetera firma y envía:

• Dirección del router a la que enviar la transacción

• Calldata con todo el enrutamiento preconfigurado

• Cantidad mínima de compra (protección contra deslizamiento aplicada en cadena)

• Tarifa de afiliado ya inyectada — sin contabilidad separada por tu parte

Los agentes se saltan la escritura de pegamento de agregadores, el manejo de deslizamiento y la lógica de tarifas. Una llamada, bytes listos.

El servicio es sin custodia: PaladinFi nunca retiene, firma ni mueve fondos de los usuarios. Cada transacción es firmada y enviada por la propia billetera del usuario (o su agente actuando en su nombre).

Instalación (MCP)

Para Claude Code o cualquier cliente compatible con MCP que admita transporte Streamable-HTTP:

claude mcp add --transport http --scope user paladin-swap https://swap.paladinfi.com/mcp

Reinicia tu cliente. Tres herramientas estarán disponibles:

• swap_quote(sellToken, buyToken, sellAmount, taker, chainId?, slippageBps?) — cotización del mejor de N entre 0x + Velora; devuelve calldata lista para ejecutar.

• trust_check_preview(address, chainId?) — vista previa de muestra de la evaluación de confianza del contrato de token. Gratuita / no pagada; devuelve _real: false para marcar claramente como vista previa. Evaluaciones reales disponibles a través de @paladinfi/eliza-plugin-trust o @paladinfi/agentkit-actions (pagadas mediante x402, $0.001/llamada).

• swap_health() — estado de actividad + contadores por fuente para el servicio de enrutamiento.

Consulta mcp-tools.json para ver los esquemas completos de las herramientas.

Instalación (REST)

No se necesita MCP — accede al endpoint directamente:

curl -sS https://swap.paladinfi.com/v1/quote \
  -H 'content-type: application/json' \
  -d '{
    "chainId": 8453,
    "sellToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "buyToken":  "0x4200000000000000000000000000000000000006",
    "sellAmount": "5000000",
    "taker": "0xYOUR_AGENT_WALLET"
  }'

Especificación REST completa en openapi.yaml.

Endpoints

Forma de respuesta (abreviada)

{
  "source": "velora",
  "chainId": 8453,
  "router": "0x6a000f20005980200259b80c5102003040001068",
  "calldata": "0x...",
  "buyAmount": "2160000000000000",
  "minBuyAmount": "2138000000000000",
  "sellAmount": "5000000",
  "gas": "318707",
  "ourFeeBps": 10,
  "ourFeeRecipient": "0xeA8C33d018760D034384e92D1B2a7cf0338834b4",
  "estimatedOurFeeAmount": "2160000000000",
  "estimatedOurFeeToken": "0x4200000000000000000000000000000000000006"
}

source es el agregador ascendente que ganó esta cotización ("0x" o "velora"). Envía la transacción como to=router, data=calldata, value=0 (para ERC20→ERC20) desde taker.

Ejemplos

• examples/python/quote_and_swap.py — Python con web3.py

• examples/typescript/quote_and_swap.ts — TypeScript con viem

Tarifas

Se aplica una tarifa plana de 10 puntos básicos (0.1%) sobre el token de compra. La tarifa se calcula sobre la cantidad de llenado real, no sobre la estimación cotizada, por lo que nunca pagas más de lo esperado incluso si el pool se mueve entre la cotización y el llenado.

Las tarifas se dirigen directamente a la tesorería de PaladinFi — sin paso de recibo en cadena por tu parte. La dirección del destinatario de la tarifa se publica en /health para que sea auditable en cadena. El servicio sigue siendo gratuito para consultar, sin cargos por llamada ni margen adicional.

Activos soportados

• Cadena: Base (8453). Ethereum mainnet, Arbitrum, Optimism, BNB están en la hoja de ruta.

• Tokens: Cualquier ERC20 soportado por 0x o Velora en Base. La cobertura es la unión de ambos agregadores — los pares canónicos (USDC, WETH, cbBTC, USDT, DAI, AERO) son enrutables en ambos; los tokens de cola larga a menudo se enrutan solo en uno de los dos.

Hoja de ruta

• [x] Enrutamiento 0x Settler en Base

• [x] Enrutamiento del mejor de N entre 0x y Velora en Base (v0.11.66+, 2026-05-04)

• [x] Transporte MCP Streamable-HTTP

• [x] Herramienta MCP trust_check_preview (v0.11.65)

• [ ] 1inch + Odos como fuentes de enrutamiento adicionales — planificado

• [ ] Ethereum mainnet, Arbitrum, BNB, Optimism — planificado

• [ ] Flujo nativo Permit2 (saltar la transacción de aprobación) — planificado

Estado

Producción. El endpoint está activo, monitoreado y verificado de extremo a extremo con transacciones de prueba en cadena en Base. Consulta /health para ver la configuración actual de tarifas, la versión y los contadores por fuente.

Qué hay en este repositorio

No está en este repositorio: el backend alojado (propietario). Este repositorio es la superficie del cliente público — instrucciones de instalación, esquemas y ejemplos de código de integración.

Contacto

• Correo electrónico: dev@paladinfi.com

• Marketing: paladinfi.com

• API: swap.paladinfi.com/health

• Landing: paladinfi.com/swap/

Legal

Operado por Malcontent Games LLC, operando como PaladinFi, una compañía de responsabilidad limitada de Michigan. El Servicio enruta cotizaciones a través de agregadores de terceros (actualmente 0x y Velora). Tú retienes la custodia — tu agente firma cada transacción. PaladinFi nunca retiene fondos de los usuarios.

El uso del Servicio alojado está sujeto a los Términos de Servicio de PaladinFi y a la Política de Privacidad.

Licencia

El contenido de este repositorio se publica bajo la Licencia MIT. El backend alojado es propietario y no está cubierto.