agent-pay-mcp

@deepfirstsearch/agent-pay-mcp

一个 MCP 服务，让任何 MCP Agent（Claude Desktop、Claude Code、Cursor，……）都能在 Base 上用 USDC 支付 x402 API，同时避免超支，即使网页或 API 响应通过提示词注入攻击它也不例外。

Beta 版，未经审计。 请使用 Base Sepolia 或在 Base 主网上使用小额资金。

模型只能使用以下工具：

工具	模型可以做什么
paid_fetch(url, method?, body?, contentType?)	获取 URL。如果返回 402 Payment Required，只有在商户、价格和预算符合你的配置时才会进行付款
check_price(url, method?, body?, contentType?)	免费查看支付该 URL 会产生什么结果，无需付款。显示待支付的价格和收款方，或拒绝原因（payee_mismatch、price_changed，……）。不会签署任何内容。no_challenge 表示当前没有显示付款条件，并不代表该路由免费
list_merchants()	查看可付款的源站、对应价格和剩余预算
budget_status()	查看每个商户的剩余预算、额度周期续期时间和金库余额

模型无法选择收款方、金额、网络或限额：这些参数都无法传入。商户、价格锁定值、上限和支出计划均来自你的配置文件；密钥来自环境变量。响应会放在带有随机标签、标记为不可信数据的围栏代码块中。链上，Agent Safe 金库会强制执行你签署的单笔和每日付款上限，即使这台机器遭到入侵也不例外。

设置

1. 预算（所有者，仅需设置一次）： 使用所有者 CLI创建金库并为每个商户签署预算：运行 npx @deepfirstsearch/agent-pay owner create-vault，然后运行 owner budget …，该命令会输出 intentId 和可直接粘贴的 merchants[] 条目。（没有金库？省略 vault、tranche 和 intentId；此时每个商户都会获得一个由 AGENT_PAY_BURNER_SEED 派生的独立付款方地址，你需要自行向该地址充值 USDC。）
2. 配置： 复制 config.example.json 并填写内容。金额使用 USDC 十进制字符串。tranche 不得超过对应意图的 trancheCap 和 maxPerTx。
3. 密钥（仅限环境变量）：
   • AGENT_PAY_AGENT_KEY：意图的 Agent 密钥（仅在使用金库时需要）。
   • AGENT_PAY_MCP_CONFIG：配置文件路径，除非你将其作为参数传入。
   • AGENT_PAY_BURNER_SEED：派生付款方地址所用的 32 字节密钥。切勿使用所有者密钥。

Claude Code

claude mcp add agent-pay \
  -e AGENT_PAY_AGENT_KEY=0x… -e AGENT_PAY_BURNER_SEED=0x… \
  -- npx -y @deepfirstsearch/agent-pay-mcp /absolute/path/config.json

OpenClaw

npm install -g @deepfirstsearch/agent-pay-mcp   # or use "command":"npx","args":["-y","@deepfirstsearch/agent-pay-mcp","/absolute/path/config.json"]
openclaw mcp set agent-pay '{"command":"agent-pay-mcp","args":["/absolute/path/config.json"],"env":{"AGENT_PAY_AGENT_KEY":"${AGENT_PAY_AGENT_KEY}","AGENT_PAY_BURNER_SEED":"${AGENT_PAY_BURNER_SEED}"}}'
openclaw mcp probe agent-pay   # - agent-pay: 3 tools

完整操作指南：OpenClaw 指南。

Claude Desktop / Cursor

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

{
  "mcpServers": {
    "agent-pay": {
      "command": "npx",
      "args": ["-y", "@deepfirstsearch/agent-pay-mcp", "/absolute/path/config.json"],
      "env": { "AGENT_PAY_AGENT_KEY": "0x…", "AGENT_PAY_BURNER_SEED": "0x…" }
    }
  }
}

如果要从源代码而不是 npm 使用：运行 cd integrations/mcp && npm ci && npm run build，然后使用 node /path/to/integrations/mcp/dist/index.js 作为命令。

使用经过验证的卖家快速上手（Base 主网）

verified 预设包含 35 个 x402 卖家，每个卖家的收款地址和价格都已通过真实付款确认，并附有指南。scripts/verify-preset.ts 会实时重新检查这些信息，但不会付款；卖家列表位于 src/presets.ts。选择你要使用的卖家，并设置总预算：

{
  "network": "eip155:8453",
  "preset": "verified",
  "presetOnly": ["https://netintel.dev"],
  "periodBudget": { "amount": "1.00", "hours": 24 }
}

将其保存为 preset.json，然后使用 AGENT_PAY_BURNER_SEED=0x$(openssl rand -hex 32) npx -y @deepfirstsearch/agent-pay-mcp ./preset.json 启动服务。启动时会打印每个卖家的付款方地址。在 Base 上向该地址转入少量 USDC（0.10 可用于数十次调用）。然后让你的 Agent 对卖家的 URL 调用 check_price 和 paid_fetch，例如 https://netintel.dev/web/extract?url=https://www.sitemaps.org/protocol.html。请保留种子：相同的种子会生成相同的付款方地址。

• **你自己的条目优先：**如果你在 merchants 下列出了具有相同 origin 的商家，预设中的对应条目将被忽略。
• 选择卖家：presetOnly 将预设限制为指定的 origin；presetExclude 会排除指定的条目；presetMaxSpend（默认为 "0.25"）会限制每个卖家在每个计划窗口内的支出。
• **预算：**使用预设时必须设置 periodBudget。这是所有卖家的总预算。
• **Vault：**目前，预设仅适用于由你自行注资的付款方。使用 vault 时，请改为在 merchants 中列出商家及其 intentId。

离线试用（1 分钟）

无需准备密钥，也无需连接链：使用 SDK 运行本地模拟商家，并让服务连接到它。

npm install -g @deepfirstsearch/agent-pay-mcp   # or skip this and use `npx -y @deepfirstsearch/agent-pay-mcp` below
mkdir mock && cd mock && npm init -y >/dev/null && npm install @deepfirstsearch/agent-pay
node --input-type=module -e '
import { startMockServer } from "@deepfirstsearch/agent-pay/testing";
const m = await startMockServer({ "/data": { price: 10000n, payTo: "0x1111111111111111111111111111111111111111", body: "{\"ok\":true}" } });
console.log("origin:", m.url);'

让它保持运行。在 offline.json 中使用打印出来的 origin：{ "network": "eip155:84532", "merchants": [{ "origin": "<printed origin>", "payTo": "0x1111111111111111111111111111111111111111", "price": "0.01", "maxPerTx": "0.05", "maxSpend": "0.50" }] }。然后使用 AGENT_PAY_BURNER_SEED=0x$(openssl rand -hex 32) agent-pay-mcp ./offline.json 启动服务（若未全局安装：AGENT_PAY_BURNER_SEED=0x$(openssl rand -hex 32) npx -y @deepfirstsearch/agent-pay-mcp ./offline.json），或将其添加到你的 MCP 客户端，然后对 <printed origin>/data 调用 paid_fetch。模拟商家会在本地验证签名，因此付款方无需资金。

5 分钟看它运行（Base Sepolia）

sdk/examples/demo-merchant.ts 是一个运行在 Base Sepolia 上的小型 x402 API，包含一个正常路由（/premium，0.01 USDC）和一个恶意路由（/malicious：其 402 响应要求向攻击者地址支付 5 USDC，响应正文还包含提示词注入）。

cd sdk && MERCHANT=0xYourMerchantAddress npx tsx examples/demo-merchant.ts

将配置中的商家指向 http://127.0.0.1:4021，并使用该 payTo，然后让你的 Agent 获取 /premium 和 /malicious。预期结果：第一个请求会完成付款，并在链上结算；第二个请求会在签署任何内容之前被拒绝（“payTo … is not the merchant's registered address”）。

配置参考

字段	含义
network	eip155:84532（Base Sepolia）或 eip155:8453（Base）
rpcUrl	该网络的可选 RPC URL（用于金库充值和余额读取）；默认使用 viem 的公共 RPC
vault, tranche	为每位商户的付款方充值的 Agent Safe 金库，以及充值金额
merchants[].origin, payTo	可以向谁付款，以及付款唯一可以发往的地址
merchants[].intentId	此商户的所有者签名预算（意图），由 owner budget 打印；设置 vault 时，每位商户都必须提供此项
merchants[].label	可选的显示名称（最多 80 个字符），由 list_merchants 显示
merchants[].price, tolerancePct	每次调用的预期价格；超过 price × (1 + tolerance) 的费用将被拒绝
merchants[].maxPerTx, maxSpend	每次调用的硬性上限，以及每个计划周期内每位商户的上限
merchants[].maxTimeoutSeconds	此商户可请求的最长授权时限，范围为 10 至 86400 s（默认 300 s）。只有该商户可使用更长的时限。
merchants[].x402Versions	此商户可接受付款的 x402 版本，默认为 [2]。对于仍使用 x402 v1 的商户（例如 Heurist Mesh），请设置为 [1, 2]。
confirmOnChain	默认为 true。当商户回执缺失或无法读取时，会通过链上（经由 rpcUrl）查询 USDC，确认付款是否已执行，而不是重新发送。CoinMarketCap、JustaName 和 Glim 等使用非标准回执的商户需要此项。仅在该失败路径中使用。
planWindowHours	计划在启动时根据此文件确定，并在每个周期从此文件续订
periodBudget	每个周期内所有商户的总预算：{ "amount": "1.00", "hours": 24 }
approvalAbove	超过此金额的付款将被拒绝（此服务没有模型无法访问的审批渠道）
sessionHasSensitiveData	如果 Agent 还可以读取私有数据，则每笔付款都需要人工参与（双重规则），因此所有付款都会被拒绝
auditLog	以哈希链保护的每项决策 JSONL 日志
maxResponseChars	返回给模型的响应正文最长字符数（默认 20000，最大 1000000）；更长的正文会被截断并注明
allowPrivateNetwork	默认为 false。设置为 true 后，paid_fetch 可以访问 http:// URL，以及此文件中未列为商户的环回、私有、链路本地或 CGNAT 主机

未知键会被拒绝，因此拼写错误（approvalabove）会导致服务停止，而不是静默丢弃某项限制。

从 0.2.0 起，每个经过测试的商户都能通过 MCP 正常工作：对于使用 v1 的商户（Heurist Mesh），请设置 x402Versions: [1, 2]；对于使用非标准回执的商户（CoinMarketCap、JustaName、Glim），请保持启用 confirmOnChain。如果没有金库，服务会在启动时打印每位商户的付款方地址，方便你知道要向哪个地址充值。

付款遭拒时，会返回错误结果 Payment refused by policy: …。从 0.1.8 起，只要捆绑的 @deepfirstsearch/agent-pay 版本为 0.8.0 或更高，文本就会包含拒绝的稳定代码及应对方法，例如 Payment refused by policy [price_changed → ask the owner]: …（代码列表见 SDK README 中的 “Refusal codes”）。拦截结果也会包含代码（Payment blocked [settlement_pending → …]: …；还包括 settled_not_delivered、rate_limited、kill_switch），并提供额外操作 resend_same：再次使用相同 URL 调用 paid_fetch，SDK 会重新发送同一份已签名授权，而不会重新签署。 paid_fetch 会获取模型请求的任何公开 https URL；只有支付才会限制为配置中的商户。来自未注册源站的非 402 响应会作为数据返回（并标记为不可信），因此应像对待提供给模型的任何获取工具一样谨慎处理。除非某个主机是配置中的商户，或者你设置了 allowPrivateNetwork，否则会拒绝环回、私有、链路本地或 CGNAT 地址（或会解析到这些地址的主机）、localhost 名称和纯 http；重定向只会返回，不会跟随。策略拒绝之外的错误（例如 RPC 故障，其消息可能包含你的 rpcUrl）会以固定文本形式传给模型；详细信息会写入服务的 stderr。

开发

npm ci && npm run typecheck && npm test   # tests drive the server through an MCP client against a mock x402 merchant