paladin-swap-mcp

Открытый клиент и спецификация API для PaladinFi Swap — конкурентоспособный мульти-агрегаторный маршрутизатор свопов для ИИ-агентов в сети Base. Этот репозиторий содержит спецификацию публичного REST и MCP API, рабочие примеры кода и легковесные клиентские обертки. Размещенный бэкенд по адресу swap.paladinfi.com является проприетарным.

Область маршрутизации. PaladinFi Swap параллельно опрашивает ограниченный набор интегрированных вышестоящих агрегаторов (в настоящее время 0x и Velora; в планах 1inch и Odos) и возвращает тот вариант, который обеспечивает большую сумму покупки после вычета комиссии. Мы не утверждаем, что какой-либо возвращенный маршрут является лучшим из доступных, самым дешевым или оптимальным на более широком рынке DeFi. Такие фразы, как "лучшее исполнение" (best execution), являются терминами с зарезервированным значением в законодательстве США о ценных бумагах и намеренно здесь не используются.

Что такое PaladinFi Swap?

Маршрутизатор свопов, созданный для ИИ-агентов, которым необходимо выполнять ончейн-свопы. Ваш агент вызывает один инструмент; сервис возвращает готовые к исполнению calldata, которые ваш кошелек подписывает и отправляет:

• Адрес маршрутизатора, на который отправляется транзакция

• Calldata со всей предварительно настроенной маршрутизацией

• Минимальная сумма покупки (защита от проскальзывания, принудительно применяемая ончейн)

• Партнерская комиссия уже включена — никакой отдельной бухгалтерии с вашей стороны

Агентам не нужно писать код для интеграции агрегаторов, обработки проскальзывания и логики комиссий. Один вызов, готовые байты.

Сервис является некастодиальным: PaladinFi никогда не хранит, не подписывает и не перемещает средства пользователей. Каждая транзакция подписывается и отправляется собственным кошельком пользователя (или его агентом, действующим от его имени).

Установка (MCP)

Для Claude Code или любого MCP-совместимого клиента, поддерживающего транспорт Streamable-HTTP:

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

Перезапустите клиент. Станут доступны три инструмента:

• swap_quote(sellToken, buyToken, sellAmount, taker, chainId?, slippageBps?) — котировка "лучший из N" между 0x + Velora; возвращает готовые к исполнению calldata.

• trust_check_preview(address, chainId?) — предварительный просмотр оценки доверия к токен-контракту на основе образца. Бесплатно / не оплачивается; возвращает _real: false, чтобы четко обозначить это как предварительный просмотр. Реальные оценки доступны через @paladinfi/eliza-plugin-trust или @paladinfi/agentkit-actions (оплачивается через x402, $0.001/вызов).

• swap_health() — проверка работоспособности + счетчики по источникам для сервиса маршрутизации.

Смотрите mcp-tools.json для получения полных схем инструментов.

Установка (REST)

MCP не требуется — обращайтесь к эндпоинту напрямую:

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"
  }'

Полная спецификация REST в openapi.yaml.

Эндпоинты

Формат ответа (сокращенно)

{
  "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 — это вышестоящий агрегатор, который выиграл эту котировку ("0x" или "velora"). Отправьте транзакцию как to=router, data=calldata, value=0 (для ERC20→ERC20) от имени taker.

Примеры

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

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

Комиссии

Фиксированные 10 базисных пунктов (0.1%) взимаются с покупаемого токена. Комиссия рассчитывается от фактической суммы исполнения, а не от оценочной котировки, поэтому вы никогда не заплатите больше ожидаемого, даже если пул изменится между котировкой и исполнением.

Комиссии направляются напрямую в казну PaladinFi — с вашей стороны не требуется никаких действий по подтверждению ончейн. Адрес получателя комиссии опубликован в /health, поэтому его можно проверить ончейн. Сервис остается бесплатным для запросов, без дополнительных сборов за вызов или спредов.

Поддерживаемые активы

• Сеть: Base (8453). Ethereum mainnet, Arbitrum, Optimism, BNB находятся в дорожной карте.

• Токены: Любой ERC20, поддерживаемый либо 0x, либо Velora в сети Base. Покрытие представляет собой объединение обоих агрегаторов — канонические пары (USDC, WETH, cbBTC, USDT, DAI, AERO) маршрутизируются через оба; токены с длинным хвостом часто маршрутизируются только через один из двух.

Дорожная карта

• [x] Маршрутизация 0x Settler в Base

• [x] Маршрутизация "лучший из N" между 0x и Velora в Base (v0.11.66+, 2026-05-04)

• [x] Транспорт MCP Streamable-HTTP

• [x] Инструмент MCP trust_check_preview (v0.11.65)

• [ ] 1inch + Odos в качестве дополнительных источников маршрутизации — запланировано

• [ ] Ethereum mainnet, Arbitrum, BNB, Optimism — запланировано

• [ ] Поток, нативный для Permit2 (пропуск транзакции approve) — запланировано

Статус

Продакшн. Эндпоинт работает, отслеживается и проверен сквозным тестированием с помощью ончейн-транзакций в Base. См. /health для получения текущей конфигурации комиссии, версии и счетчиков по источникам.

Что находится в этом репозитории

Не входит в этот репозиторий: размещенный бэкенд (проприетарный). Этот репозиторий является публичной клиентской поверхностью — инструкции по установке, схемы и примеры кода интеграции.

Контакты

• Email: dev@paladinfi.com

• Маркетинг: paladinfi.com

• API: swap.paladinfi.com/health

• Лендинг: paladinfi.com/swap/

Юридическая информация

Управляется компанией Malcontent Games LLC, ведущей деятельность как PaladinFi, общество с ограниченной ответственностью штата Мичиган. Сервис направляет котировки через сторонние агрегаторы (в настоящее время 0x и Velora). Вы сохраняете кастодиальное владение — ваш агент подписывает каждую транзакцию. PaladinFi никогда не хранит средства пользователей.

Использование размещенного Сервиса регулируется Условиями предоставления услуг PaladinFi и Политикой конфиденциальности.

Лицензия

Содержимое этого репозитория выпущено под лицензией MIT. Размещенный бэкенд является проприетарным и не подпадает под действие этой лицензии.