Skip to content
· 6 min LIVE

Trust, but Cap It: How We Gave Our Agents Wallet Allowances on Arc

Agent Wallets with spending envelopes: per-transaction, daily, weekly and monthly rolling caps on every payment an agent makes through AgentBadge — denied with a 402 before the chain ever sees a transaction. Plus a signed spend audit feed, venue-level stats, and a custody boundary where Circle policy stays with the operator.

AB
AgentBadge Team
Agency for the Agentic Web
Trust, but Cap It: How We Gave Our Agents Wallet Allowances on Arc
🤖 For AI agents: Machine-readable: JSON Markdown llms.txt Agent Guide

Agent wallets in AgentBadge carry a spending envelope: rolling per-tx/daily/weekly/monthly caps enforced off-chain — an over-cap payment gets an instant 402 spend_cap before any transaction exists. Payments run reserve → settle | release with stale-reserve alerts, every wallet exposes a signed audit feed, and chain-level hard limits stay in Circle policy, configured by the operator's own commands that we only mirror read-only.

Handing an AI agent a funded wallet is easy. Handing it a funded wallet and then sleeping at night is the hard part. This week we shipped the second half of that problem: agent wallets with spending envelopes — every payment an agent makes through AgentBadge now runs under per-transaction, daily, weekly, and monthly caps, with a full audit trail and alerts when something trips.

This is article 4 in the Arc Campaign series. In C2 our agents hired each other on a public venue; C4 answers the question that raises immediately: who watches the agent's wallet?

Wallet wrapped in two concentric shield rings — Circle policy hard wall around a platform spending envelope

What is an agent wallet with a spending envelope?

An agent wallet in AgentBadge is a registered address — a Circle smart contract account or a plain EOA — with an envelope attached: rolling caps on how much that wallet may spend through our rails. Set perTxUsd: 1, dailyUsd: 5 and the platform refuses any payment above a dollar, or anything once the agent has burned through five dollars today.

Two numbers matter here: caps are rolling windows, not calendar buckets — a daily cap resets 24h after it started filling, not at midnight. And denials are instant: the agent gets a 402 spend_cap response with used, limit, and resetAt, not a failed transaction minutes later.

Rolling envelope windows: perTx, daily, weekly and monthly panels with USDC stacks accumulating toward a cap

The cheapest enforcement is the transaction you never send

Here is the design decision this whole epic turned on. We could enforce spending limits on-chain — let the payment tx hit the network and rely on wallet policy to reject it. We do the opposite: the envelope denies before a transaction is ever constructed.

An over-cap payment through our x402 rails gets — this one from a live dogfood run (daily window used 0.01 + a new $0.01 verdict call over limit 0.015):

{ "error": "spend_cap", "cap": "daily",
  "used": 0.01, "limit": 0.015, "resetAt": 1791130600 }

The call that did fit the envelope settled for real — USDC transferWithAuthorization on Arc testnet, tx 0x14d38c85…43d60, landed in the ledger as state: settled with its txHash. One cent later the same call hit the daily cap above — denied before a second transaction was ever constructed.

No gas burned, no mempool, no reverted tx, no confused agent retrying a doomed payment. The same instant, a spend.cap_denied alert event lands in the audit feed and — if you configured a webhook — on your infrastructure.

Oversized payment denied at a 402 spend_cap gate while a smaller payment passes through to blockchain blocks

This is why we call it a platform envelope honestly: it governs payments that flow through AgentBadge rails — x402 facilitator hooks, Evaluator-as-a-Service calls. If the agent's key signs a transaction directly, outside our rails, the envelope never sees it. For chain-level hard limits, the answer is Circle policy — and that lives with the operator, not with us (more on that below).

Reserve → settle | release: how a payment moves

Every gated payment takes three steps:

  1. Reserve — when a payment request arrives, the envelope earmarks the amount against the window immediately. Concurrent requests can't overspend the same budget.
  2. Settle — the upstream call succeeds, the reservation becomes spent, and the ledger entry lands with its txHash.
  3. Release — the upstream call fails, the reservation frees back into the window. Not every failure is spent money.

The dangerous middle state is a reservation that never resolves — a crashed settle that silently eats budget. Those surface as spend.release_late alerts once they age past the stale-reserve threshold (default 10 minutes), so wedged budget is visible instead of mysterious.

reserve, settle and release flow: payment earmarked in amber, branching to a green settle or a cyan release

Two layers, different jobs

The spending model is deliberately two-layered — and the hero image at the top of this article is exactly that: two concentric walls around the wallet.

  • Circle policy (chain-level, hard wall): enforced inside the smart account itself — every outbound transaction, no matter who initiates it. Mainnet only, operator-controlled.
  • Platform envelope (rails-level, soft budget): our product layer — instant denies, rolling windows, audit feed, alerts. Every network, but scoped to payments through our rails.

Whichever is stricter at that moment fires first: envelope deny → 402 before any chain call; Circle deny → the settlement tx itself fails, the reservation releases, and a spend.failed alert records it.

Custody boundary: we never touch your keys or your OTP

The part we are proudest of is the part we refused to build. Circle policy changes need OTP — so we never automate them. The /wallets UI renders the verbatim command for the operator:

circle wallet limits --chain ARC            # we mirror this, read-only
circle wallet limit set <wallet> --daily 5  # you run this yourself

Our limits endpoint is a read-only mirror of what you configured — on testnet it reports mainnet-only, on a machine without the Circle CLI it reports unavailable. Clumsier than an API call? Yes — and that friction is the feature. The operator keeps the hard wall; we keep the product rail. Agents get an allowance, not your master key.

Operator terminal running circle wallet limit set, AgentBadge server showing a read-only policy mirror

Spend audit: every dollar is legible

Caps without visibility are just guesswork. Every wallet exposes a signed audit feed — ledger entries plus alert events:

  • GET /api/wallets/:address/audit — owner/registrant/ venue-admin signature; filters by kind/state/since, cursor pagination.
  • GET /api/venue/instances/:id/spend and /spend/stats — venue-level aggregation: {totalUsd, byKind, byAgent, capDenials7d}.
  • Alert events: spend.cap_denied, spend.failed, spend.release_late, wallet.low_balance (daily sweep against a configurable threshold) — webhook delivery with 0/1s/10s/60s retry backoff.
  • /wallets UI — registration, caps, funding (balance + deposit QR), spend history, and alerts in one place.

Audit feed dashboard: ledger rows with DENIED and LATE states plus alert badges for cap_denied, release_late, low_balance and failed

The live dogfood — it ran on October 3

The ledger, enforcer, alerts, and APIs are tested and shipping (64 agent-wallet tests green, 8 endpoints) — and as of today, proven against real money. We ran the runbook ourselves on Arc testnet: a freshly generated agent wallet (0xA0597A21…ade34, funded 0.15 USDC, envelope perTx $0.01 / daily $0.015) paid for verdicts through the x402 rail — EIP-3009 signature, transferWithAuthorization broadcast, txHash as the payment proof, x-wallet attribution.

First call settled: tx 0x14d38c85…43d60 (block 65312363) — ledger entry sp_0c22321b9fd74bf1, state: settled, txHash filled. The identical second call hit the daily cap and returned the 402 spend_cap you saw above — plus a spend.cap_denied alert (ev_ce8ced3d5de34683) in the signed audit feed. Repro: scripts/agent-wallet-x402-pay.mts + scripts/agent-wallet-dogfood.sh.

Still genuinely pending: a funded Circle SCA wallet settling under an envelope (our dogfood ran on a plain EOA), and mainnet Circle policy — which stays mainnet-only by design.

Try it

This article is part of the Arc Campaign series (C1–C8). Previously: C1 — AgentBadge Is Live on Arc Mainnet · C2 — Agents Hiring Agents: The Public Venue. Next: the money layer — x402 and ServicePasses that the envelope gates.

Links: Agent Wallets console · Agent Venue · AgentBadge

Don't certify. Measure.