Back to Details

agent-wallet-policy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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:
OperationCommandOTP required?
View current limits
circle wallet limit --address <addr> --chain BASE --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 return an error if you try to set a policy.
如需了解Circle CLI的完整功能集，请查看
use-circle-cli
主技能。本技能是更细分的支出政策流程。
Circle Agent钱包支持支出政策——CLI对每笔支付和转账强制执行的单钱包限额。共有三种操作：
操作命令是否需要OTP？
查看当前限额
circle wallet limit --address <addr> --chain BASE --output json
否
设置自定义限额
circle wallet limit set ...
是——需人工输入OTP，在用户自己的终端中执行
重置为默认值
circle wallet limit reset ...
是——需人工输入OTP，在用户自己的终端中执行
支出政策仅支持主网。若尝试在测试网链上设置政策，会返回错误。

Prerequisites

前提条件

bash
undefined
bash
undefined

Confirm session is good

确认会话状态正常

circle wallet status
circle wallet status

Get the wallet address

获取钱包地址

circle wallet list --chain BASE --type agent --output json

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.
circle wallet list --chain BASE --type agent --output json

如果`circle wallet status`返回“未登录”或“需要接受条款”错误，请转接至`use-agent-wallet`技能——该技能涵盖安装、条款接受、登录及钱包创建流程。

Viewing current limits (in-agent, no OTP)

查看当前限额（在Agent内执行，无需OTP）

bash
circle wallet limit --address <addr> --chain BASE --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.
bash
circle wallet limit --address <addr> --chain BASE --output json
显示当前每笔交易、每日、每周及每月的USDC限额（未设置的层级显示为
null
）。可自由调用——仅为只读操作，不会涉及资金变动，无需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.
circle wallet limit set
和
circle wallet limit reset
为交互式命令。执行过程中会向用户邮箱发送6位OTP，并在CLI的标准输入提示符处等待用户输入验证码。
OTP等同于密码。Agent绝对不能接收、存储或转发OTP。 Agent的职责是向用户提供完整命令，供其在自己的终端中执行，然后等待用户反馈执行结果。

Step 1 — Confirm values with the user

步骤1——与用户确认限额数值

Limits must be monotonic: 
per-tx ≤ daily ≤ weekly ≤ monthly
.
A typical conservative configuration:
TierSuggested 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.
限额必须单调递增：
每笔交易限额 ≤ 每日限额 ≤ 每周限额 ≤ 每月限额
。
典型的保守配置示例：
层级建议USDC数值
--per-tx
1
--daily
5
--weekly
20
--monthly
50
可根据用户所述的风险承受能力调整数值。生成命令前需获得用户明确同意。

Step 2 — Hand the user the command

步骤2——向用户提供命令

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 BASE \
  --policy-type stablecoin \
  --per-tx 1 --daily 5 --weekly 20 --monthly 50
For reset, the verbatim command is:
bash
circle wallet limit reset --address <addr> --chain BASE --yes
Omit 
--yes
if you want the user to see a confirmation prompt before the OTP is sent.
告知用户：
设置支出限额需要OTP，而我不应查看该验证码。请在您自己的终端中运行以下命令——CLI会向您的邮箱发送6位验证码，请在提示符处输入。完成后请告知我。
bash
circle wallet limit set \
  --address <addr> --chain BASE \
  --policy-type stablecoin \
  --per-tx 1 --daily 5 --weekly 20 --monthly 50
对于重置操作，完整命令为：
bash
circle wallet limit reset --address <addr> --chain BASE --yes
如果希望用户在发送OTP前看到确认提示，可省略
--yes
参数。

Step 3 — Verify after the user reports done

步骤3——用户反馈完成后验证

bash
circle wallet limit --address <addr> --chain BASE --output json
Confirms the new caps. Surface them to the user.
bash
circle wallet limit --address <addr> --chain BASE --output json
确认新的限额，并告知用户。

Troubleshooting

故障排查

SymptomCauseFix
User received multiple OTP emailsCommand was re-run while a previous invocation was still waitingTell 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 requestRestart — each 
set
/ 
reset
invocation has a fresh prefix.
Spending policies are mainnet-only
Tried to set a policy on a testnet chainRe-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) walletSpending policies apply only to agent wallets created via 
circle wallet create
.
症状原因解决方法
用户收到多封OTP邮件在前一次调用仍处于等待状态时重新执行了命令告知用户仅使用最新的OTP，之前的验证码已失效。
OTP被拒绝并提示“前缀不匹配”用户输入了来自前一次请求的OTP重新执行命令——每次
set
/
reset
调用都会生成新的前缀。
Spending policies are mainnet-only
尝试在测试网链上设置政策使用主网
--chain
参数重新执行（如
BASE
、
MATIC
等）。
Limits must be monotonic
每笔交易限额>每日限额、每日限额>每周限额等重新检查数值，确保
每笔交易限额 ≤ 每日限额 ≤ 每周限额 ≤ 每月限额
。
Only agent wallets support spending policies
尝试在本地（非Agent）钱包上设置政策支出政策仅适用于通过
circle wallet create
创建的Agent钱包。

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 BASE --output json
    so the user sees the new caps.
  • 绝对不要要求用户向您分享OTP。OTP必须直接从用户邮箱发送到其自己终端的CLI提示符——绝对不能接触Agent的上下文、工具调用或任何本地文件。
  • 如果已连接邮箱或消息集成工具（如通过MCP连接的Gmail或Slack），用户也可通过这些工具获取OTP——可向用户说明该选项，具体由用户决定如何处理。
  • 必须始终向用户提供完整的
    circle wallet limit set
    /
    reset
    命令，供其在自己的终端中执行。切勿尝试通过聊天协调OTP流程。
  • 生成命令前必须始终与用户确认拟议的限额数值。明确告知每笔交易/每日/每周/每月的数值，并等待用户明确同意。
  • 支出政策仅支持主网——测试网链会被拒绝。请勿引用测试网示例。
  • 支出政策仅适用于Agent钱包，不适用于本地钱包。
  • 用户反馈更改完成后，执行
    circle wallet limit --address <addr> --chain BASE --output json
    ，让用户查看新的限额。

Reference Links

参考链接

Alternatives

替代方案

Trigger the 
use-agent-wallet
skill instead when:
  • The user has not yet logged in to the CLI or accepted Terms.
  • circle wallet status
    errors with "Not logged in" or "Terms acceptance is required".
  • The user is asking about wallet setup, login, or session state — not policy.
Trigger the 
pay-via-agent-wallet
skill instead when:
  • The user wants to call, pay for, or use a paid x402 service.
  • Limits are already set and the user is ready to spend.
Trigger the 
fund-agent-wallet
skill instead when:
  • The user wants to add USDC before setting limits.
  • The user mentions deposit, fiat on-ramp, fiat purchase, QR-code transfer, or Gateway deposit.
DISCLAIMER: This skill is provided "as is" without warranties, is subject to the Circle Developer Terms, and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository README.
当出现以下情况时，应触发
use-agent-wallet
技能：
  • 用户尚未登录CLI或未接受条款。
  • circle wallet status
    返回“未登录”或“需要接受条款”错误。
  • 用户询问钱包设置、登录或会话状态——而非政策相关问题。
当出现以下情况时，应触发
pay-via-agent-wallet
技能：
  • 用户想要调用、支付或使用付费x402服务。
  • 限额已设置完成，用户准备进行支付。
当出现以下情况时，应触发
fund-agent-wallet
技能：
  • 用户想要在设置限额前添加USDC。
  • 用户提及存款、法币入金、法币购买、二维码转账或Gateway存款。
DISCLAIMER: This skill is provided "as is" without warranties, is subject to the Circle Developer Terms, and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository README.