q402-mcp

@quackai/q402-mcp

用于 Q402 的 MCP 服务，可在 12 条 EVM 链上进行免 Gas 的 USDC、USDT、RLUSD 和 USDG 支付（Robinhood Chain 上的 USDG），可通过 Claude（Desktop / Code）、OpenAI Codex CLI 以及任何其他 Model Context Protocol 客户端调用。

可免费试用。BNB Chain + Base 上可进行 500 笔免 Gas 交易（USDC + USDT），无需银行卡。只需一次钱包签名：https://q402.quackai.ai。 **限时奖励：**2026-08-21~08-28 UTC+9 期间，试用密钥也适用于 Mantle（USDC + USDT）。

**试用范围政策：**免费试用计划下创建的 API 密钥（plan: "trial"）可在 BNB Chain（USDC/USDT 免 Gas）和 Base（USDC/USDT 免 Gas）上永久使用。Avalanche 试用已结束——请使用 Multichain 密钥访问 avax。限时期间 2026-08-21~08-28 UTC+9，Mantle（USDC/USDT 免 Gas）也适用；由服务器端进行时间限制，超出时段将返回 TRIAL_BNB_ONLY。付费 API 密钥始终可使用完整的 12 链矩阵。

通过任意 MCP 客户端，为 12 条 EVM 链上的稳定币支付执行报价 → 路由 →（可选）结算。收款方收到全额；付款方通过 Q402 的 EIP-7702 中继器支付 $0 Gas 费。

快速开始

1. 将服务注册到你的客户端（每个客户端只需一行命令）。
2. 对你的 Agent 说 “Set up Q402”。它会运行 q402_doctor → 创建 ~/.q402/mcp.env → 引导你粘贴密钥。

1. 注册服务

mcp_servers:
  q402:
    command: "npx"
    args: ["-y", "@quackai/q402-mcp"]
    enabled: true

Claude Code（CLI，即 claude 二进制文件）和 Claude Desktop（macOS / Windows 应用）是不同的产品。claude mcp add 命令仅在 CLI 中可用；Desktop 应用需要使用上述 JSON 配置。

此配置中不包含密钥。服务会从 ~/.q402/mcp.env 中读取密钥（与 AWS / Stripe / gh CLI 的方式相同）。

[mcp_servers.q402]
command = "npx"
args = ["-y", "@quackai/q402-mcp"]

重启客户端，然后询问：> "设置 Q402"

Agent 会运行 q402_doctor。首次安装时：

1. 创建 ~/.q402/mcp.env（占位符）
2. 在编辑器中打开该文件
3. 指引你将 API 密钥和签名路径粘贴到文件中，而不是聊天中
4. 重启并重新运行 q402_doctor 进行验证

切勿将密钥粘贴到聊天中。 本地模式会在你的设备上签名；密钥不会离开设备。模式 C（服务端管理）不需要在客户端配置 PK。

选择签名模式

设置了多个模式时，q402_pay 会询问用户要使用哪种模式。选择器：walletMode = "agentic-server" \| "agentic-local" \| "eoa"。

手动设置（无需 AI）

使用下方模板自行创建 ~/.q402/mcp.env。只有在填写了 API 密钥和签名路径后，才会切换到实付模式，因此按原样保存模板仍处于沙盒模式。即使配置了真实密钥，Q402_ENABLE_REAL_PAYMENTS=0 也会强制使用沙盒模式。

# ~/.q402/mcp.env

# ── API key (pick one or both for auto-routing) ──
Q402_TRIAL_API_KEY=          # Free Trial, BNB (permanent) + Base (permanent) + Mantle limited-time (from /event)
Q402_MULTICHAIN_API_KEY=     # Paid Multichain, all 12 chains (from /payment)

# ── Signing path - pick ONE of Mode A / B / C ──
# Mode A: your MetaMask EOA's hex private key.
# Hardware wallets (Ledger / Trezor) are NOT supported here - Q402
# needs a raw hex key it can sign EIP-7702 type-4 authorizations with.
Q402_PRIVATE_KEY=

# Mode B: exported Agent Wallet pk from the dashboard. Keeps your
# MetaMask untouched. Get it at:
#   https://q402.quackai.ai/dashboard → Agent tab → Export
Q402_AGENTIC_PRIVATE_KEY=

# Mode C: no PK needed. A Trial key also enables Mode C one-shot payments;
# leave both PK lines blank. Q402 signs with the server-managed Agent Wallet.
# Multichain key required for recurring, Mode C batch, and bridge/OFT.
# Optional: pin one of your Agent Wallets when you have multiple (max 10).
# Q402_AGENT_WALLET_ADDRESS=0x...

# Live mode switch:
#   0 = sandbox (test mode, no funds move)
#   1 = real on-chain payments
# Default 1 - safe because mode only flips to live when an API key AND
# at least one valid signing path (A/B/C) are populated above.
Q402_ENABLE_REAL_PAYMENTS=1

# Default Q402 deployment. Only change for self-hosted.
Q402_RELAY_BASE_URL=https://q402.quackai.ai/api

# Safety guards (max-amount ships uncommented at $200; lower for tighter caps):
Q402_MAX_AMOUNT_PER_CALL=200
# Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...

# Pre-check (automatic trust-check before outgoing payments in live mode).
# Triggers when paying a first-time counterparty OR amount >= $1.
# Fee: $0.02 per check; verdict cached 7 days (no repeat charge within TTL).
# Set to 1 to disable pre-check entirely (even first-time / large-amount pays).
# Q402_DISABLE_PRECHECK=0

然后运行 chmod 600 ~/.q402/mcp.env（Unix），并重启客户端。配置就全部完成了。**关于 EIP-7702 副作用的提醒：**在某条链上首次完成实付后，你的钱包会在 MetaMask / OKX 中显示“智能账户”——这是 Q402 用于免 gas 结算的委托，可随时通过 q402_clear_delegation 撤销。**x402 用户请注意：**如果 EIP-7702 委托处于旧版实现上，在调用 q402_clear_delegation 之前，q402_x402_fetch 无法对 x402 支付进行签名（在 Base 上免 gas，可撤销；下次 q402_pay 会自动重新委托）。委托给当前支持 ERC-1271 的实现的钱包可正常工作。

高级用法 - 显式注入环境变量

如果你更愿意跳过文件并自行注入环境变量（例如通过 Codex env_vars 允许列表、密钥管理器或 Shell 导出），服务端会回退到 process.env；发生冲突时，process.env 的值优先于文件中的值。因此，现有的 Shell 导出配置可以保持不变，继续使用。

[mcp_servers.q402]
command = "npx"
args = ["-y", "@quackai/q402-mcp"]
startup_timeout_sec = 20.0
env_vars = [
  "Q402_TRIAL_API_KEY",
  "Q402_MULTICHAIN_API_KEY",
  "Q402_PRIVATE_KEY",
  "Q402_AGENTIC_PRIVATE_KEY",
  "Q402_AGENT_WALLET_ADDRESS",
  "Q402_ENABLE_REAL_PAYMENTS",
  "Q402_RELAY_BASE_URL",
]

无需设置即可试用

q402_quote 无需任何配置即可使用——不需要 API 密钥、私钥或环境变量文件。询问：

"比较在所有 12 条 Q402 链上向 vitalik.eth 发送 50 USDC 的 Gas 费用。"

Q402_RELAY_BASE_URL 可覆盖中继端点。连接到可自托管的 Q402 部署或非规范环境时，请显式设置此项。

提供的工具

共 49 个工具，按功能分组。 默认只读；实付模式需要有效的 API 密钥、签名路径，以及 Q402_ENABLE_REAL_PAYMENTS=1。标记为 live mode 的条目会转移资金，并需要在聊天中明确确认。

注意：q402_pay 要求使用 0x 地址；服务器端不会解析 ENS，因此请先在客户端解析。 各链的 Gas Tank 余额和完整 TX 历史记录位于仪表板（仅限钱包签名）。

x402 出站付款（q402_x402_fetch）

q402_x402_fetch 是通用 x402 客户端。它会获取任意 URL，并自动处理 HTTP 402 付款要求响应。如果服务器返回非 402 状态，响应将原样传递，因此它也可用作常规 fetch 工具。

解决的问题。 部分 API 和内容端点使用 x402 协议按请求收费。Agent 访问这类 URL 时，会收到包含机器可读付款要求的 HTTP 402 响应。q402_x402_fetch 会读取这些要求，验证付款选项，针对 Base USDC 签署 EIP-3009 TransferWithAuthorization，将其编码为 base64 JSON 负载，然后重试请求——对于 x402 v2 服务器使用 PAYMENT-SIGNATURE，对于旧版 v1 服务器使用 X-PAYMENT——所有操作均在一次调用中完成。

支持范围。 仅支持 scheme=exact + network=base（CAIP-2 eip155:8453；也接受：base-mainnet）+ Base USDC。任何其他方案、网络或资产都会被明确拒绝，且不会生成签名。

防护措施（三层）。

两阶段同意流程：首次调用（不带 consentToken）会返回 needs_confirmation，其中包含列明确切金额和收款方的预览，以及一个 consentToken。请将报价原样展示给用户，并等待用户在下一条独立消息中确认付款。 只有此后才能使用相同参数并附上 consentToken 重新调用。该令牌只能使用一次，有效期为约 120 秒；若在签发后 2 秒内使用，则会被拒绝（用于防止同一轮内重复调用的保护机制：这是时间阈值，不是用户已确认的证明）。如果没有单独的用户确认消息，切勿在同一轮对话中重新调用。

结果状态——向用户总结前请先阅读。

最小可运行示例。

{
  "url": "https://api.example.com/data",
  "method": "GET",
  "confirm": true
}

如果端点返回 402，工具会以 needs_confirmation 状态和一个 consentToken 作出响应。请将报价原样展示给用户，并等待用户下一条独立消息。使用相同参数并附上 consentToken 再次调用，即可授权付款。该令牌只能使用一次，约 120 秒后过期。

要求。 Q402_ENABLE_REAL_PAYMENTS=1，并且需要本地签名密钥（Q402_AGENTIC_PRIVATE_KEY 或 Q402_PRIVATE_KEY）。签名授权会直接发送到卖方的 facilitator 端点；此流程不涉及 Q402 中继。

前置条件 — 委托检查。 如果你此前曾在此钱包上调用过 q402_pay，它可能已通过 EIP-7702 委托（在 MetaMask / OKX 中显示为“智能账户”）。如果委托给较旧的实现，q402_x402_fetch 将会失败。委托给当前支持 ERC-1271 的实现的钱包可正常使用。恢复方法：调用 q402_clear_delegation（在 Base 上无需 Gas，且可撤销）。清除后，q402_x402_fetch 即可再次使用。下次调用 q402_pay 时会自动重新委托。

治理分析（q402_governance_analyze）

q402_governance_analyze 会分析一项 Snapshot 治理提案，并返回投票建议、五项维度评分及其理由。通过 x402 在 Base 上每次调用收费 0.05 USDC。

输入参数。

语言感知结果。 设置 language: "zh" 后，投票建议、维度名称、评级和理由文本都会以中文呈现，不会向用户显示英文枚举值。

沙盒模式与实时模式

默认沙盒模式：q402_pay 会返回一个虚假的 txHash，并附带 success: false 和 sandbox: true。不会转移资金，也不会消耗配额。

实时模式 = (a) 实时 API 密钥（q402_live_*），(b) 签名路径（A / B / C），(c) Q402_ENABLE_REAL_PAYMENTS=1。实时标志默认值为 1——仅当另外两个条件均满足时才会启用。设为 0 可强制使用沙盒模式，即使配置了真实密钥也是如此。

模板 q402_doctor 会写入 ~/.q402/mcp.env：

# ── API key - fill ONE (or both for auto-routing) ──
# Auto-routing (same for q402_pay AND q402_batch_pay):
#   chain="bnb" or "base" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
#   anything else                                    → Multichain (paid 12-chain)
# Batch ambiguity: 6+ recipient BNB/Base batch with Trial set returns
#   status="ambiguous" instead of executing - agent asks user to pick.
# Override per call with keyScope: "auto" | "trial" | "multichain".
Q402_TRIAL_API_KEY=                # BNB + Base sponsored Trial key (from /event; Avalanche trial ended)
Q402_MULTICHAIN_API_KEY=           # paid 12-chain key (per-chain Gas Tank)

# ── Signing path - pick ONE of Mode A / B / C ──
Q402_PRIVATE_KEY=                  # Mode A: real EOA pk (0x + 64 hex)
Q402_AGENTIC_PRIVATE_KEY=          # Mode B: exported Agent Wallet pk (from dashboard)
# Mode C: leave both PK lines blank. A Trial key enables one-shot Mode C
# payments; Multichain key required for recurring, batch, and bridge/OFT.
# Q402 signs with the server-managed Agent Wallet. Optionally:
# Q402_AGENT_WALLET_ADDRESS=0x...   # pin one of your wallets when you have multiple

# Live mode switch:
#   0 = sandbox (test mode, no funds move - every q402_pay returns a fake hash)
#   1 = real on-chain payments (live mode)
# Default 1. Safe because the gate only flips to live when an API key AND
# at least one valid signing path (A/B/C) are populated. Empty values
# fail the gate, so partial setups stay in sandbox with a hint.
Q402_ENABLE_REAL_PAYMENTS=1

# Pre-check trust-check (live mode). Triggers for first-time counterparties or
# payments >= $1. Fee: $0.02 per check; cached 7 days. Never blocks the main tx.
# Set Q402_DISABLE_PRECHECK=1 to opt out.

已解析的作用域所需配置项若有缺失 → 自动回退到沙盒模式，并提示需要设置哪些配置项。

沙盒响应包含 success: false、sandbox: true、mode: "sandbox"、method: "sandbox"，以及解释原因的 setupHint——四项标记可确保下游摘要不会误报成功。

硬性上限

结合两阶段 consentToken 和实时模式环境变量，进行稳定币付款需要满足：用户在单独的消息中批准的预览 + 金额 ≤ 上限 + 收款方在允许名单中 + 全部 3 个实时环境变量。consentToken 只能使用一次，约 120 秒后过期；如果在签发后 2 秒内使用，就会触发同轮双重调用限制（这是阈值，并不保证用户已确认）。Q (QuackAI) 不受上限限制（它是你自己的代币）；预览、收款方白名单和实时模式环境变量仍适用于它。

配置参考

支持的链

为什么要构建 Q402

AI Agent 正逐渐成为软件的默认交互界面，但一旦需要转移资金，整个技术栈就会出问题：持有 Gas 代币、为每笔交易签名、管理多条链上的钱包。当 Agent 需要自主行动时，这些做法都无法扩展。

Q402 是用于解决这一问题的支付层。单一签名原语（EIP-712 + EIP-7702）可在 12 条 EVM 链上结算免 Gas 稳定币支付，并为每笔交易生成一份由 ECDSA 签名的 Trust Receipt。MCP 包将这一能力集成到 Claude、Codex、Cursor 和 Cline 中，让你的 Agent 可以通过自然语言提示词报价、发送、批量处理和审计支付。

单笔转账和多收款方批量支付现已推出。下一层功能——定期付款、有条件执行和受策略控制的资金库自动化——会以不同方式组合使用同一原语。我们的目标是打造能够管理实际预算、彼此结算并通过无人手动触发的工作流转移价值的 Agent。

Hooks - 可编程支付策略

Q402 Hooks 1.0 是一个策略引擎，可将规则附加到支付生命周期中：OFAC 合规筛查、支出上限 + 收款方允许列表、ERC-8004 信誉门控、Chainlink 预言机条件结算（“仅在 BTC ≥ $80k 时执行”）和自动多收款方拆分——此外还提供需审批的软拦截机制，用于处理大额支付（返回 202 approval_required；调用方在带外重新提交，v1 不会存储挂起的支付）。Uniswap v4 将可编程 Hooks 引入 DEX 流动性；Q402 则将其引入 AI Agent 支付。

开发者参考：docs/HOOKS.md - 生命周期、Hook 合约，以及所有已发布 Hook 的配置和示例。

Base 上的托管支付：docs/ESCROW-VS-INSTANT.md - 供 Agent 使用的即时支付与托管支付决策指南。docs/ESCROW-BASE-DEPLOY-RUNBOOK.md - Base 主网金库部署工程操作手册（仅供人工操作，不适用于 Agent）。

代码仓库

源代码：https://github.com/quackai-org/q402-mcp
问题 / 功能请求：https://github.com/quackai-org/q402-mcp/issues

许可证

Apache-2.0 - 详见 LICENSE。