paladin-swap

paladin-swap-mcp

面向 PaladinFi Swap 的开放客户端和 API 规范——一个为 Base 上的 AI Agent 提供服务的竞争性多聚合器兑换路由器。此仓库包含公开的 REST 和 MCP API 规范、可运行的代码示例，以及轻量级客户端封装。托管后端 swap.paladinfi.com 为专有服务。

路由范围。 PaladinFi Swap 会并行查询已集成的上游聚合器（目前为 0x 和 Velora），并返回扣除费用后买入数量更高的路由。我们不声称返回的任何路由在更广泛的 DeFi 市场中可用性最佳、成本最低或最优。“最佳执行”等词语在美国证券法中具有特定含义，因此我们特意不在此使用。

---

什么是 PaladinFi Swap？

一个专为需要执行链上兑换的 AI Agent 打造的兑换路由器。你的 Agent 调用一个工具；服务会返回可直接执行的 calldata，由你的钱包签名并提交：

• 要将交易发送到的 路由器地址
• 已预先完成所有路由配置的 Calldata
• 最低买入数量（链上强制执行滑点保护）
• 已注入的 联盟费用——你无需单独核算

Agent 无需编写聚合器衔接代码，也无需处理滑点和费用逻辑。一次调用，即可获得可直接使用的字节数据。

本服务 非托管：PaladinFi 绝不会持有、签署或转移用户资金。每笔交易都由用户自己的钱包（或代表用户行事的 Agent）签名并提交。

安装（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 之间选择竞争性路由（返回扣费后买入数量较高的路由）；返回可直接执行的 calldata。
• trust_check_preview(address, chainId?) — 信任门控的示例数据预览。返回 _real: false，每个因素的 real: false，且建议结果带有 sample- 前缀（例如 sample-allow）。请勿使用预览判定来限制真实兑换、签名或任何生产环境中的 Agent 决策。如需在生产环境中进行信任评估，请向 /v1/trust-check 发送 POST 请求（付费，每次调用通过 x402 支付 $0.001 USDC），或使用 npm 插件 @paladinfi/eliza-plugin-trust / @paladinfi/agentkit-actions。
• swap_health() — 存活状态、费用配置、各来源计数器、小数位缓存状态、最近一次 Velora 启动金丝雀判定、选择器强制执行状态。

完整工具架构请参阅 mcp-tools.json。

MCP 标准合规性

要求	状态
工具 title + annotations（readOnlyHint、openWorldHint、idempotentHint、destructiveHint）	✓ 自 v0.11.74 起支持；可通过 MCP tools/list 方法验证
工具名称 ≤64 个字符	✓ 最长的是 trust_check_preview（19 个字符）
Streamable HTTP 传输	✓ 地址：https://swap.paladinfi.com/mcp
公开的 OpenAPI 3.0 架构	✓ 地址：/openapi.yaml
已记录的速率限制	✓ 见 paladinfi.com/swap（/v1/quote 为 5 r/s + 突发 30；/mcp 为 10 r/s + 突发 30；每个 IP 最多 5 个并发连接）
x402 付费工具挑战	✓ 适用于 /v1/trust-check 付费端点。MCP trust_check_preview 工具仅提供样例固定数据输出，并带有明确的误用警示（_real: false、_HUMAN_DO_NOT_USE_AS_REAL_VERDICT、sample- 建议前缀）——它的设计用途仅为预览，绝非真实判定
工具描述精确且范围明确	✓ 具体架构见 mcp-tools.json
浏览器来源的客户端（CORS）	✓ 自 v0.11.75 起在 /v1/quote 支持；允许列表仅包含 paladinfi.com 和 www.paladinfi.com——其他来源会在预检阶段被阻止
免费的真实数据接入端点	✓ 自 v0.11.77 起支持——POST /v1/trust-check/ofac 仅执行 OFAC SDN 钱包筛查环节（匿名，速率限制为 1 r/s + 突发 3，每日刷新财政部 XML）。响应中包含 _paid_endpoint_info 升级提示，可引导至 /v1/trust-check 上的完整多来源组合。范围仅限钱包 OFAC 筛查（计划在未来版本中支持代币合约制裁名单）。
MCP Registry 上架	✓ 此软件包已上架为 io.github.paladinfi/paladin-swap。符合 §4.A 的纯信任检查变体（无支付接口、无 calldata、无交易执行）单独发布为 com.paladinfi/trust-check-mcp——Streamable HTTP 地址为 trust.paladinfi.com/mcp。如果与支付接口相邻会成为部署障碍，请使用信任检查变体。

根据 MCP ToolAnnotations：

• swap_quote — 标题为 "Get Swap Quote"；readOnlyHint: true（返回 calldata，不会更改服务端状态），openWorldHint: true（会调用上游聚合器 0x AllowanceHolder + Base 上的 Velora Augustus v6.2）
• trust_check_preview — 标题为 "Token Trust Check (Preview)"；readOnlyHint: true、idempotentHint: true（每个地址对应确定性的样例固定数据）、openWorldHint: true（付费模式下的上游因子来源会跨越进程边界；针对形状偏移设有防御性契约违规处理程序）
• swap_health — 标题为 "Swap Service Health"；readOnlyHint: true、openWorldHint: false（仅检查我们自己的服务状态）

Agent 使用演练

MCP 感知型 Agent（例如 Claude Code）处理兑换意图时的典型调用链。具体的工具调用格式因客户端而异；关键在于，兑换路由器会返回可直接执行的 calldata，因此 Agent 无需自行编写路由逻辑。

用户： “在 Base 上将 100 USDC 兑换为 WETH。”

1. 可选的交易前信任检查（免费，仅使用样例数据）。在编写兑换交易前，Agent 可以调用 trust_check_preview，查看买入代币合约的风险状况。

// Tool call
{
  "tool": "trust_check_preview",
  "arguments": {
    "address": "0x4200000000000000000000000000000000000006",
    "chainId": 8453
  }
}

// Response (truncated)
{
  "_real": false,
  "_HUMAN_DO_NOT_USE_AS_REAL_VERDICT": "Preview-only fixture. See README.",
  "trust": {
    "recommendation": "sample-allow",
    "_preview": true,
    "factors": [
      { "real": false, "source": "ofac",      "signal": "clear" },
      { "real": false, "source": "goplus",    "signal": "clear" },
      { "real": false, "source": "etherscan", "signal": "verified-contract" }
    ]
  }
}

此预览仅使用样例数据——Agent 必须检查 _real === true 后才能使用判定结果。若要在生产环境中进行准入控制，请调用 /v1/trust-check（付费，通过 x402 每次调用需支付 $0.001 USDC），或使用 npm 插件 @paladinfi/eliza-plugin-trust / @paladinfi/agentkit-actions。

2. 获取包含 calldata 的竞争性报价。 Agent 调用 swap_quote，获取路由和可直接执行的交易。

// Tool call
{
  "tool": "swap_quote",
  "arguments": {
    "sellToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "buyToken":  "0x4200000000000000000000000000000000000006",
    "sellAmount": "100000000",
    "taker":      "0xUserAgentWallet",
    "chainId":    8453,
    "slippageBps": 50
  }
}

// Response (illustrative; values depend on live pool state)
{
  "source":           "velora",
  "chainId":          8453,
  "router":           "0x6a000f20005980200259b80c5102003040001068",
  "calldata":         "0xe3ead59e000000000000000000000000...",
  "buyAmount":        "43200000000000000",
  "minBuyAmount":     "42984000000000000",
  "sellAmount":       "100000000",
  "gas":              "318707",
  "ourFeeBps":        10,
  "ourFeeRecipient":  "0xeA8C33d018760D034384e92D1B2a7cf0338834b4"
}

source 表示为该交易对提供较高扣费后买入数量的上游聚合器（0x 或 Velora）。10 bps 的费用已注入 calldata；你看到的 buyAmount 是用户的净额（扣费后、滑点前）。minBuyAmount 体现了请求的 50 bps 滑点容忍度。

3. 签名并提交。 Agent 将交易信息展示给用户的钱包以供签名——to=router, data=calldata, value=0（适用于 ERC20 → ERC20）。PaladinFi 无法看到签名；钱包会直接向 Base 广播交易。

4. 确认。 滑点由链上强制执行：如果实际成交金额低于 minBuyAmount，兑换就会回滚。Agent 会报告交易哈希；用户的钱包会显示 Base 上已结算的买入数量。10 bps 的费用会在同一笔交易中原子转入已公布的金库地址（/health）——无需在链上另行执行第二步。

端到端非托管。 PaladinFi 不会在任何环节持有、签署或转移资金。MCP 服务会返回元数据；钱包负责执行。遭到入侵的兑换路由器只能返回 calldata；即使 calldata 恶意，也会受到 v0.11.71 外层路由器 + 选择器 + 0x Settler 目标地址允许列表的限制（见下文的路线图），并受用户在钱包端设置的批准限额约束。

安装（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。

如需免费进行 OFAC SDN 钱包筛查（无需 MCP、密钥或注册），请参阅 paladinfi.com/docs/screen-wallets/ 中可直接使用的 cURL + React hook 演练——POST /v1/trust-check/ofac 会匿名返回 allow 或 block 判定，速率限制为 1 r/s，突发上限为 3。

端点

方法	路径	用途	定价
GET	/health	存活状态、费用配置、各来源计数器、小数位缓存状态、最近一次 Velora 金丝雀判定、选择器强制执行状态	免费
POST	/v1/quote	含 calldata 的竞争性路由报价——在 0x 和 Velora 中选取扣费后买入数量最高的报价	免费
POST	/v1/trust-check	实时评估代币合约的可信度（OFAC SDN、GoPlus、Etherscan、异常启发式检测）	通过 x402 每次调用需支付 $0.001 USDC
POST	/v1/trust-check/preview	预览信任检查响应结构的样例数据（不会评估实时数据源）	免费
POST	/mcp	MCP Streamable-HTTP 传输（3 个工具——见 mcp-tools.json）	免费

响应结构（节选）

{
  "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 的 10 个基点从买入代币一侧收取，通过上游聚合器的集成方费用机制实现（0x 的 swapFeeBps / Velora 的 partnerFeeBps），因此响应中的 buyAmount 已反映上游协议费用（如有）和我们的 10 个基点——成交时不会再额外扣款。

费用直接汇入 PaladinFi 国库，你无需在链上执行收款步骤。费用接收地址公布在 /health 中，可在链上审计。/v1/quote 端点可免费查询，不收取单次调用费用，也不额外加点差。（/v1/trust-check 是唯一的付费端点，通过 x402 按每次调用收取 $0.001 USDC。）

支持的资产

• 链： Base（8453）。Ethereum 主网、Arbitrum、Optimism、BNB 已列入路线图。
• 代币： Base 上 0x 或 Velora 支持的任意 ERC20 代币。覆盖范围为两个聚合器支持资产的并集——常见交易对（USDC、WETH、cbBTC、USDT、DAI、AERO）在两个聚合器上都可路由；长尾代币通常只能通过其中一个聚合器路由。

Trust Check 数据源

付费 /v1/trust-check 端点会根据一组定义好的公开数据源评估代币合约，并返回单一的 recommendation: "allow" | "warn" | "block" 判定，同时附带各数据源的细分结果。目前查询的数据源及其可验证性说明如下：

数据源	检查内容	可验证性
OFAC SDN 名单（美国财政部）	受制裁地址（合约本身、部署者以及已知关联钱包）	托管后端每天从财政部制裁名单服务（Treasury Sanctions List Service）的数据源 https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN_ADVANCED.XML 刷新名单。提取的地址数据集是 Feature[@FeatureTypeID="345"]/FeatureVersion/VersionDetail[@DetailTypeID="1432"] 条目的并集（FeatureTypeID 345 = ETH/EVM 地址；DetailTypeID 1432 = 数字货币地址详情）。截至上次验证，已加载数量为：87 个 ETH 地址（2026-04-30）。财政部的底层数据源可公开下载，因此任何客户端都可以独立重新推导该数据集并验证匹配结果。
GoPlus Token Security API	貔貅盘模式、铸币权限、放弃所有权、暂停转账、黑名单功能、反巨鲸机制、隐藏所有者、滑点修改器	每次调用时通过 https://api.gopluslabs.io/api/v1/token_security/8453?contract_addresses=<address> 查询。我们会将 GoPlus 响应规范化为对外返回的 factors 数组；GoPlus 的完整响应可公开查询，买家可以独立审查任何信号。
Etherscan / BaseScan 源码验证（通过统一的 Etherscan v2 API）	源码是否已验证，以及代理模式检测（通过 getSourceCode 响应中的 Proxy / Implementation 字段）	每次调用时通过 https://api.etherscan.io/v2/api?chainid=8453&module=contract&action=getsourcecode&address=<address> 查询。公开源码（如已验证）可在 basescan.org 上独立检查。
异常启发式规则（PaladinFi 内部）	合约年龄范围（不足 1h / 24h / 7d）、地址类型分类（通过 eth_getCode 区分合约与 EOA），以及无出站交易历史记录（检查 nonce=0）	启发式规则在托管后端模块 address_anomaly.py 中运行；每个发出的信号（contract_age_under_*、address_kind_*、no_outbound_history）都会显示在响应中，因此买家可以通过直接调用 RPC 复现或覆盖结论。

预览版与付费版的区别。 /v1/trust-check/preview（免费）返回带有 _real: false 标记的静态样例，不会查询上述任何实时数据源。/v1/trust-check（付费，通过 x402 收取 $0.001 USDC）会查询全部四个数据源。预览功能旨在让集成方无需付费即可验证请求格式并查看响应架构；Agent 在使用判定结果前必须检查顶层 _real 字段是否为 true。

请求日志记录。 每次调用后，PaladinFi 会保留一条请求日志，其中包含时间戳、查询的地址、来源 IP 以及计费／速率限制参考信息。这些信息用于收入核算、速率限制执行和滥用检测，不用于分析或转售。PaladinFi 不会单独维护已评估代币或买家查询历史的数据库。

路线图

• Base 上的 0x Settler 路由
• 在 Base 上通过 0x 和 Velora 进行双路由择优（v0.11.66+，2026-05-04）
• MCP Streamable-HTTP 传输，提供 swap_quote、swap_health 和 trust_check_preview 工具
• 通过 x402 提供付费 /v1/trust-check 端点（每次调用 $0.001 USDC）
• 按数据源校验 4 字节 calldata 选择器 + Settler 目标允许列表（v0.11.71 — 纵深防御，抵御路由替换／分发器劫持攻击）
• Ethereum 主网、Arbitrum、BNB、Optimism — 计划中
• Permit2 原生流程（跳过 approve 交易）— 计划中

状态

生产环境。端点已上线，正在监控，并已通过 Base 上的链上测试交易完成端到端验证。查看 /health，了解当前费用配置、版本和各来源的计数器。

此仓库包含的内容

文件 / 文件夹	用途
README.md	本文件
LICENSE	MIT — 适用于此仓库中的所有内容
SECURITY.md	漏洞披露渠道和范围
openapi.yaml	公共 REST API 的 OpenAPI 3.0 规范
mcp-tools.json	MCP 工具架构
examples/	可运行的代码示例（Python、TypeScript）
.github/workflows/ci.yml	CI：推送/PR 时进行 YAML/JSON 语法检查和 OpenAPI 3.0 架构验证

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

联系方式

• 电子邮箱：[email protected]
• 市场推广：paladinfi.com
• API：swap.paladinfi.com/health
• 着陆页：paladinfi.com/swap/

法律信息

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

使用托管服务须遵守 PaladinFi 服务条款和隐私政策。

许可证

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