Limits and controls

Spending controls let you define how an Agent Wallet should be used without giving an AI agent unrestricted access to the customer’s funds. Controls are configured on individual wallets, and a wallet can be frozen on its own without affecting the customer’s other wallets.

Wallet balances are held in USDC, while spending limits are in USD. USDC and USD are treated one to one.

Wallet controls

Every control is enforced by the payment flow. A payment that would go over any of them is not refused: it is held for customer approval, and the agent receives a pending_approval result rather than a successful payment. The payment continues once the customer approves it.

Reading and changing controls

The controls live on the wallet’s spending policy. Read it with Get wallet policies and change it with Update a wallet policy. Only the fields you send change, so raising daily leaves monthly as it was.

{ "config": { "daily": 150 } }

A policy can also be paused with { "status": "paused" }. A paused policy keeps its values but is not applied until it is set back to active.

Get policy usage returns how much has been spent against session, daily and monthly, how much remains, and when each window resets. Usage is counted the same way limits are enforced, so remaining is what the agent can spend before a payment is held.

Zero and omitted controls

A control set to 0 is disabled rather than interpreted as a spending limit of zero. To stop a wallet spending entirely, freeze it instead.

An omitted control is also different from explicitly setting a control to zero. When a wallet is created without limits, its controls are inherited from the controls already configured for the customer. Your integration should therefore treat omitted, zero and positive values as distinct configurations.

Freezing a wallet

Freeze a wallet stops the agent spending from it. Its payments are refused outright with no approval route, and payments already held for approval cannot be approved until it is unfrozen. Deposits still credit, and its limits and usage are untouched. Unfreeze a wallet lets the agent spend again.

A frozen wallet reports status: "frozen" with frozen_at and frozen_reason. You can list only frozen wallets with GET /v1/customers/{id}/wallets?status=frozen, and the wallet.frozen and wallet.unfrozen events tell you when the state changes.

When the agent tries to pay from a frozen wallet, it receives:

{ "status": "refused", "reason": "wallet_frozen", "message": "This wallet is frozen by its owner." }

Wallet and customer controls

Wallet limits and freezes apply to the individual wallet they are configured on. A customer with separate Travel and Office wallets can have different spending configurations for each, and freezing Travel leaves Office able to pay.

Customer-level restrictions apply more broadly. A blocked destination, or a freeze set on the customer from the dashboard, affects spending across all of the customer’s wallets.

Example configurations

The following configurations illustrate how different wallets can carry different controls. The amounts are examples rather than recommended limits, and you should choose values appropriate for your product and customers.

{
  "per_payment": 50,
  "session": 50,
  "daily": 100,
  "monthly": 500,
  "approve_above": 100
}

{
  "per_payment": 500,
  "session": 0,
  "daily": 1000,
  "monthly": 3000,
  "approve_above": 750
}

Related