paladin-swap-mcp

adin-swap-m**[PaladinFi 兑换](https://paladinfi.com/swap/) 的开放客户端和 API 规范** — 面向 Base 上的 AI 代理的竞争性多聚合器兑换路由器。本仓库包含公共的 REST 和 MCP API 规范、有效的代码示例和薄客户端包装器。托管后端位于 `swap.paladinfi.com`，是专有的。 > **路由范围。** PaladinFi 兑换并行查询集成的上游聚合器（目前为 0 Velora），并返回提供最高后费买的聚合器。我们任何返回的路由表示为最佳、最低成本或广泛的 DeFi优。诸如“最佳执行”之类的短美国证券法含义术语，在此处故意不使用。 [](swap.pal.com/health) [ [ [ [](https://model.io) [](LICENSE) fi/paladin-mcp MCP://glama.ai/servers/p/paladin-scp/badges/s)](https://glama.ai/mcp/servers/paladinfi/paladin-mcp) 什么是 PaladinFi 兑换？ 为 **代理** 构建的兑换路由器，需要在链兑换。您的代理调用一个服务返回已可执行 calldata，您的钱包签名并提交：路由器地址**，发送交易到 -data**，包含所有路由预先计算 买入金额**（强制执行的滑点保护 **已注入的联盟费用** — 无您这边进行单独的核算 代理跳过编写聚合器胶水、处理滑点和费用逻辑。，即可获得准备。 该服务为 **非托管**：PaladinFi 永远不会持有、签名或移动用户资金。每个交易都由用户自己的钱包（或代表他们的代理）签名和提交。 ## 安装（MCP） 适用于 [Claude Code](https://claude.com/claude-code) 或任何支持 Streamable-HTTP 传输的 MCP 兼容客户端： ```bash claude mcp add http --scope user-swap https.paladinficp ``` 。变得可用： swap_quote(sellTokenToken, sellAmount, taker, chain slippageBps?)` — 跨 0 Velora 的竞争性最高后费买入金额）；返回准备好的 calldata。 - `trust_check_preview(address, chainId?)` — **示例固定预览信任门。返回 `_real: false`因素都是 `real: false`，并且建议以-` 为例如 `sample-）。**不要使用控制实际兑换签名或任何生产。对于生产信任评估 `/v1/tr`（付$0.001 US调用 via x或使用 npm 插件adinfi/el-trust` /adinfi/agentkit。 - `swap_health()` — 存活率、费用配置、按来源计数十进制缓存最后一个 Velora 启动雀判决、选择状态。 在 [`-tools.json`](m.json) 中查看模式。 ## MCP规性 | | 状态 | ---| | 工具` + `annotations`OnlyHint、open、idempotentdestructiveHint）0.11.74 起 ✓；通过tools/list` 方法| 工具名称 ≤64 个字符 | ✓ `trust_check_preview`（19 个 | | Streamable传输 | ✓ 在 `.pal.com/mcp` 公共 OpenAPI.0 模式 在 [`/openapi.yaml`](https://swap.pfi.com/openapi.yaml) | | 文档速率 ✓ 在 [paladinfi.com/https://paladin/swap)（5 + 突发 次调用 `/vquote`；10 r/s + 突发 调用 `/mcp每个 IP 并发连接） | | x402 付费工具挑战 | ✓费端点 `/v1/trust-check`。MCP `trust_check_preview` 工具被限制为示例固定输出，带有明确的滥用横幅（`_real: false`，`_HUMAN_DO_NOT_USE_AS_REAL_VERDICT`，`sample-` 建议前缀）— 通过设计，永远不是真正的判决 | | + ✓ 查看 [`-tools.json`](m) 以获取模式 | | 客户端（C | ✓ 自 v11.75 `/v1/仅限 `fi.com` +.paladinfi.com` — 其他来源在预检时被阻止 | | 免费真实数据登机口令端点 | ✓ 自 v0.11.77 起 — `POST /v1/trust-check/ofac` 仅AC SDN 钱包筛查腿（匿名，1 r/s 速率限制 + 突发 3 次，日常财政部 XML 刷新）。响应包含 `_paid_endpoint_info` 升级提示到 `/v1/trust-check` 的完整多源组成。钱包-OFAC 范围（代币合约制裁列表计划在未来版本中）。 | | MCP 注册表列表 | ✓ 该包在 [`io.github.paladinfi/paladin-swap`](https://registry.modelcontextprotocol.io/v0/servers?search=paladinfi) 中列出。§4.A-clean 信任检查变体（无支付表面，无 calldata，无交易执行）单独作为 [`com.paladinfi/trust-check-mcp`](https://registry.modelcontextprotocol.io/v0/servers?search=paladinfi) 运输。 | 按照 [MCP `ToolAnnotations`](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations)： - **`swap_quote`** — 标题 `"获取兑换报价"`；`readOnlyHint: true`（返回 calldata，永远不会改变服务器状态），`openWorldHint: true`（调用上游聚合器 0x AllowanceHolder + Velora Augustus v6.2 在 Base 上） - **`trust_check_preview`** — 标题 `"代币信任检查（预览）"`；`readOnlyHint: true`，`idempotentHint: true`（确定性示例固定每地址），`openWorldHint: true`（付费模式上游跨进程边界；存在防御性合同违规处理程序以适应形状漂移） - **`swap_health`** — 标题 `"兑换服务健康"`；`readOnlyHint: true`，`openWorldHint: false`（仅限我们自己的服务状态自省） ## 代理使用演练 当 MCP 感知代理（例如 Claude Code）处理兑换意图时的代表性调用链。特定的工具调用格式因客户端而异；关键点是兑换路由器返回准备好的 calldata，以便代理永远不会自行编写路由逻辑。 **用户：** *"用 100 USDC 兑换 Base 上的 WETH。"* **1. 可选的预交易信任检查** （免费，仅示例固定）。在组成兑换之前，代理可以调用 `trust_check_preview` 以检查购买代币合约的风险形状。 ```json // 工具调用 { "tool": "trust_check_preview", "arguments": { "address": "0x4200000000000000000000000000000000000006", "chainId": 8453 } } ``` ```json // 响应（截断） { "_real": false, "_HUMAN_DO_NOT_USE_AS_REAL_VERDICT": "仅限预览固定。请参阅自述文件。", "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" } ] } } ``` 预览 **仅限示例固定** — 代理必须检查 `_real === true` 才能使用判决。对于生产门控，请发布到 `/v1/trust-check`（付费，$001 USDC/调用 via x402）或使用 npm 插件 [`@paladinfi/eliza-plugin-trust`](https://www.npmjs.com/package/@paladinfi/eliza) / [`@paladinfi/agentkithttps://www.npmjs.com/package/@paladinfi/agentkit-actions)。 **2. 有竞争力的报价和 calldata.** 代理调用 `swap_quote` 以获取路由 + 准备好的交易。 ```json // 工具调用 { "tool": "swap_quote", "arguments": { "sellToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "buyToken": "0x4200000000000000000000000000000000000006", "sellAmount": "100000000", "taker": "0xUserAgentWallet", "chainId": 8453, "slippageBps": 50 } } ``` ```json // 响应（示例；值取决于实时池状态） { "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. 签名 + 提交。** 代理将交易形状呈现给用户的钱包进行签名 — `to=router, data=calldata, value=0` （适用于 ERC2020）。PaladinFi 永远不会看到签名；钱包直接将交易广播到 Base。 **4. 确认。** 滑点在链上强制执行：如果实际填充将交付的金额少于 `minBuy，则兑换会恢复。交易哈希；在 Base结算的买入金额。10 bps 的同一交易原子转移发布的金库`/health`您的这边不需要第二个链上步骤。 **端到端 在任何时候adinFi 都不会签名或移动MCP 服务器返回元数据；钱包执行损的兑换路由器只能返回 calldata；即使是恶意的 calldata 也受到 v0.11.71 外部路由器 + 选择器 + 0x Settler-target 允许列表（参见下面的路线图）和用户的钱包端批准限制的限制。 ## 安装（REST） 不需要 MCP — 直接访问： ```bash curl -sSswap.paladinfi.com/v1/quote \ -H 'content-type: application/json' \ -d '{ "chainId": 8453, "sellToken": "0x833589fCD6eDb6E08f71b54bdA02913", "buyToken": "0x4200000000000006", "sellAmount": "5000000", "taker": "0xYOUR_AGENT_WALLET" }' ``` 完整的 REST 规范在 [`openapi.yaml`](openapi.yaml) 中。 免费的 OFAC SDN 钱包筛查（无需 MCP，无需密钥，无需注册），请参阅 [paladinfi.com/docs/screen-wallets/](https://paladinfi.com/docs/screen-wallets/) 上的 cURL + React Hook 演练 — `POST /v1/trust-check/ofac` 返回“允许”或“阻止”判决，匿名，速率限制为 1 r/s + 突发 3 次。 ## 端点 | 方法 | 路径 | 用途 | 定价 | |--------|------|---------|---------| | `GET` | `/health` | 存活率、费用配置、按来源计数器、十进制缓存状态、最后一个 Vel丝雀判决、选择器强制 免费 | | `POST `/v1/quote` | 有竞争力的路由报价和 calldata — Velora 之间的最高后费买入金额 | 免费 | |` | `/v1/trust-check` | 代币合约的实时信任评估（OFAC SDN、GoPlus、Etherscan、异常启发式） | $0.001 USDC/调用 via x402 | | `POST` | `/v1/trust-check/preview` | 信任检查响应的示例固定预览（不评估实时数据源） | 免费 | | `POST` | `/mcp` | Streamable-HTTP 传输的 MCP（3 个工具 — 参见 `mcp-tools.json`） | 免费 | ## 响应形状（缩写） ```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”）。将交易提交为 `to=router, data=calldata, value=0` （适用于 ERC20→ERC20）来自 `taker`。 ## 示例 - [`examples/python/quote_and_swap.py`](examples/python/quote_and_swap.py) — 使用 web3.py 的 Python - [`examples/typescript/quote_and_swap.ts`](examples/typescript/quote_and_swap.ts) — 使用 viem 的 TypeScript ## 费用 对 **买入代币** 征收 **10 个基点（0.1%）** 的固定费用。费用根据实际成交金额计算，而不是报价估计值，因此即使在报价和成交之间池子发生变化，您也不会支付更多费用。PaladinFi 的 10 bps 从买入代币方通过上游聚合器的集成商费用机制收取（0x 的 `swapFeeBps` / Velora 的 `partnerFeeBps`），因此您在响应中看到的 `buyAmount` 已经反映了上游协议费用和我们的 10 bps — 在成交时无需额外扣除。 费用直接路由到 PaladinFi 金库 — 无需在您这边进行链上接收步骤。`/v1/quote` 端点免费查询，无需每次调用收费或在上面有价差。（`/v1/trust-check` 是唯一付费端点，$0.001 USDC/调用 via x402。） ## 支持的资产 - **链：** Base（8453）。以太坊主网、Arbitrum、Optimism、BNB 正在路线图中。 - **代币：** Base 上 0x 或 Velora 支持的任何 ERC20 代币。覆盖范围是两个聚合器的并集 — 规范对（USDC、WETH、cbBTC、USDT、DAI、AERO）可在两个聚合器上路由；长尾代币通常仅在一个聚合器上路由。 ## 信任检查数据源 付费 `/v1/trust-check` 端点评估代币合约的一组公共数据源，并返回单个 `recommendation: "allow" | "warn" | "block"` 判决以及每个源的明细。当前咨询的来源，具有可验证性指针： | 来源 | 屏幕内容 | 可验证性 | |--------|----------------|---------------| | **OFAC SDN 列表** （美国财政部） | 受制裁地址（合约本身、部署者和已知关联钱包） | 列表每天从 Treasury Sanctions List Service 提要刷新 [@https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN_ADVANCED.XML](https://listservice.ofac.treas.gov/api/PublicationPreview/exports/SDNANCED.XML)。提取的地址数据集是 `Feature[@FeatureTypeID="345"]/FeatureVersion/VersionDetail[@DetailTypeID="1432"]目的并集（FeatureType345/EVM 地址； 1432 = 详细信息）。加载计数（截至验证）：**87 个以太坊地址** （2026-04-30）。基础财政部提要可公开下载，因此任何客户端都可以独立重新导出数据集并验证积极匹配。 | | **GoPlus 代币安全 API** | 蜂蜜罐模式、铸造权限、所有权放弃、转移暂停、黑名单功能、反鲸鱼、隐藏所有者、滑点修改器 | 通过 `https://api.gopluslabs.io/api/v1/token_security/8453?contract_addresses=<address>` 按调用查询。我们规范化 GoPlus 响应到表面上的 `factors` 数组；完整的 GoPlus 公开查询，因此买家可以独立审计任何信号。 | | **Etherscan / BaseScan 源验证** （通过统一的 Etherscan v） | 验证源存在和代理模式检测（通过 `getSourceCode` 响应中的 `Proxy` / `Implementation` 字段） | 通过 `https://api.etherscan.io/v2/api?chainid=8453&module=contract&action=getsourcecode&address=<address>` 按调用查询。公开源代码（当验证时）在 basescan.org 上可独立检查。 | | **异常启发式** （Paladin） | 合窗口（小于 时 / 24 小时 / 7 天）、地址类型分类（合约与 EOA 通过_getCode`）、无输出（nonce=0 检查）发式逻辑在托管 `address_anomaly.py` 中每个发出的信号（_age_under_*`、`address、`no_outbound_history都在响应中显示，以便买重现或通过直接 RPC结论。 | **预览与区别。** `/v1-check/preview` （免费具有 `_real: false` 标记的静态固定 — 不会任何实时数据源。`/v1/trust-check` （付费，.001 USDC via x402）会咨询所有四个。 日志记录。** ，PaladinFi 保留日志条目，其中包含时间查询地址、源 IP 和速率限制引用。此日志用于收入核算、速率限制强制和滥 — 不用于分析售。PaladinFi 不会维护已评估代币或买家的单独数据库。 ## - [x] Base 0x Settler 路- [x] **跨 0x 和 Velora 在 Base源路由** （v11.66+，20205-04） -] 具有 `swap_quote_health` 和 `trust` 工具的 MCP StreamHTTP 传输 - [x] `/v1/trust-check付费端点 via ($0.001 USDC) - [x] 每4 字节 calldata 选择器ler-target 允许列表（v0.11.71 —防御针对路由器替换/调度持攻击） - [ ]主网、Arbitrum、Optimism — 计划中 ] Permit2 原生流程（跳过批准交易）— 计划中 ## 状态 生产环境。端点已上线、，并通过 Base 上的链上测试交易进行端到端验证当前费用配置、版本和按来源计数器，请参见 [`/health`](https://swap.paladinfi.com/health)。 ## 本仓库 | 文件/文件夹 | 用途 | |---------------|---------| README.md`](README.md) | 本文件 | | [`LICENSE`](LICENSE) | MIT — 涵盖此仓库中的所有内容 | | [`SECURITY.md`](SECURITY.md) | 漏洞披露路径 + 范围 | | [`openapi.yaml`](openapi.yaml) | 公共 REST API 的 OpenAPI 3.0 规范 | | [`mcp-tools.json`](mcp-tools.json) | MCP 工具模式 | | [`examples/`](examples) | 有效代码示例（Python、TypeScript） | | [`.github/workflows/ci.yml`](.github/workflows/ci.yml) | CI：YAML/JSON 语法 + OpenAPI 3.0 模式验证在推送/拉取请求时 | **本仓库中不包含：**托管后端（专有）。本仓库是公共客户端表面 — 安装说明、模式和集成代码样本。 ## 联系方式 - 邮箱：[dev@paladinfi.com](mailto:dev@paladinfi.com) - 市场营销：[paladinfi.com](https://paladinfi.com) - API：[swap.pfi.com/health](https://swap.paladinfi.com/health) - 官网：[paladinfi.com/swap/](https://paladin/swap/) ## 法律 由 **Malcontent Games LLC** 运营，业务名为 **PaladinFi**，一家密歇根州有限责任公司。该服务通过第三方聚合器（目前为 0x 和 Velora）路由报价。您保留托管权 — 签署每笔交易。PaladinFi 永远不会持有用户资金。 使用托管服务受 [PaladinFi 服务条款](https://paladinfi.com/terms/) 和 [隐私政策](https://