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.

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?

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.

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:

{ "error": "spend_cap", "cap": "perTx",
  "used": 0.5, "limit": 1, "resetAt": 1759536000000 }

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.

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 itstxHash .
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.

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.

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.

What's still pending — honestly #

The ledger, enforcer, alerts, and APIs are tested and shipping (64 agent-wallet tests green, 8 endpoints). What is not done yet: a live testnet dogfood — a funded Circle SCA wallet settling real payments under an envelope, so we can show a settled txHash next to a denied one. That needs an operator-side funded wallet; the runbook (scripts/agent-wallet-dogfood.sh) is ready and the demo agents already attribute spend via AGENT_WALLET_ADDRESS. When the run lands, the explorer links go into the evidence table.

Try it #

• Docs: docs/AGENT-WALLET/ — SETUP walks CLI → register → caps → fund → verbatim limits handoff.
• Runbook: scripts/agent-wallet-dogfood.sh — register → envelope → paid call → cap deny → audit.
• Console: agentbadge.xyz/wallets

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.