ConceptsPolicies

Policies

A policy is the set of spending rules stored in each wallet. The contract checks it on every payment, before any USDC moves. Only the wallet owner can change it, with setPolicy.

In the hosted app, a policy is shown as a doctrine.

The rules

FieldMeaning
perTxCapThe most the agent can send in one payment.
daily24hCapThe most it can send in one day.
monthlyCapThe most it can send in one 30-day period. 0 means no monthly limit.
escalationThresholdPayments above this amount wait for approval. Set it equal to perTxCap to never ask for approval.
allowedCategoriesWhich vendor categories the agent may pay, as a bitmask (bit 0 = API … bit 4 = OTHER).
requireAllowlistIf on, the agent can only pay vendors the owner has approved.
freezeOnBlockedVendorIf on, trying to pay a blocked vendor freezes the wallet instead of only refusing.

All amounts are USDC with 6 decimals: 100_000_000 is 100 USDC.

The order of checks

The wallet first refuses a zero amount or a frozen wallet. Then the policy engine checks the rules in this fixed order and stops at the first one that applies:

  1. Blocked vendor: freeze if freezeOnBlockedVendor is on, otherwise deny.
  2. Vendor not on the allowlist when one is required: deny.
  3. Vendor category not allowed: deny.
  4. Above the per-payment cap: deny.
  5. Above the vendor’s own per-payment cap: deny.
  6. Above the daily cap: deny.
  7. Above the monthly cap: deny.
  8. Above the escalation threshold: escalate (hold for approval).
  9. Otherwise: allow.

Limits are checked before approval, so approvers can never push a payment past a cap.

Time windows

The daily and monthly limits use fixed windows counted from the Unix epoch in UTC, not rolling ones. The daily counter resets at 00:00 UTC. The monthly counter resets every 30 days on the same fixed schedule, not on the first of the calendar month.

Check before you send

simulate asks the contract for its decision without sending a transaction. The wallet checks again when the real payment arrives, so a simulation is advice, not a promise.

const decision = await arc.simulate({ to: vendor, amount: 1_250_000_000n })
console.log(decision.verdict, decision.reason)