A Paying Client That Cannot Overspend: Mandatory Caps for x402 Buyer Agents

Description and use

A client without spending limits can drain a wallet; the @agentbadge/circle-payments library enforces mandatory payment caps and session budgets, rejecting requests before signing to prevent overspending.

Problem

A paying client without spending limits can cause runaway loops that drain a wallet, leading to unintended charges.

Outcome

The mandatory caps and session budget enforcement prevented three failed payment attempts from draining the wallet, with zero on-chain settlement on rejected requests.

Workflow

• Create a paying client with caps and signer
• Call an API endpoint that returns a 402 with payment requirements
• Client validates accepts list and checks per-call cap, network, and session budget
• If any check fails, client returns a refusal without signing
• If all checks pass, client signs the payment payload and retries the request
• On successful settlement, spend is recorded and persisted via onSpend hook

Evidence

Three times, three different ways: once for the per-call cap, once for the network allowlist, once for the session budget.

Source

createPayingClient throws a TypeError the moment you omit PaymentCaps, before a single request leaves the process.

Source

refused field=amount value="300000": amount 300000 exceeds per-call cap 10000 (atomic units) refused field=network value="eip155:84532": network "eip155:84532" not in allowedNetworks refused: Session budget exhausted: spent 0 + requested 300000 > budget 10000 (atomic units)

Source