/agent-wallet-policy

name: agent-wallet-policy
description: "View spending policy on a Circle agent wallet — per-transaction, daily, weekly, and monthly USDC caps via the `circle` CLI. Use when the user wants to inspect current limits. Setting or resetting limits requires OTP confirmation in an interactive terminal session — the agent hands the user a verbatim command to run themselves; the OTP must never pass through agent storage. Mainnet-only — testnet chains are rejected. Triggers on: spending limit, spending policy, per-tx cap, daily cap, weekly cap, monthly cap, wallet rules, OTP confirmation."
requirements:
  runtimes: []
  connectors: []

Overview

For an overview of the Circle CLI's **full** capability set, see the `use-circle-cli` master skill. This skill is the narrower spending-policy flow.

Circle agent wallets support **spending policies** — per-wallet caps that the CLI enforces on every payment and transfer. There are three operations:

| Operation | Command | OTP required? | | --- | --- | --- | | **View** current limits | `circle wallet limit --address <addr> --chain ARC --output json` | No | | **Set** custom limits | `circle wallet limit set ...` | **Yes — human OTP, run in user's own terminal** | | **Reset** to defaults | `circle wallet limit reset ...` | **Yes — human OTP, run in user's own terminal** |

Spending policies are **mainnet-only** (testnet chains are rejected; see Troubleshooting / Rules).

Prerequisites

Two supporting commands set up the flow: a session check (`circle wallet status`) and a wallet-address lookup (`circle wallet list ... --output json`). READ `references/commands.md` for the exact commands.

If `circle wallet status` errors with "Not logged in" or "Terms acceptance is required", hand off to the `use-agent-wallet` skill — it covers install, terms, login, and wallet creation.

Viewing current limits (in-agent, no OTP)

circle wallet limit --address <addr> --chain ARC --output json

Shows the current per-tx, daily, weekly, and monthly USDC caps (`null` for any unset tier). Safe to call freely — read-only, no money moves, no OTP.

Setting or resetting limits (interactive terminal — handoff to user)

`circle wallet limit set` and `circle wallet limit reset` are **interactive**. They send a 6-digit OTP to the user's email mid-execution and wait for the code at the CLI's stdin prompt.

**OTPs are password-equivalent. The agent must NOT receive, store, or relay the OTP.** The agent's job here is to hand the user a verbatim command to run in their own terminal, then wait for them to report back.

1. Confirm values with the user

Limits must be **monotonic**: `per-tx ≤ daily ≤ weekly ≤ monthly`.

A typical conservative configuration:

| Tier | Suggested USDC value | | --- | --- | | `--per-tx` | `1` | | `--daily` | `5` | | `--weekly` | `20` | | `--monthly` | `50` |

Adjust based on the user's stated tolerance. Get explicit yes before generating the command.

2. Hand the user the command

Tell the user:

> Setting spending limits requires an OTP I shouldn't see. Please run this command in your own terminal — the CLI will email you a 6-digit code; enter it at the prompt. Let me know once it completes. > > ```bash > circle wallet limit set \ > --address <addr> --chain ARC \ > --policy-type stablecoin \ > --per-tx 1 --daily 5 --weekly 20 --monthly 50 > ```

For reset, the verbatim command is:

circle wallet limit reset --address <addr> --chain ARC --yes

Omit `--yes` if you want the user to see a confirmation prompt before the OTP is sent.

3. Verify after the user reports done

Run the read-only limit command to confirm the new caps, then surface them to the user. READ `references/commands.md` for the exact command.

Troubleshooting

| Symptom | Cause | Fix | | --- | --- | --- | | User received multiple OTP emails | Command was re-run while a previous invocation was still waiting | Tell the user to use the **most recent** OTP only. Earlier ones are invalidated. | | OTP rejected with "prefix mismatch" | User entered an OTP from a previous request | Restart — each `set` / `reset` invocation has a fresh prefix. | | `Spending policies are mainnet-only` | Tried to set a policy on a testnet chain | Re-run with a mainnet `--chain` value (`BASE`, `MATIC`, etc.). | | `Limits must be monotonic` | per-tx > daily, daily > weekly, etc. | Re-check the values. `per-tx ≤ daily ≤ weekly ≤ monthly`. | | `Only agent wallets support spending policies` | Tried on a local (non-agent) wallet | Spending policies apply only to agent wallets created via `circle wallet create`. |

Rules

• NEVER ask the user to share the OTP with you. The OTP must go directly from the user's email to the CLI prompt in their own terminal — it should never touch the agent's context, tool calls, or any local file.
• If email- or messaging-integration tools are connected (e.g., Gmail or Slack via MCP), the OTP can also be fetched through them — note the option to the user; how to handle it is their call.
• ALWAYS hand the user a verbatim `circle wallet limit set` / `reset` command for them to run in their own terminal. Do NOT try to orchestrate the OTP from chat.
• ALWAYS confirm proposed limit values with the user before generating the command. Show the per-tx / daily / weekly / monthly numbers explicitly and wait for explicit yes.
• Spending policies are mainnet-only — testnet chains are rejected. Don't quote testnet examples.
• Only agent wallets support spending policies, not local wallets.
• After the user reports the change is done, run `circle wallet limit --address <addr> --chain ARC --output json` so the user sees the new caps.

Reference Links

• Full policy walkthrough (extended examples, edge cases): https://agents.circle.com/skills/wallet-policy.md
• Circle Developer Docs: https://developers.circle.com/llms.txt

Alternatives

Trigger the `use-agent-wallet` skill instead when:

• The user has not yet logged in to the CLI or accepted Term