trust-check-mcp

trust-check-mcp

PaladinFi Trust Check 的开放客户端和 API 规范 — 为 Base 上的 AI Agent 提供免费的钱包 OFAC SDN 筛查和样例夹具信任检查预览。本仓库包含公开的 REST 和 MCP API 规范、可运行的代码示例以及轻量客户端封装。托管后端为专有软件。

由 Malcontent Games LLC 运营，商号为 PaladinFi。

---

什么是 PaladinFi Trust Check？

为 Base 上的 AI Agent 提供免费的钱包 OFAC SDN 筛查接口。调用一次 MCP 工具，即可根据美国财政部 OFAC SDN 名单返回二元 allow / block 判定。

• 无需身份验证。 无需 API 密钥、注册或付费。
• 实时美国财政部 OFAC SDN 数据。 每日从财政部 XML 数据源刷新。
• 每个响应都包含新鲜度元数据。 每个响应的 trust 块中都会提供 _ofac_list_updated_at（ISO 时间戳）和 _ofac_sdn_count；调用方无需信任我们的记录，即可验证数据是否过时。
• 响应经过签名。 每个 /ofac 响应都包含对规范化 JSON 请求体的 Ed25519 签名（_signature、_signature_alg、_signature_pubkey_hex），供使用方验证来源完整性。
• 速率限制。 每个 IP 每秒 1 个请求 + 突发 3 个请求 + 每个 IP 3 个并发连接。
• 非托管、只读。 不处理资金、不提供 calldata、不提供签名接口，也不执行交易。

此 MCP 是用于制裁筛查的链下 HTTP 接口。对于合约内的门控逻辑（在结算合约中运行的 Solidity 修饰符），链上制裁预言机仍是标准接口。

安装（MCP）

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

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

添加前，请确认主机已启动：

curl -i https://trust.paladinfi.com/health
# Expect: HTTP/1.1 200 OK

执行 mcp add 后，重启客户端。随后会提供三个工具：

• trust_check_ofac_free(address, chainId?) — 实时美国财政部 OFAC SDN 钱包筛查。返回 recommendation: "allow" | "block"，并附带 _real: true 和新鲜度元数据。
• trust_check_preview(address, chainId?) — 对更广泛的信任检查响应结构进行样例夹具预览。trust 块带有 _preview: true，每个因素的 real 均为 false，且判定以 sample- 为前缀。请勿使用预览判定来门控真实兑换、签名或任何生产环境 Agent 决策。
• trust_check_health() — 存活状态、支持的链、OFAC 名单刷新时间戳及条目数量。

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

REST API

MCP 服务提供三个 REST 端点。后端与其他 PaladinFi 服务一起托管在共享源站（swap.paladinfi.com）；此 MCP 服务仅用于只读 OFAC 筛查，不提供更广泛平台上的 calldata、签名或交易接口。可以通过 curl 直接调用 REST 端点：

# Free OFAC SDN screen
curl -X POST https://swap.paladinfi.com/v1/trust-check/ofac \
  -H "content-type: application/json" \
  -d '{"chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}'

# Sample-fixture preview
curl -X POST https://swap.paladinfi.com/v1/trust-check/preview \
  -H "content-type: application/json" \
  -d '{"chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}'

完整架构请参阅 openapi.yaml。

chainId 说明： OFAC SDN 筛查针对钱包地址，与链无关——无论在哪个网络，同一个 0x 地址都会以相同方式出现在名单中（或不出现在名单中）。接受 chainId 是为了与完整的 /v1/trust-check 端点保持一致；它不会限定 OFAC 匹配的范围。

覆盖范围和限制

维度	值
链	Base 主网（chainId 8453）
来源	美国财政部 OFAC SDN XML 数据源
管辖范围	仅限美国 OFAC SDN。不涵盖欧盟、联合国、英国或其他制裁制度；在美国以外司法管辖区的调用方有责任根据当地适用的名单进行筛查。
刷新频率	每日从财政部 XML 数据源刷新
名单规模	约 93 个钱包/EOA 地址（参见实时的 _ofac_sdn_count）
速率限制	每秒 1 个请求 + 突发 3 个请求 + 每个 IP 最多 3 个并发请求
身份验证	匿名（无需 API 密钥或注册）
费用	免费

响应格式

trust_check_ofac_free

数据新鲜度和范围标记位于 trust 块内部。顶层还包含 Ed25519 签名，以及指向付费完整评估端点的指针。

{
  "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "chainId": 8453,
  "trust": {
    "recommendation": "allow",
    "factors": [
      { "source": "ofac", "signal": "not_listed", "weight": 0, "details": "", "real": true }
    ],
    "version": "1.1",
    "_real": true,
    "_scope": "ofac-only (wallet-address screen; use /v1/trust-check for full composition: GoPlus + Etherscan + anomaly heuristics)",
    "_ofac_list_updated_at": "2026-05-31T04:08:06Z",
    "_ofac_sdn_count": 93
  },
  "_signature": "<base64 Ed25519>",
  "_signature_alg": "ed25519",
  "_signature_pubkey_hex": "272b6b62230d9da810f3ed64b5e5147f1ae062cb46ad7f25044b0aab1d18fb6f"
}

受制裁地址会返回相同格式，其中 trust.recommendation: "block"，以及一个 { "source": "ofac", "signal": "sdn_listed" } 因子。

在使用判定结果前进行程序化安全检查：

resp = httpx.post("https://swap.paladinfi.com/v1/trust-check/ofac",
                  json={"chainId": 8453, "address": addr}).json()
trust = resp["trust"]
assert trust["_real"] is True                    # not a fixture
assert trust["_scope"].startswith("ofac-only")   # not a different evaluation path
verdict = trust["recommendation"]                # "allow" or "block"

trust_check_preview

这是一个示例数据 FIXTURE，并非实时评估。信封格式相同（address、chainId、trust，以及顶层的 request_id 和 _mcp_paid_endpoint_info），但 trust 内部包含：_preview: true、带有 sample- 前缀的 recommendation（例如 "sample-allow"）、值为 null 的 risk_score、real: false 的每个因子，以及 trust._message 中的禁止将其作为真实判定使用的横幅。预览中没有 _real 字段——可通过 _preview: true 标记和 sample- 前缀判断这是示例数据，而非真实筛查结果。

刷新频率

OFAC SDN 名单每日从 https://www.treasury.gov/ofac/downloads/sdn.xml 获取。每个响应都会在 trust._ofac_list_updated_at 中返回内存名单的精确时间戳，因此调用方无需信任单独的记录层即可检测数据是否过期。

如果无法访问源数据源，则保留内存中的名单，且 _ofac_list_updated_at 会继续反映上次成功刷新的时间。名单过期不会自动降级为 block——负责执行最大可接受过期时间的调用方应自行检查 _ofac_list_updated_at。

日志记录和保留

服务会在标准 nginx 访问日志中记录请求时间戳、源 IP（仅用于速率限制核算）和查询的地址。日志会保留 30 天，用于运营调试，之后轮换。除速率限制窗口外，不会建立调用方身份与查询地址之间的持久关联。不进行分析、不使用第三方跟踪，也不丰富个人身份信息（PII）。

速率限制行为

超过每秒 1 个请求 + 突发 3 个请求限制的请求会收到 HTTP 429。速率限制窗口按 IP 计算；不会封禁 IP，也不会逐步升级封锁——窗口结束后的下一次请求会正常处理。Retry-After 标头会指明何时可以重试。

使用此端点须遵守 PaladinFi 条款。

相关软件包

对于组合多个信号进行评估的场景（OFAC + GoPlus 代币安全性 + Etherscan 源代码验证 + 异常启发式分析），PaladinFi 还提供其他 npm 软件包——详情请参见 paladinfi.com/trust-check。从此 MCP 迁移到多信号软件包：安装所选 npm 软件包，与此 MCP 并用或替换此 MCP；工具名称有重叠，因此调用方无需重写调用代码即可迁移。

何时使用此工具，而非链上制裁预言机

	链上预言机	trust_check_ofac_free
访问方式	在结算合约上进行 Solidity 调用	HTTP POST（匿名）
最适合	合约内的门控逻辑（修饰符）	链下 Agent、机器人、Web 应用、MCP 客户端
响应	纯 bool	包含数据新鲜度元数据的结构化 JSON
费用	每次调用消耗 Gas	免费 + 受速率限制
覆盖范围	通常涵盖多个司法管辖区	仅限美国 OFAC SDN

这两种方式互为补充：一种是用于 Agent / Web UI 展示的链下 HTTP 筛查，另一种是用于结算合约的链上修饰符。

示例

零依赖，可直接复制粘贴运行。默认会筛查一个干净地址和一个确实被 OFAC 列入名单的地址，因此首次运行就能看到 allow 和 block 两种结果。可将自己的地址作为参数传入。退出代码：0 表示所有地址均干净，1 表示有地址被列入名单，2 表示请求错误——可直接用于 CI 或发送前的检查。

• examples/python/check_address.py — Python 3（仅使用标准库；无需 pip install）。运行：python check_address.py。
• examples/typescript/check_address.ts — 使用内置 fetch 的 TypeScript。运行：npx tsx check_address.ts。

如需了解同一端点的浏览器/React 集成，请参阅教程：paladinfi.com/docs/screen-wallets/。

文档

• 托管的 MCP 端点：trust.paladinfi.com/mcp
• 实时 /health：trust.paladinfi.com/health
• Apex 文档：paladinfi.com/trust-check/
• 用于兑换路由的姊妹 MCP：paladin-swap-mcp

联系方式

• 一般咨询：[email protected]
• 安全问题：请参阅 SECURITY.md

法律声明

由 **Malcontent Games LLC（以 PaladinFi 名义经营）**运营。托管后端 swap.paladinfi.com 和 MCP 服务 trust.paladinfi.com 均为专有内容；本仓库提供客户端规范和示例，并采用 MIT 许可证。