Spend Guard

Spend Guard

A spending guard for AI agents that pay for APIs in USDC.

A real run on Arc testnet with x402 exact (node demo/agent.js --arc-x402 --dashboard), trimmed and sped up: the guard refuses a 40x price spike and a swapped payout address before anything is signed, and a $0.30 payment goes out only after a person clicks Approve on the dashboard.

Agents are starting to pay per call over HTTP 402: the server answers 402 Payment Required with a price, the agent pays and gets the data (the x402 protocol). An agent that can pay can also be talked into paying: a prompt injection, a retry loop, or a paywall that raises its price or swaps its payout address. Spend Guard sits between the agent and its money. Every payment is checked against budgets, a payee allowlist and the endpoint's usual price, and anything unusual waits for a person to approve it. All of this happens before any USDC leaves and before any authorization is signed. It pays on Circle's Arc testnet by plain USDC transfer, by x402 exact (EIP-3009) and by Circle Gateway nanopayments, from a local key, and in NEAR on NEAR testnet. A rail for Circle developer-controlled wallets is tested offline only. Claude and other MCP clients can use it as an MCP server.

Status: testnet only, not audited. On npm as @vulinh1704/spend-guard and in the official MCP Registry as io.github.vulinh1704/spend-guard. MIT licensed.

Quickstart (1 minute, no keys)

You need git and Node 22.22.2 or later. No keys and no wallet: the payments are mocked, and nothing leaves your machine after the install.

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

With --dashboard, open http://localhost:4400 while it runs. The $0.30 /report waits there for Approve or Deny, and is declined after 120 seconds without an answer. The page stays up until you press Ctrl+C. If 4400 is taken, the demo takes a free port and prints it; DASHBOARD_PORT picks another.

What it stops

The demo paywall behaves for a few calls and then turns bad. /quotes raises its price 40x, and /maps asks to be paid at a look-alike address. /report stays honest but costs more than the agent may pay without asking. This is the offline demo, 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

The same run on Arc testnet with x402 exact (node demo/agent.js --arc-x402, 31 Oct 2026) paid in real test USDC. The agent only signed. The paywall settled each signature on chain and paid the gas, so the agent's balance fell by exactly the $0.10 it spent:

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)

Every decision, paid or not, is recorded with its reasons. The rules and their exact messages are in docs/policy.md.

How it works

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)

The guard decides before a rail moves money or signs anything. A rail that signs uses the payee and amount the guard approved, never the paywall's own numbers, and it pins the chain and token it signs for. More in docs/architecture.md.

Rails

Details for each rail are in docs/rails.md.

x402 v2 and the exact scheme (EIP-3009)

payingFetch speaks x402 v2. It reads the offer from the PAYMENT-REQUIRED header, and still reads v1 JSON bodies. For an exact offer in USDC on Arc that names the token's EIP-712 domain, the agent signs a transferWithAuthorization and sends no transaction. The signature is the payment, so the guard decides first and counts it as spent when it is signed. Each signature is for the approved payee and amount only, has a fresh random nonce, and is valid for at most 120 seconds. Offers for another chain (the same key works on Arc mainnet), another token, or Permit2 and escrow flows are refused before anything is signed, with the reason.

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 nanopayments

The agent deposits USDC into Circle's Gateway Wallet once. After that each call is an off-chain authorization: no gas and no transaction per call, so a $0.01 call costs $0.01. Circle settles the payments on Arc in batches a few minutes later. A Gateway authorization stays valid for at least 7 days, so the guard decides before it is signed. The rail also signs nothing the deposit can't cover, counting what is signed but not settled yet.

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

With CircleWalletRail, Circle holds the key (MPC) and signs when asked. The agent's process has a testnet API key and an entity secret, but no private key, and Spend Guard still checks every payment before Circle is asked to send or sign. Circle's own controls (custody, screening, DENIED) still apply after the guard says yes. docs/circle-wallets.md explains the setup, which needs your own Circle developer account, and how the two layers fit together.

Use it from Claude or any MCP client

spend-guard mcp serves the guard over stdio and gives an MCP client three tools:

• pay_and_fetch fetches a URL and pays its x402 paywall through the guard.
• spending_status and spending_policy are read-only views of the budget, recent payments and the rules.

There is no tool to approve a payment or to change the policy. Payments the policy flags wait for you on the dashboard. They are declined after 55 seconds without an answer, and a call the client cancels never pays.

The config goes in .mcp.json (Claude Code, project scope) or claude_desktop_config.json (Claude Desktop). Cursor and other clients take the same mcpServers shape.

From npm. The default mock rail pays nothing, so this is a safe first try:

{

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

The mock rail pretends to pay on near-testnet, so this policy must allow that network: list "networks": ["near-testnet"], or leave networks out and the server allows the networks of the rails it runs. A policy that lists only Arc networks leaves the mock rail nothing it may pay. To have something to pay, run the demo paywall from a clone, node demo/paid-api.js, and ask the agent to fetch http://localhost:4402/weather. demo/mcp-policy.json is a mock policy that knows its payees.

From a clone, and for the rails that pay. Node reads the keys from .env with --env-file, which npx can't pass on, so they stay out of the client's config:

{

"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" } } } }

Or in Claude Code: claude mcp add spend-guard -- npx -y @vulinh1704/spend-guard mcp, or from a clone 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

A policy.json for the arc,gateway config. Its networks are the ones those two rails pay on; with ot