Policy Engine

Configurable spending limits, allowlists, and approval thresholds for agent wallets.

Overview

Every wallet has a policy that governs what transactions are allowed. Policies are evaluated before any transaction reaches the network. If a transaction violates any policy rule, it is rejected with a descriptive error code and recovery hint.

Default policy

New wallets are created with these defaults:

Rule	Default value
`per_tx_limit`	100 USDC
`daily_limit`	500 USDC
`max_tx_per_day`	20
`allowed_tokens`	Chain-dependent. Ethereum: `ETH`, `USDC`, `USDT`; Polygon: `POL`, `USDC`, `USDC.e`, `USDT`; Solana: `SOL`, `USDC`, `USDT`
`allowed_addresses`	`[]` (any address)
`require_approval_above`	`null` (disabled)

Evaluation order

When a write operation is submitted (aw send, aw predict buy), the policy engine evaluates rules in this order:

Token allowlist — is the token in allowed_tokens?
Address allowlist — is the destination in allowed_addresses? (empty = allow all)
Per-transaction limit — does the amount exceed per_tx_limit?
Daily limit — would total spend today exceed daily_limit?
Transaction count — has max_tx_per_day been reached?
Approval threshold — does the amount exceed require_approval_above?

If any check fails, the transaction is rejected with exit code 1 and the corresponding error code (e.g., DAILY_LIMIT_EXCEEDED).

Sell exemption

aw predict sell operations skip spending limits (daily_limit, per_tx_limit, require_approval_above) because selling liquidates an existing position rather than spending new funds. Rate limits (max_tx_per_day) and allowlists are still enforced.

Micro-unit precision

All limit values are stored and compared as integers in micro-units (1 USDC = 1,000,000 micro-units) to avoid floating-point errors. The CLI handles conversion automatically — you pass human-readable values like 100 and the engine stores 100000000.

View current policy

aw policy show bot --json

{
  "ok": true,
  "data": {
    "name": "bot",
    "address": "0x4f3A...6a1",
    "policy": {
      "daily_limit": 500,
      "per_tx_limit": 100,
      "max_tx_per_day": 20,
      "allowed_tokens": ["ETH", "USDC", "USDT"],
      "allowed_addresses": [],
      "require_approval_above": null
    }
  }
}

Update policy

Set one or more policy fields. Unspecified fields remain unchanged.

aw policy set bot \
  --limit-daily 1000 \
  --limit-per-tx 200 \
  --max-tx-per-day 50 \
  --allowed-tokens POL,USDC,USDC.e \
  --allowed-addresses 0xAAA...,0xBBB... \
  --require-approval-above 500

Flag	Description
`--limit-daily <n>`	Daily spending limit
`--limit-per-tx <n>`	Per-transaction spending limit
`--max-tx-per-day <n>`	Maximum transactions per day
`--allowed-tokens <list>`	Comma-separated token symbols (e.g., `POL,USDC,USDC.e`)
`--allowed-addresses <list>`	Comma-separated address allowlist
`--require-approval-above <n>`	Require human approval above this amount (`0` to clear)

Aliases

The policy commands are also available as wallet subcommands:

aw wallet settings <wallet> = aw policy show <wallet>
aw wallet settings-set <wallet> = aw policy set <wallet>

Daily reset

Daily limits (daily_limit, max_tx_per_day) reset at UTC midnight automatically.