Spend Guard

Spend Guard

为使用 USDC 支付 API 费用的 AI Agent 提供消费防护。

这是在 Arc 测试网上使用 x402 exact 运行的真实演示（node demo/agent.js --arc-x402 --dashboard），经过剪辑并加速：防护机制在签署任何内容之前，拒绝了价格飙升至原价 40 倍的请求和被替换收款地址的请求；点击仪表板上的 Approve 后，才会发出 $0.30 的付款。

Agent 已开始通过 HTTP 402 按调用付费：服务端以 402 Payment Required 响应并提供价格，Agent 付款后获取数据（x402 协议）。能够付款的 Agent 也可能被诱导付款：例如提示词注入、重试循环，或提高价格、替换收款地址的付费墙。Spend Guard 位于 Agent 与资金之间。每笔付款都会根据预算、收款方允许列表和端点的常规价格进行检查；任何异常情况都会等待人工审批。所有检查都在任何 USDC 转出、任何授权签署之前完成。它可通过普通 USDC 转账、x402 exact（EIP-3009）和 Circle Gateway 微支付在 Circle 的 Arc 测试网上付款，也可使用本地密钥付款，并支持在 NEAR 测试网上通过 NEAR 付款。Circle 开发者控制的钱包支付通道仅经过离线测试。Claude 和其他 MCP 客户端可将其用作 MCP 服务。

状态：仅限测试网，未经审计。已发布到 npm，名称为 @vulinh1704/spend-guard，并收录于官方 MCP Registry，名称为 io.github.vulinh1704/spend-guard。采用 MIT 许可。

快速开始（1 分钟，无需密钥）

需要 git 和 Node 22.22.2 或更高版本。无需密钥或钱包：付款均为模拟付款，安装完成后不会有任何内容离开你的计算机。

git clone https://github.com/vulinh1704/spend-guard
cd spend-guard
npm ci
node demo/agent.js                       # a scripted agent against a demo paywall that turns bad
node demo/agent.js --dashboard           # the same run, paced, with the live page on http://localhost:4400

使用 --dashboard 时，可在运行期间打开 http://localhost:4400。$0.30 的 /report 会在此等待你选择 Approve 或 Deny；如果 120 秒内没有回应，则会拒绝。页面会一直运行，直到你按下 Ctrl+C。如果 4400 端口已被占用，演示会选择一个空闲端口并显示出来；可通过 DASHBOARD_PORT 指定其他端口。

它能拦截什么

演示用的付费墙在前几次调用时表现正常，随后便开始作恶。/quotes 将价格提高 40 倍，/maps 则要求付款到一个相似地址。/report 始终如实，但费用超过了 Agent 无需询问即可支付的金额。以下是离线演示，运行 node demo/agent.js：

✓ paid $0.01   /weather  {"city":"Hanoi","tempC":29,"sky":"clear"}
✓ paid $0.02   /news     {"headlines":["Stablecoin volume hits a record","New L2 opens its testnet"]}
✓ paid $0.01   /quotes   {"NEAR":2.5,"BCH":450}
✓ paid $0.01   /quotes   {"NEAR":2.5,"BCH":450}
✓ paid $0.01   /quotes   {"NEAR":2.5,"BCH":450}
✗ denied /quotes   $0.40 is 40x the usual $0.01 for 127.0.0.1:33955/quotes; $0.40 is above the $0.25 that needs your approval
✓ paid $0.015  /maps     {"route":"Hoan Kiem → My Dinh","km":11.2}
✓ paid $0.015  /maps     {"route":"Hoan Kiem → My Dinh","km":11.2}
✗ denied /maps     127.0.0.1:33955 asked to be paid at rnaps.paywall.testnet, which is not one of its known addresses
✓ paid $0.01   /weather  {"city":"Hanoi","tempC":29,"sky":"clear"}
  ? asks you: $0.30 is above the $0.25 that needs your approval → no
✗ declined /report   $0.30 is above the $0.25 that needs your approval

spent today $0.10 of $1.00; 3 payments stopped

同一演示在 Arc 测试网上使用 x402 exact 运行（node demo/agent.js --arc-x402，2026 年 10 月 31 日），并以真实测试网 USDC 付款。Agent 只负责签署。付费墙在链上结算每笔签名并支付 Gas，因此 Agent 的余额恰好减少了其支付的 $0.10：

agent 0xBbc0B612C19beA521D2eA1Ad7dfEe91D23753244 · Arc testnet (USDC) · x402 v2 exact, EIP-3009
✓ paid $0.01   /weather  … https://testnet.arcscan.app/tx/0x92414aea1d896cd7ebd032c85ca32a84764d743931e61f4474a92f434a61fae3
✗ denied /maps     … asked to be paid at 0xF870cC7D7c258Cc856197fB6C3C819AD6Bb324b5, which is not one of its known addresses
agent wallet $17.999436 → $17.899436 USDC (-$0.10)

规则	可拦截的情况
每笔付款限额、每日预算，以及每项服务的单次调用上限	价格过高的调用；循环调用的总额不会超过每日预算
每项服务的收款方允许列表	付费墙开始要求将款项支付到其他地址
根据端点的常规价格检测价格飙升	突然涨价 5 倍、40 倍或 1000 倍
超过阈值的付款，或针对未知服务的付款，需要人工审批	大额付款；向策略未列出的主机付款，例如被注入页面引导 Agent 访问的主机
同一时间只处理一个决策（使用账本文件时，跨进程也适用）	并行工具调用争抢每日预算

无论是否付款，每项决策都会连同原因一起记录。规则及其具体提示信息见 docs/policy.md。

工作原理

agent ── payingFetch(url) ──► paywall: 402 + offer (PAYMENT-REQUIRED)
              │
              ▼
            Guard ── policy: budgets, payees, usual price ── ledger
              │  └─ flagged? ask the person on the dashboard
              ▼
            Rail ── USDC transfer · EIP-3009 signature · Gateway authorization · Circle wallet
              │
payingFetch ──► paywall: PAYMENT-SIGNATURE ──► 200 + data + PAYMENT-RESPONSE (settlement)

防护机制会在支付通道转移资金或签署任何内容之前做出决策。需要签署的支付通道会使用防护机制批准的收款方和金额，而绝不会使用付费墙自身提供的数据；同时会固定签署所用的链和代币。更多信息见 docs/architecture.md。

支付渠道

支付渠道	Agent 如何付款	状态
Arc USDC 转账（--arc）	使用 Agent 的密钥执行 ERC-20 transfer。支付墙会检查收据中的 USDC Transfer 事件。	在 Arc 测试网上可用，例如这笔付款。
Arc 上的 x402 exact（--arc-x402）	为 USDC 签署 EIP-3009 transferWithAuthorization。支付墙会验证并结算付款，同时支付 Gas 费。	在 Arc 测试网上可用。演示支付墙使用自己的结算器。
Circle Gateway（--gateway）	使用存入 Circle Gateway Wallet 的 USDC 签署 Gateway 授权。Circle 会批量结算付款。	在 Arc 测试网上可用，无需 Circle 账户或 API 密钥。此前一次运行中的付款记录在一笔批量交易中。
Circle Wallets	由 Circle 开发者控制的钱包转账或签署，因此 Agent 的进程中不会存放私钥。	已通过 Circle SDK 离线测试。尚未在 Circle 上运行，因为需要你的 Circle 账户（设置说明）。
NEAR 测试网（--near）	原生 NEAR 转账。	在 NEAR 测试网上可用。
Mock	不发生资金转移。	用于测试和离线演示。
Bitcoin Cash、Concordium		计划中。

各支付渠道的详细信息见docs/rails.md。

x402 v2 和 exact 方案（EIP-3009）

payingFetch 支持 x402 v2。它会从 PAYMENT-REQUIRED 标头读取付款报价，也仍会读取 v1 JSON 请求体。对于指定了该代币 EIP-712 域的 Arc USDC exact 报价，Agent 会签署 transferWithAuthorization，而不会发送交易。签名即付款，因此防护机制会先作出决策，并在签名时将其计为已支出。每个签名仅针对获准的收款方和金额，使用全新的随机 nonce，且有效期最长为 120 秒。对于其他链的报价（同一密钥也适用于 Arc 主网）、其他代币的报价，或 Permit2 和托管流程的报价，系统会在签署任何内容之前拒绝，并说明原因。

node scripts/arc-testnet-wallet.js       # agent key and demo payees in .env; fund the agent at https://faucet.circle.com (Arc Testnet)
node scripts/arc-facilitator.js          # the demo paywall's settling key, topped up with a little test USDC for gas
node demo/agent.js --arc-x402 --dashboard

Circle Gateway 微额付款

Agent 只需向 Circle Gateway Wallet 存入一次 USDC。之后，每次调用都通过链下授权完成：无需 Gas 费，也无需为每次调用发送交易，因此一笔 0.01 美元的调用只需支付 0.01 美元。几分钟后，Circle 会在 Arc 上批量结算这些付款。Gateway 授权至少有效 7 天，因此防护机制会在签署前作出决策。该支付渠道也不会签署超过存款可覆盖金额的付款，并会将已签署但尚未结算的金额计入。

node scripts/gateway-deposit.js 1        # approve and deposit 1 test USDC (two Arc transactions)
node demo/agent.js --gateway --dashboard # nanopayments to an x402 v2 seller that settles each one with Circle
node scripts/gateway-status.js           # Gateway balance, and each payment's batch transaction on Arc

Circle Wallets

使用 CircleWalletRail 时，密钥由 Circle 持有（MPC），并会在收到请求时进行签署。Agent 的进程中有测试网 API 密钥和实体密钥，但没有私钥；Spend Guard 仍会在请求 Circle 发送或签署任何付款之前检查每笔付款。防护机制批准后，Circle 自己的控制措施（托管、筛查、DENIED）仍然适用。docs/circle-wallets.md 介绍了设置方法（需要你自己的 Circle 开发者账户），以及这两个控制层如何配合运作。

在 Claude 或任何 MCP 客户端中使用

spend-guard mcp 通过 stdio 提供守卫，并为 MCP 客户端提供三个工具：

• pay_and_fetch 获取 URL，并通过守卫支付其 x402 付费墙。
• spending_status 和 spending_policy 是只读视图，可查看预算、近期付款和规则。

没有用于批准付款或更改策略的工具。策略标记的付款会在仪表板上等待你处理。如果 55 秒内没有答复，付款就会被拒绝；如果客户端取消调用，则不会付款。

配置写入 .mcp.json（Claude Code，项目范围）或 claude_desktop_config.json（Claude Desktop）。Cursor 和其他客户端使用相同的 mcpServers 结构。

从 npm 安装。默认的 mock 支付通道不会实际付款，因此可以安全地先试用：

{
  "mcpServers": {
    "spend-guard": {
      "command": "npx",
      "args": ["-y", "@vulinh1704/spend-guard", "mcp"],
      "env": { "SPEND_GUARD_POLICY": "/abs/path/policy.json" }
    }
  }
}

mock 支付通道会假装在 near-testnet 上付款，因此策略必须允许该网络：列出 "networks": ["near-testnet"]，或者省略 networks，这样服务就会允许其运行的支付通道所支持的网络。只列出 Arc 网络的策略不会允许 mock 支付通道付款。如需实际付款，请从克隆仓库运行演示付费墙 node demo/paid-api.js，然后让 Agent 获取 http://localhost:4402/weather。[`demo/mcp-policy.json`](demo/mcp-policy.json) 是一个了解其收款方的 mock 策略。

从克隆仓库运行，并用于会实际付款的支付通道。Node 使用 --env-file 从 .env 读取密钥，而 npx 无法传递此参数，因此密钥不会放在客户端配置中：

{
  "mcpServers": {
    "spend-guard": {
      "command": "node",
      "args": ["--env-file=/abs/path/spend-guard/.env", "/abs/path/spend-guard/bin/spend-guard.js", "mcp"],
      "env": { "SPEND_GUARD_POLICY": "/abs/path/policy.json", "SPEND_GUARD_RAILS": "arc,gateway" }
    }
  }
}

或者在 Claude Code 中运行：claude mcp add spend-guard -- npx -y @vulinh1704/spend-guard mcp；如果从克隆仓库运行，则运行 claude mcp add spend-guard --env SPEND_GUARD_POLICY=/abs/path/policy.json --env SPEND_GUARD_RAILS=arc -- node --env-file=/abs/path/spend-guard/.env /abs/path/spend-guard/bin/spend-guard.js mcp

下面是适用于 arc,gateway 配置的 policy.json。它的 networks 是这两个支付通道实际付款所用的网络；如果使用其他支付通道，请列出它们对应的网络，或省略 networks：

{ "networks": ["arc-testnet", "arc-testnet-gateway"], "dailyUsd": 1, "perPaymentUsd": 0.5, "askAboveUsd": 0.25, "spikeRatio": 5, "unknownService": "ask",
  "services": { "api.example.com": { "payTo": ["0xPayeeAddress"], "maxUsd": 0.1 } } }

变量	含义
SPEND_GUARD_RAILS	mock（默认，不实际付款）、near、arc、gateway，或逗号分隔的列表
SPEND_GUARD_POLICY	策略文件。如果未指定，每个服务都视为未知，因此每笔付款都需要你确认。如果文件中未设置 networks，则允许运行的支付通道所支持的网络。
SPEND_GUARD_LEDGER	决策记录文件，启动时会重新读取，因此重启后会保留当天的支出。使用同一个文件的服务共享同一预算。默认值为 ~/.spend-guard/ledger.jsonl；设为 off 则仅保存在内存中。
SPEND_GUARD_DASHBOARD_PORT	仪表板在 127.0.0.1 上使用的端口，默认值为 4400；设为 0 则自动选择空闲端口。如果该端口已被占用，则使用空闲端口，并在 stderr 中显示端口号。设为 off 表示不启用仪表板，且会拒绝被标记的付款。
SPEND_GUARD_APPROVAL_TIMEOUT	付款等待你处理的秒数（默认值为 55）。请同时调高此值和客户端的工具超时时间。
SPEND_GUARD_MOCK_NETWORK	mock 支付通道假装付款所用的网络（默认值为 near-testnet，演示付费墙会请求此网络）
ARC_PRIVATE_KEY	供 arc 和 gateway 使用。仅限测试网密钥。
NEAR_ACCOUNT_ID、NEAR_PRIVATE_KEY	供 near 使用。仅限测试网密钥。

密钥通过 --env-file 从 .env 读取，绝不要放进客户端配置中。运行实际付款的 Agent 时，不要提供 shell 或浏览器工具：否则它可能会读取 .env，或自行点击“批准”。

无需模型即可试用：node scripts/mcp-demo.js（mock），或 node scripts/mcp-demo.js --arc（在 Arc 上使用真实测试 USDC）。

在仪表板上审批

仪表板是一个实时页面，地址为 http://localhost:4400。它显示预算、每项决策及其原因和交易链接，以及每笔被标记支付的 Approve 或 Deny 卡片和倒计时。它仅监听 127.0.0.1，且只响应 localhost 名称；审批也只能通过页面本身提交（相同 Origin、回环对端、JSON 正文）。它提供浅色和深色主题，并采用响应式布局（它仅响应 localhost，因此通过手机审批已列入路线图）；测试使用 Mantis（scripts/check-dashboard.sh：在移动端和桌面端的浅色及深色模式下均为 0 个错误、0 个警告）。

node demo/agent.js --dashboard           # the offline demo, paced for watching; /report waits for your answer

安装和测试

npm ci
npm test                                 # 189 tests, offline: no network, no keys
node demo/agent.js                       # offline demo, mock payments

你需要 Node 22.22.2 或更高版本，因为 near-api-js 7 有此要求（Circle 的 SDK 需要 Node 22）。测试网演示会从 .env 读取密钥；该文件已被 git 忽略，设置脚本会将密钥写入其中。测试网代币没有价值。切勿让脚本指向主网。

演示	所需条件
node demo/agent.js --arc	node scripts/arc-testnet-wallet.js，然后从 https://faucet.circle.com 获取测试 USDC
node demo/agent.js --arc-x402	上述条件，另加 node scripts/arc-facilitator.js
node demo/agent.js --gateway	上述条件，另加 node scripts/gateway-deposit.js 1
node demo/agent.js --near	node scripts/near-testnet-account.js 和 node scripts/near-demo-payees.js

在任意命令后添加 --dashboard，即可在实时页面上查看。

将其用作库

import { Guard, payingFetch } from '@vulinh1704/spend-guard';
import { ArcRail } from '@vulinh1704/spend-guard/rails/arc';
import { GatewayRail } from '@vulinh1704/spend-guard/rails/gateway';

const guard = new Guard({
  policy: {
    networks: ['arc-testnet', 'arc-testnet-gateway'],
    dailyUsd: 5, perPaymentUsd: 1, askAboveUsd: 0.25, spikeRatio: 5, unknownService: 'ask',
    services: { 'api.example.com': { payTo: ['0xPayeeAddress'], maxUsd: 0.5 } },
  },
  rails: [new ArcRail({ privateKey: process.env.ARC_PRIVATE_KEY }), new GatewayRail({ privateKey: process.env.ARC_PRIVATE_KEY })],
  approve: async (intent, verdict) => askTheHuman(verdict.reasons), // never the model
});

const res = await payingFetch(guard, 'https://api.example.com/data'); // pays a 402 through the guard

当守卫拒绝请求时，payingFetch 会抛出 GuardRefused，并附上拒绝原因。仪表板和 MCP 服务使用的 approve 队列是 Approvals。使用 npm install @vulinh1704/spend-guard 安装（需要 Node 22.22.2 或更高版本）。

文档

• 架构：逐步介绍一笔付费请求。
• 策略参考：每个字段、规则和消息。
• 支付通道：各个支付通道、付费墙会检查哪些内容，以及如何编写支付通道。
• Circle 钱包：设置方法，以及 Circle 的控制措施与守卫的控制措施对照。
• 威胁模型：它能阻止什么、无法阻止什么，以及已知的不足。
• 发布：发布到 npm 和 MCP Registry。
• CHANGELOG、CONTRIBUTING、SECURITY。

路线图

尚未实现。计划按以下顺序构建：

1. 接入 Circle Wallets。 使用开发者账户在 Circle 测试网上运行支付通道，然后将其提供给 MCP 服务，让 Agent 从密钥始终留在 Circle 的钱包付款。
2. 通过 Circle 结算，而不是使用我自己的结算器。 在支持的情况下，使用 Circle 的 facilitator 在 Arc 上处理 x402 exact，并通过同一笔存款在更多链上使用 Gateway。
3. 弥补已知不足。 将 gas 计入预算，在重启后保留 Gateway 未结算计数，并接受智能钱包付款方（ERC-1271），例如 Circle SCA 钱包，其 gas 可由 Circle 的 Gas Station 赞助。
4. 为团队提供托管式策略和审批页面。
5. 主网， 仅在守卫和支付通道经过外部审查后启用。

许可证

MIT