x402 Research

x402-research-mcp

适用于 x402-research 按调用付费 API 的 MCP（stdio）服务。 默认使用测试网（Base Sepolia）。只有明确设置 X402_NETWORK=eip155:8453 时才使用 Base 主网。 发布者不会持有密钥：付款来自你通过环境变量提供的自己的钱包密钥，并且 每次调用和每个会话的支出都有上限。

警告

请使用专用的低余额钱包，绝不要使用你的主钱包。 为此服务创建一个全新的密钥，并且只为其充值少量 USDC（主网上的充值金额应略高于会话上限）。任何能够读取你的 MCP 客户端配置或此进程环境的个人或程序，都能花费该钱包中的资金。支出上限限制的是此服务会签署的金额，而不是泄露的密钥能花费的金额。

工具（每次调用的价格，以 Base 上的 USDC 计，来自 /llms.txt）

工具	路由	价格
signal(asset)	GET /api/signal/{asset}	0.003
signal_batch(assets[≤10])	GET /api/signal-batch?assets=	0.02
brief(asset)	GET /api/brief/{asset}	0.03
risk_snapshot(address)	GET /api/firm/risk-snapshot?address=	0.03
invoice_decode(header)	POST /api/x402/invoice-decode	0.02
settlement_status(tx)	GET /api/x402/settlement-status?tx=	0.02
approval_enumerate(address)	GET /api/x402/approval-enumerate?address=	0.03
preflight(address, invoice?)	GET /api/x402/preflight?address=[&invoice=]	0.05
session_status()	本地	免费

资产：btc eth sol xrp doge ada avax link dot ltc bch uni aave xlm hbar shib sui near atom fil。 每个付费工具还接受 preview: true（返回 402 条款，不付款）和 max_price_usdc。

安全

• 预览模式会在未设置 X402_BUYER_PRIVATE_KEY 或设置 X402_PREVIEW=1 时启用：工具会返回解码后的 402 条款，绝不会签名。
• 单次调用上限 X402_MAX_PRICE_USDC（默认值为 0.10）。工具的 max_price_usdc 只能调低该上限。
• 会话上限 X402_SESSION_CAP_USDC（默认值为 0.50）。如果某次调用会导致支出超过上限，则会在签名前被拒绝。签名付款发送时计入支出。服务器进程重启后，上限计数会重置。
• 如果报价高于标示价格、使用其他网络、方案不是 exact，或使用非规范 USDC 资产，则会拒绝报价。
• payTo 允许列表（硬编码）： signal、signal_batch 和 brief 只向 0xacfca8bc6567e7db35ad8c814756695dad1cfb30 付款。risk_snapshot、invoice_decode、settlement_status、approval_enumerate 和 preflight 只向 0xa26f179e42836bc4ae0cea997fdfc9602d5b8147 付款。任何其他收款方都会被拒绝，即使 X402_RESEARCH_URL 指向其他地址也一样。
• 服务器绝不会记录其环境或密钥，错误消息也不会回显配置。
• 无法传入预签名付款：每笔付款都由此服务器在上述上限范围内签名。
• 请使用仅持有少量 USDC 的专用热钱包。密钥保留在本地进程中，绝不会被记录或返回。

配置

变量	默认值
X402_NETWORK	eip155:84532（Base Sepolia）。设置为 eip155:8453 可使用 Base 主网
X402_RESEARCH_URL	https://x402-research-iota.vercel.app（仅限主网；测试网需要部署到 Sepolia）
X402_BUYER_PRIVATE_KEY	未设置 → 仅预览
X402_MAX_PRICE_USDC / X402_SESSION_CAP_USDC	0.10 / 0.50
X402_PREVIEW	未设置（设为 1 可强制启用预览）

安装

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

{
  "mcpServers": {
    "x402-research": {
      "command": "npx",
      "args": ["-y", "@agentfirm402/x402-research-mcp"],
      "env": {
        "X402_NETWORK": "eip155:8453",
        "X402_PREVIEW": "1"
      }
    }
  }
}

请先以预览模式启动。若要付款，请移除 X402_PREVIEW 并添加 "X402_BUYER_PRIVATE_KEY": "0x…"（使用专用低余额钱包，绝不要使用主钱包）， 并可选择添加 "X402_SESSION_CAP_USDC": "0.25"。

测试

npm test 使用一次性密钥和零资金，针对本地模拟对象离线运行。测试涵盖每项检查对应的拒绝情况、无密钥时的预览模式，以及一项 stdio 泄漏测试：该测试会对全部 stdout 和 stderr 执行 grep，检查是否包含 /0x[0-9a-fA-F]{64}/。 npm run test:mainnet-preview 会在预览模式下发起实时主网 402 调用，不会付款。

发布

依赖项已精确锁定，并提交了锁文件。仅通过 .github/workflows/mcp-publish.yml 发布（手动触发，npm publish --provenance）。

仅供参考，不构成财务建议。MIT。