Spend Guard

Spend Guard

USDC で API の料金を支払う AI エージェントのための支出ガードです。

Arc テストネット上で x402 exact を使った実際の実行例（node demo/agent.js --arc-x402 --dashboard）を編集し、再生速度を上げています。ガードは署名が行われる前に、価格の 40 倍への急騰と支払い先アドレスの差し替えを拒否します。また、0.30 ドルの支払いは、人がダッシュボードで「承認」をクリックした後にのみ実行されます。

エージェントは HTTP 402 を介して、呼び出しごとに料金を支払い始めています。サーバーが価格とともに 402 Payment Required を返し、エージェントが支払うとデータを受け取ります（x402 プロトコル）。支払いができるエージェントは、支払いをするよう仕向けられることもあります。プロンプトインジェクション、リトライループ、価格を引き上げたり支払い先アドレスを差し替えたりするペイウォールなどです。Spend Guard はエージェントとその資金の間に位置します。すべての支払いを予算、支払い先の許可リスト、エンドポイントの通常価格と照合し、通常と異なるものは人による承認を待ちます。これらはすべて、USDC が送金される前、そして承認に署名が行われる前に実行されます。Circle の Arc テストネットでは、通常の USDC 送金、x402 exact（EIP-3009）、Circle Gateway のナノペイメントで支払います。ローカルキーを使い、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 を開いてください。/report への 0.30 ドルの支払いは、「承認」または「拒否」を選ぶまでそこで保留され、120 秒以内に回答がなければ拒否されます。Ctrl+C を押すまでページは開いたままです。4400 番ポートが使用中の場合、デモは空いているポートを使い、その番号を表示します。別のポートを指定するには DASHBOARD_PORT を設定してください。

防止できること

デモのペイウォールは数回の呼び出しには適切に応答しますが、その後、不正な動作を始めます。/quotes は価格を 40 倍に引き上げ、/maps はよく似た別のアドレスへの支払いを要求します。/report は正直ですが、確認なしでエージェントが支払える金額を超えています。これはオフラインデモで、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 で支払われました。エージェントが行ったのは署名だけです。ペイウォールが各署名をオンチェーンで決済し、ガス代を支払ったため、エージェントの残高は使った 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)

ルール	検知できること
支払いごとの上限、1 日あたりの予算、サービスごとの呼び出し上限	価格が高すぎる呼び出し。ループによる支払いの合計は 1 日あたりの予算で止まります
サービスごとの支払い先許可リスト	ペイウォールが別の場所への支払いを求め始めること
エンドポイントの通常価格を基準とした価格急騰	突然の 5 倍、40 倍、1000 倍への値上げ
しきい値を超える場合、または不明なサービスの場合の人による承認	高額な支払い、ポリシーに記載されていないホストへの支払い（注入されたページがエージェントに示したホストなど）
一度に 1 件ずつの判定（台帳ファイルがあれば、プロセス間でも適用）	並列のツール呼び出しが 1 日あたりの予算を奪い合うこと

支払いの有無にかかわらず、すべての判定は理由とともに記録されます。ルールとその正確なメッセージについては、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 を参照してください。

Rails

レール	エージェントの支払い方法	ステータス
Arc USDC transfer (--arc)	エージェントのキーから ERC-20 transfer を実行します。ペイウォールはレシートの USDC Transfer イベントを確認します。	Arc テストネットで動作します。たとえば、この支払いをご覧ください。
Arc 上の x402 exact（--arc-x402）	USDC の EIP-3009 transferWithAuthorization に署名します。ペイウォールが検証して決済し、ガス代を支払います。	Arc テストネットで動作します。デモのペイウォールは独自のセトラーです。
Circle Gateway（--gateway）	Circle の Gateway Wallet に一度預け入れた USDC に対する Gateway オーソリゼーションに署名します。Circle がまとめて決済します。	Circle アカウントや API キーがなくても、Arc テストネットで動作します。以前の実行では、支払いは1 件のバッチトランザクションにまとめられました。
Circle Wallets	Circle が管理するウォレットが送金または署名するため、エージェントのプロセスに秘密鍵を置く必要がありません。	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 ボディも引き続き読み取ります。Arc 上の USDC を使い、トークンの EIP-712 ドメインが指定された exact オファーの場合、エージェントは 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 のナノペイメント

エージェントは USDC を Circle の Gateway Wallet に一度預け入れます。その後の各呼び出しはオフチェーンのオーソリゼーションとなるため、呼び出しごとのガス代もトランザクションも発生せず、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）、求めに応じて署名します。エージェントのプロセスにはテストネットの API キーとエンティティシークレットがありますが、秘密鍵はありません。また、Circle に送金や署名を依頼する前に、Spend Guard がすべての支払いを引き続き確認します。ガードが許可した後も、Circle 独自の管理機能（カストディ、スクリーニング、DENIED）が適用されます。docs/circle-wallets.mdでは、独自の Circle 開発者アカウントが必要なセットアップと、2 つのレイヤーの連携方法について説明しています。

Claude または任意の MCP クライアントから使用する

spend-guard mcp は stdio 経由でガードを提供し、MCP クライアントに次の 3 つのツールを公開します。

• 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 で実行し、エージェントに http://localhost:4402/weather を取得するよう依頼してください。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 には、この 2 つのレールが支払いを行うネットワークを指定します。ほかのレールを使う場合は、それらのネットワークを指定するか、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 から読み込まれ、クライアントの設定には決して記述しません。支払いを行うエージェントには、シェルツールやブラウザツールを使用させないでください。これらのツールがあると、.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

near-api-js 7 が Node 22.22.2 以降を必要とするため、Node 22.22.2 以降が必要です（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 をスローします。Approvals は、ダッシュボードと MCP サーバーが approve に使用するキューです。npm install @vulinh1704/spend-guard でインストールしてください（Node 22.22.2 以降）。

ドキュメント

• アーキテクチャ：有料リクエストを段階的に説明します。
• ポリシーリファレンス：すべてのフィールド、ルール、メッセージを説明します。
• 決済レール：各決済レール、ペイウォールによる確認内容、実装方法を説明します。
• Circle Wallets：セットアップと、ガードの制御と並べて確認できる Circle の制御を説明します。
• 脅威モデル：阻止できること、阻止できないこと、既知の不足点を説明します。
• 公開：npm と MCP Registry へのリリース方法を説明します。
• CHANGELOG、CONTRIBUTING、SECURITY。

ロードマップ

まだ実装されていません。次の順番で実装する予定です。

1. Circle Wallets の実稼働対応。 開発者アカウントで Circle のテストネットに対して決済レールを実行し、MCP サーバーからも利用できるようにします。これにより、エージェントはキーが Circle の外に出ないウォレットから支払えます。
2. 独自の決済処理ではなく、Circle 経由で決済を確定する。 利用可能な場合は、Arc 上の x402 exact に Circle のファシリテーターを使用し、同じデポジットからより多くのチェーンで Gateway を使えるようにします。
3. 既知の不足点を解消する。 予算にガス代を含め、再起動後も Gateway の未決済件数を維持し、Circle の Gas Station がガス代を負担できる Circle SCA ウォレットなどのスマートウォレット支払者（ERC-1271）を受け付けます。
4. チーム向けのホスト型ポリシー・承認ページ。
5. メインネット対応。 ガードと決済レールの外部レビューを受けてから実施します。

ライセンス

MIT