paladin-swap-mcp

PaladinFi Swap 的开放客户端与 API 规范 — 专为 Base 上 AI 代理打造的竞争性多聚合器交换路由。本仓库包含公共 REST 和 MCP API 规范、可运行的代码示例以及轻量级客户端封装。托管后端 swap.paladinfi.com 为专有服务。

路由范围。 PaladinFi Swap 并行查询一组有限的集成上游聚合器（目前为 0x 和 Velora；计划集成 1inch 和 Odos），并返回扣除费用后买入金额最高的结果。我们不保证任何返回的路由是整个 DeFi 市场中可用、成本最低或最优的。诸如“最佳执行”之类的短语在美国证券法中属于保留含义术语，此处特意不予使用。

什么是 PaladinFi Swap？

这是一个为需要执行链上交换的 AI 代理 构建的交换路由。您的代理只需调用一个工具；服务即返回可直接执行的 calldata，由您的钱包签名并提交：

• 路由地址：用于发送交易

• Calldata：包含所有预设好的路由信息

• 最小买入金额：在链上强制执行滑点保护

• 已注入联盟费用：无需您进行单独的会计处理

代理无需编写聚合器胶水代码、处理滑点或逻辑费用。一次调用，即可获得就绪的字节码。

该服务是非托管的：PaladinFi 从不持有、签署或转移用户资金。每笔交易均由用户自己的钱包（或其代理）签名并提交。

安装 (MCP)

对于 Claude Code 或任何支持 Streamable-HTTP 传输的 MCP 兼容客户端：

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

重启您的客户端。三个工具将变为可用：

• swap_quote(sellToken, buyToken, sellAmount, taker, chainId?, slippageBps?) — 在 0x + Velora 之间进行 N 选优报价；返回可直接执行的 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"）。使用 taker 提交交易，参数为 to=router, data=calldata, value=0（针对 ERC20→ERC20）。

示例

• examples/python/quote_and_swap.py — 使用 web3.py 的 Python 示例

• examples/typescript/quote_and_swap.ts — 使用 viem 的 TypeScript 示例

费用

在买入代币上收取固定的 10 个基点 (0.1%) 费用。费用根据实际成交金额计算，而非报价估算值，因此即使在报价和成交之间资金池发生变动，您也不会支付超出预期的费用。

费用直接路由至 PaladinFi 金库 — 您无需进行链上接收步骤。费用接收地址发布在 /health 中，因此可在链上审计。该服务查询免费，无单次调用费用，也不收取额外点差。

支持的资产

• 链： Base (8453)。以太坊主网、Arbitrum、Optimism、BNB 均在路线图中。

• 代币： 0x 或 Velora 在 Base 上支持的任何 ERC20 代币。覆盖范围是两个聚合器的并集 — 规范交易对（USDC, WETH, cbBTC, USDT, DAI, AERO）在两者上均可路由；长尾代币通常仅在其中一个上路由。

路线图

• [x] Base 上的 0x Settler 路由

• [x] Base 上 0x 和 Velora 之间的 N 选优路由 (v0.11.66+, 2026-05-04)

• [x] MCP Streamable-HTTP 传输

• [x] trust_check_preview MCP 工具 (v0.11.65)

• [ ] 1inch + Odos 作为额外的路由来源 — 计划中

• [ ] 以太坊主网、Arbitrum、BNB、Optimism — 计划中

• [ ] Permit2 原生流程（跳过授权交易） — 计划中

状态

生产环境。该端点已上线、受监控，并已通过 Base 上的链上测试交易进行了端到端验证。请参阅 /health 获取当前的费用配置、版本和各来源计数器。

本仓库包含内容

本仓库不包含： 托管后端（专有）。本仓库是公共客户端界面 — 包含安装说明、架构和集成代码示例。

联系方式

• 电子邮件: dev@paladinfi.com

• 市场: paladinfi.com

• API: swap.paladinfi.com/health

• 落地页: paladinfi.com/swap/

法律声明

由 Malcontent Games LLC 运营，以 PaladinFi 名义开展业务，是一家密歇根州有限责任公司。本服务通过第三方聚合器（目前为 0x 和 Velora）路由报价。您保留托管权 — 您的代理签署每一笔交易。PaladinFi 从不持有用户资金。

使用托管服务受 PaladinFi 服务条款 和 隐私政策 约束。

许可

本仓库内容根据 MIT 许可证 发布。托管后端为专有，不在此范围内。