verify402

verify402-mcp

verify402 的 MCP 服务：在 Agent 签署付款或链上交易前，提供免费的、默认拒绝的预检门控，并提供五项通过 x402 按次付费的链上检查。

适用于 Claude Desktop、Cursor、OpenCode，以及任何使用 stdio 通信的 MCP 客户端。免费门控无需钱包。公开演示的付费工具使用专用热钱包，钱包中已注入 Base Sepolia 测试网 USDC（eip155:84532）。 分析会读取主网链上数据，但演示绝不会结算主网付款。桥接服务绝不会签署或发送交易。

已发布软件包说明： [email protected] 已发布到 npm，付费调用默认使用 Base Sepolia 测试网（eip155:84532），供公开演示使用。在单独的部署中，Base 主网（eip155:8453）需要显式启用 VERIFY402_NETWORKS，此版本未启用该功能。此前发布的 1.0.8、1.0.6、1.0.5 和 1.0.4 软件包均不可变，且 1.0.4 默认使用 Base 主网。请勿重新发布或覆盖这些版本。

工具

工具	价格	可回答的问题
preflight_gate	免费	“我应该签署这笔付款请求或交易吗？”——给出 PASS / CAUTION / BLOCK 及原因、checked / notChecked 和一份短时有效的收据
verify_arbitrage	$0.05	“这个跨平台套利机会现在是真的吗？”
check_token_safety	$0.10	“这个代币能以合理规模卖出吗？往返交易成本是多少？”——根据证据给出 TRUST / CAUTION / AVOID；不进行代码审计
get_best_route	$0.03	“这笔兑换实际会产生多少链上成本？”——给出最佳路径和所有报价平台
verify_quote_fairness	$0.05	“经纪商/机器人给了我这个报价——靠谱吗？” fair / overpaying / too_good_to_be_true
get_trade_depth	$0.05	“在往返成本吞噬收益之前，我最多能在这里交易多大规模？”——按规模给出价格影响、往返成本和容量

preflight_gate 是入口工具。在签署任何加密货币交易或 x402 付款请求前，请先调用它。如果 sign_allowed 为 false，请勿签署。如果 requires_ack 为 true，请向操作员展示相关原因。收据会过期（默认 90 秒）；请重新调用，而不要重复使用。

对于付款意图，policy.allowedResourceHosts 会将 payment.resource 中的主机绑定到策略；匹配的主机可以得到 PASS，其他主机则会被 BLOCK。如果没有 allowedResourceHosts 或 expectedResource，则即使资源有效，也会得到 CAUTION resource_identity_unverified，并在 notChecked 中列出 resource identity。桥接服务会将此策略转发给服务端；服务端负责执行该策略。

以下两项可选检查会按原样转发：

• payment.idempotencyKey + policy.obligation.settledKeys 会拒绝调用方已结算过的键；policy.obligation.spentUsd + grantUsd 会拒绝超出授权额度的累计支出。桥接服务不会持久化此状态。
• policy.sellerPayoutWallets 是调用方提供的收款钱包允许列表。若不匹配则会被 BLOCK，但匹配并不代表来源已验证，也绝不会添加 payee_payout_binding。
• policy.sellerPayoutManifest 会从调用方指定的 HTTPS 来源获取卖家签名的清单，此来源位于 402 之外。只有已验证且 payTo 列表匹配的清单才会添加 payee_payout_binding。响应会包含 payeeBinding，其中列出来源、源站、签名者、到期时间和清单哈希值。

在此层级，门控仅提供建议：桥接服务不会持有 Agent 的交易密钥，因此无法阻止忽略检查结果的 Agent。执行签名的执行器负责强制执行——先验证收据，再签名。请参阅 examples/preflight-guard.mjs ，了解一份默认拒绝的参考实现；在没有已验证收据时，它会拒绝调用签名器。

分发与运行

该软件包已在 npm 上正式发布，名称为 verify402-mcp，并已收录于官方 Model Context Protocol Registry。

通过 npx 直接运行（stdio 传输）：

npx -y verify402-mcp --help

也可以全局安装：

npm install -g verify402-mcp
verify402-mcp --help

或从源代码运行：

git clone https://github.com/a32116150-ctrl/verify402
cd verify402/mcp-bridge
npm ci
node index.mjs --help

---

AI Agent 集成（分步指南）

第 1 步：免费模式（零配置，无需钱包）

如需为 AI Agent 提供免费的 preflight_gate（在签名前检查交易 calldata、支付挑战、收款方/金额、授权和区块时效性），请将以下内容粘贴到客户端配置中。付费的 check_token_safety 检查会额外进行基于报价的可售性检查；它不会执行转账，也不保证能识别蜜罐。

Claude Desktop（claude_desktop_config.json）或 Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "verify402": {
      "command": "npx",
      "args": ["-y", "verify402-mcp"],
      "env": {
        "VERIFY402_URL": "https://verify402.onrender.com"
      }
    }
  }
}

第 2 步：付费模式（设置热钱包）

如需启用 5 项深入的链上真实性检查（verify_arbitrage、check_token_safety、get_best_route、verify_quote_fairness、get_trade_depth），请配置专用热钱包，通过 x402 使用 USDC 按次付费：

1. 创建专用热钱包：
   • 在 MetaMask、Rabby 中创建一个全新钱包，或通过 cast wallet new 创建。
   • ⚠️ 安全警告：切勿使用主要个人钱包、冷存储钱包或金库。
2. 为钱包充值至 Base Sepolia 测试网（EIP-155:84532）：
   • USDC：从水龙头获取 Base Sepolia 测试网 USDC（该桥每次调用收费：0.03 至 0.10 美元的测试网 USDC）。
   • Gas（Base Sepolia 上的 ETH）：如果客户端需要，请获取少量 Base Sepolia 测试网 ETH 用于 Gas。公开演示无需主网资金。
3. 在 MCP 客户端中配置环境变量：
   • 将 EVM_PRIVATE_KEY 设为热钱包的 64 字符私钥。
   • 将 VERIFY402_NETWORKS 设为 eip155:84532（Base Sepolia 测试网）。
   • 设置安全上限 MAX_PAYMENT_USD（例如 "0.25"）和 MAX_DAILY_USD（例如 "1.00"）。

付费配置块（Claude Desktop、Cursor、Cline、Windsurf）：

{
  "mcpServers": {
    "verify402": {
      "command": "npx",
      "args": ["-y", "verify402-mcp"],
      "env": {
        "VERIFY402_URL": "https://verify402.onrender.com",
        "EVM_PRIVATE_KEY": "0xYOUR_HOT_WALLET_PRIVATE_KEY",
        "MAX_PAYMENT_USD": "0.25",
        "MAX_DAILY_USD": "1.00",
        "VERIFY402_NETWORKS": "eip155:84532",
        "VERIFY402_PAY_TO": "0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb"
      }
    }
  }
}

OpenCode V2 配置

在 opencode.jsonc（或 ~/.config/opencode/opencode.jsonc）中：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "verify402": {
        "type": "local",
        "command": ["npx", "-y", "verify402-mcp"],
        "environment": {
          "VERIFY402_URL": "https://verify402.onrender.com",
          "EVM_PRIVATE_KEY": "{env:EVM_PRIVATE_KEY}",
          "VERIFY402_NETWORKS": "eip155:84532",
          "MAX_PAYMENT_USD": "0.25",
          "MAX_DAILY_USD": "1.00"
        }
      }
    }
  }
}

---

AI Agent 如何使用 verify402（提示词示例）

配置完成后，Agent 会自动在其上下文中看到这些工具。你可以直接向它发送提示词：

• 预检门（免费）：

  “签署这笔交易之前，请对支付请求 / calldata 调用 preflight_gate。如果结果为 BLOCK，请中止操作并说明原因。”

• 基于代币报价的可售性检查（0.10 美元，不是代码审计）：

  “使用 check_token_safety 分析代币 0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE。在已配置的平台上，能否以实际可行的规模卖出？往返交易成本是多少？结果属于 TRUST / CAUTION / AVOID？请查看 notChecked 中的转账限制。”

• 套利验证（0.05 美元）：

  “使用 verify_arbitrage 验证当前区块中，链 1 上 WETH/USDC 在 Uniswap V3 和 Sushiswap 之间是否存在套利机会。”

• 报价公平性审计（0.05 美元）：

  “有人提出用 1,000 USDC 兑换 0.35 WETH。运行 verify_quote_fairness，看看这个报价是否公平，还是我付得太多了。”

• 市场深度与承载能力（0.05 美元）：

  “对 Uniswap V3 上的 WETH 运行 get_trade_depth，查看 50,000 美元的兑换会受到多大滑点和价格影响。”

安全

• 该桥接仅签署 x402 付款，绝不会签署或广播交易。
• 每次付费工具调用都会生成一个 crypto.randomUUID() 幂等键，并将其作为 x-idempotency-key 发送。发生超时或响应丢失时，会使用同一个键重试，因此服务器会重放已结算的判定（recovery.replayed: true），而不会重复收费。对于 402 或 409，绝不会自动重试；错误会传递给 MCP 客户端。该键是机密，绝不会记录日志或返回。
• 签名前，付费客户端会确认 402 来自已配置的服务器和已知付费路由，位于允许列表中的 EVM 网络，并且收款方是 verify402 收款地址。它只接受已识别的默认资产（USDC），将金额限制在 MAX_PAYMENT_USD 以内，并拒绝重定向。
• 系统会检查整个 402 挑战，而不仅是客户端选择的选项：每项提供的要求都必须使用允许列表中的网络、已配置的收款地址、该网络对应的规范 USDC 合约以及规范 EIP-712 域，extra.assetTransferMethod 必须为 eip3009，maxTimeoutSeconds 必须是大于 0 且不超过 300 的整数，并且金额不得超过上限。如果挑战还提供 Base 主网选项，客户端会拒绝整个挑战，而不是筛选出测试网选项。客户端还会证明它签署的要求与服务器发送的对象完全相同。
• 可通过 VERIFY402_NETWORKS、VERIFY402_PAY_TO 和 VERIFY402_RESOURCE_PREFIX 缩小允许列表范围，或将其指向其他部署。桥接的默认值为 Base Sepolia 测试网（eip155:84532）和公开的 verify402 收款地址。VERIFY402_NETWORKS 的取值受支持网络映射表约束（eip155:84532、eip155:8453）；显式设置为空值时会安全关闭，而不会回退到默认值。
• MAX_PAYMENT_USD 会在 x402 客户端内部、签名生成前强制执行；移除它会造成安全性倒退。金额上限限制的是桥接可授权的额度；不能保护已泄露的私钥。
• 桥接会发送 X-Verify402-Client: verify402-mcp/<version>，并在 User-Agent 中发送相同的版本号。这只是用于 /usage 的匿名标签，并非账户：其中不包含钱包、密钥或用户 ID，且服务器将其视为由客户端自行声明、可伪造的信息。
• preflight_gate 是一项检查，而非保证。请阅读 notChecked：它不会筛查收款方的信誉或制裁情况、审计合约、模拟完整余额变动、审计交易对手、独立证明收款方所有权、跨进程持久化义务账本、扫描工具描述或响应中的提示词注入，或防范 MEV。它能捕获可衡量的签名错误，但并不能识别所有骗局。
• 若要强制执行而非仅提供建议，请使用参考执行器。

依赖项与 npm audit

此软件包不再依赖 @x402/axios 或 @x402/evm。x402 付款方（PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE，exact 方案，EIP-3009 授权）现已在此处基于 viem 实现，运行时依赖项包括：MCP SDK、axios、dotenv、viem、zod 4。

原因：@x402 2.28.0 依赖 zod ^3.24.2，这会解析到 GHSA-mrhx-c7xc-m3w5 （在验证超大数组时可能因内存耗尽而遭受 DoS；该公告涵盖所有低于 4.6.6 的 zod 版本，且没有已修复的 3.x 版本）。npm 会忽略依赖项内部声明的 overrides，因此安装 1.0.8 及更早版本时会显示“高危”审计横幅。上游请求见 x402-foundation/x402#3953。

从其 tarball 安装的当前软件包：

$ npm i verify402-mcp
added 123 packages
$ npm audit
found 0 vulnerabilities

桥接器使用相同的线路协议付款。唯一的行为变化是外观上的：npm ls @x402 不再显示任何内容，安装包也少了 5 个软件包。付费调用策略（网络允许列表、已配置的收款方、规范的 USDC、每笔付款上限、与工具绑定的资源）未变，仍会在任何签名生成前于 payment-policy.mjs 中执行。

明确配置主网（非公共演示）

主网结算是独立的部署选择，并非桥接器或演示的默认设置。在独立确认服务端主网就绪检查、facilitator、常开主机和钱包资金均已就绪之前，请勿将此客户端指向主网。

# Only for a deliberate mainnet deployment, never against the public demo.
VERIFY402_NETWORKS=eip155:8453
VERIFY402_PAY_TO=<the payee named by the mainnet 402>

公共演示支持 eip155:84532；仅限主网的策略会拒绝该质询，而不会默默花费主网资金。反向情况同样受到限制：演示策略会拒绝仅限主网的质询。

开发

npm pack --dry-run

许可证

Apache License 2.0。请参阅 LICENSE 和 NOTICE。

你可以使用、修改和分发此软件包，包括在商业 Agent 系统和机器人中使用。如果你重新分发此软件包或包含它的产品，请保留版权声明、许可证文本和 NOTICE 文件。verify402 名称和徽标不得用于背书。