use-agent-wallet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

The Circle CLI (

@circle-fin/cli

, command

circle

) provides a programmatic agent wallet — a non-custodial USDC wallet designed for AI agents to authenticate, hold balances, and pay for paid x402 services on Circle's marketplace. This skill is the bootstrap surface for that wallet: install check, terms acceptance, login, wallet creation, and status inspection. After bootstrap completes, downstream operations (paying for services, funding, spending policy) hand off to dedicated skills.

For an overview of the Circle CLI's full capability set — bridging, smart contract execution, transaction inspection, and more — see the

use-circle-cli

master skill. This skill is the narrower bootstrap/identity surface.

This skill is for the CLI agent-wallet flow.

Circle CLI（

@circle-fin/cli

，命令为

circle

）提供了一个程序化Agent钱包——这是一个非托管式USDC钱包，专为AI Agent设计，用于在Circle市场中进行身份验证、存储余额以及支付付费x402服务。本技能是该钱包的初始化入口，涵盖安装检查、服务条款接受、登录、钱包创建和状态检查。初始化完成后，下游操作（如支付服务、充值、消费策略）将移交至专用技能处理。

如需了解Circle CLI的完整功能集——包括跨链桥接、智能合约执行、交易查询等，请查看

use-circle-cli

主技能。本技能仅专注于钱包的初始化与身份验证环节。

本技能适用于CLI端的Agent钱包流程。

Prerequisites / Setup

前置条件/设置

Step 1 — Verify the CLI is installed

步骤1 — 验证CLI已安装

bash

which circle || command -v circle
circle --version

If not installed:

bash

npm install -g @circle-fin/cli

circle --version

also surfaces any update notice from Circle's server when a newer CLI version is available (server-driven, never blocks). If a notice prints, suggest the user update with

npm install -g @circle-fin/cli@latest

— but only when it is contextually relevant (e.g., at the start of a session or when a command produces unexpected output). Do not run version checks on every routine command.

bash

which circle || command -v circle
circle --version

若未安装：

bash

npm install -g @circle-fin/cli

当有新版本CLI可用时，

circle --version

还会显示Circle服务器推送的更新通知（由服务器驱动，不会阻塞操作）。若显示通知，建议用户使用

npm install -g @circle-fin/cli@latest

更新——但仅在上下文相关时提出（例如会话开始时或命令产生意外输出时）。不要在每次常规命令执行时都进行版本检查。

Step 2 — Check session status

步骤2 — 检查会话状态

Always check whether the user is already logged in before attempting login.

bash

circle wallet status

Possible outcomes:

Logged in — output shows email, wallet type (
```
agent
```
), and session expiry. Tell the user "You're already logged in as
```
<email>
```
. Continue with this session?" and skip to Step 4.

Not logged in — output is

Error: Not logged in. Run 'circle wallet login <email> --type agent' to authenticate.

Proceed to Step 3.

Terms not accepted — output is
```
Error: Circle CLI Terms acceptance is required before use.
```
Stop and complete the Terms-of-Use Gate below before proceeding. Do NOT run
```
circle terms accept
```
without explicit user consent.

在尝试登录前，务必先检查用户是否已登录。

bash

circle wallet status

可能的结果：

已登录 — 输出显示邮箱、钱包类型（
```
agent
```
）和会话过期时间。告知用户“您已以
```
<email>
```
身份登录。是否继续使用此会话？”，并跳转至步骤4。

未登录 — 输出为

Error: Not logged in. Run 'circle wallet login <email> --type agent' to authenticate.

，继续执行步骤3。

未接受服务条款 — 输出为
```
Error: Circle CLI Terms acceptance is required before use.
```
，先完成下方的服务条款确认环节，之后再继续。未经用户明确同意，不得执行
```
circle terms accept
```
。

Step 3 — Login (email + OTP, two-step non-interactive flow)

步骤3 — 登录（邮箱+OTP，两步非交互式流程）

Circle's CLI supports a two-step OTP login designed for AI agents and other non-interactive contexts.

Circle CLI支持专为AI Agent和其他非交互式场景设计的两步OTP登录流程。

3a. Initialize login (request OTP)

3a. 初始化登录（请求OTP）

Ask the user for their email address (do NOT guess or hardcode). Then:

bash

circle wallet login <user-email> --type agent --init

--type agent

defaults to

agent

so it can be omitted, but pass it explicitly here for consistency with the error text in Step 2.

Expected output:

OTP code sent to user@example.com
Please run: circle wallet login --request <request-id> --otp <code>

Parse the request ID from the output. It is a UUID; you will need it for the next step. Request IDs expire after 10 minutes and are single-use.

向用户索要邮箱地址（不得猜测或硬编码）。然后执行：

bash

circle wallet login <user-email> --type agent --init

--type agent

默认值为

agent

，可以省略，但为了与步骤2中的错误提示保持一致，此处显式传入该参数。

预期输出：

OTP code sent to user@example.com
Please run: circle wallet login --request <request-id> --otp <code>

从输出中解析出请求ID，它是一个UUID，后续步骤会用到。请求ID有效期为10分钟，且仅可使用一次。

3b. Complete login (verify OTP)

3b. 完成登录（验证OTP）

Tell the user: "An OTP code has been sent to your email. Please share it (format: ABC-123456 or just the 6 digits)." 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 share it is their call. Then:

bash

circle wallet login --type agent --request <request-id> --otp <user-otp>

OTP format notes:

Full form:
```
ABC-123456
```
Bare digits:
```
123456
```
— the CLI prepends the cached prefix automatically
The CLI validates the prefix matches what was sent (anti-phishing)

If successful, output is:

Logged in as user@example.com

Tell the user "Successfully logged in" and continue. If the call fails (

Invalid or expired request ID

OTP prefix mismatch

Invalid OTP

), restart from 3a to generate a fresh OTP — do NOT loop without telling the user.

告知用户：“OTP验证码已发送至您的邮箱，请提供验证码（格式：ABC-123456或仅6位数字）。”若已连接邮箱或消息集成工具（如通过MCP连接的Gmail或Slack），也可通过这些工具获取OTP——向用户说明该选项，由用户决定如何提供验证码。然后执行：

bash

circle wallet login --type agent --request <request-id> --otp <user-otp>

OTP格式说明：

完整格式：
```
ABC-123456
```
纯数字：
```
123456
```
— CLI会自动添加缓存的前缀
CLI会验证前缀与发送的是否一致（防钓鱼）

登录成功后，输出为：

Logged in as user@example.com

告知用户“登录成功”并继续。若调用失败（如

Invalid or expired request ID

、

OTP prefix mismatch

、

Invalid OTP

），从3a步骤重新生成新的OTP——不得在未告知用户的情况下循环重试。

3c. Verify session

3c. 验证会话

bash

circle wallet status

Confirms the session and surfaces expiry. Proceed to Step 4.

bash

circle wallet status

确认会话状态并显示过期时间，继续执行步骤4。

Logging out / switching accounts

登出/切换账户

bash

circle wallet logout

Use only when the user explicitly asks to switch accounts.

bash

circle wallet logout

仅当用户明确要求切换账户时使用此命令。

Step 4 — Check or create the agent wallet

步骤4 — 检查或创建Agent钱包

The
--chain
flag is REQUIRED for
circle wallet list
and
circle wallet balance
. Use BASE as the default if the user hasn't specified a chain.

bash

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

If wallets already exist, save the address(es) for the next step.

If no agent wallets exist:

bash

circle wallet create --output json

Creates agent-controlled SCA wallets on each supported EVM chain. The JSON output is an array of

{ chain, address, ... }

objects — read the

address

field to save per-chain addresses for Step 5.

circle wallet list

和

circle wallet balance

命令必须传入

--chain

参数。**若用户未指定链，默认使用BASE链。

bash

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

若钱包已存在，保存地址用于下一步。

若不存在Agent钱包：

bash

circle wallet create --output json

该命令会在每个支持的EVM链上创建由Agent控制的SCA钱包。JSON输出是一个包含

{ chain, address, ... }

对象的数组——读取

address

字段，保存各链地址用于步骤5。

Step 5 — Check wallet balance

步骤5 — 检查钱包余额

Use the address(es) from Step 4:

bash

circle wallet balance --address <addr> --chain BASE --output json

If balance is 0 USDC and the user wants to pay for services, hand off to the

fund-agent-wallet

skill — it covers built-in fiat on-ramp purchase, direct address transfer with a QR code, and Gateway deposits.

If the user only wants to verify state (not pay yet), stop here. Bootstrap is complete.

使用步骤4中获取的地址：

bash

circle wallet balance --address <addr> --chain BASE --output json

若USDC余额为0且用户想要支付服务费用，移交至

fund-agent-wallet

技能处理——该技能涵盖内置法币入金购买、二维码直接转账和网关存款等功能。

若用户仅需验证状态（暂不支付），流程到此结束，初始化完成。

After bootstrap

初始化完成后

Once the wallet exists, the user's likely next move is to use it. The CLI exposes its own skill catalog —

circle skill list

shows what's installable,

circle skill info --name <skill>

shows trigger and frontmatter detail, and

circle skill install --tool <host> --name <skill>

installs one for the current host. Suggest natural follow-ups like funding, paid-service search, or setting a spending limit; prefer permissionless actions (balance, search) over money-moving ones until the user asks.

钱包创建完成后，用户接下来可能会使用它。CLI提供了自身的技能目录——

circle skill list

显示可安装的技能，

circle skill info --name <skill>

显示触发条件和详情，

circle skill install --tool <host> --name <skill>

为当前主机安装技能。建议用户进行后续操作，如充值、搜索付费服务或设置消费限额；在用户主动要求前，优先选择无需权限的操作（如查询余额、搜索服务），而非涉及资金转移的操作。

Terms-of-Use Gate

服务条款确认环节

The Circle CLI hard-gates every operational

circle wallet

command (including

circle wallet status

) until the user has accepted Circle's Terms of Use and Privacy Policy on this machine. The gate surfaces as:

By using the Circle CLI, you agree to:
  Terms of Use:    https://agents.circle.com/terms-of-use
  Privacy Policy:  https://www.circle.com/legal/privacy-policy

Error: Circle CLI Terms acceptance is required before use.
  Hint: Set CIRCLE_ACCEPT_TERMS=1 to accept in non-interactive shells (CI, scripts, sandboxed agents).

Run this section the first time the gate appears (typically during Step 2 or Step 3 above). After acceptance is recorded once, the gate is a no-op and this section is skipped on subsequent runs.

CRITICAL: The agent MUST show the Terms to the user and obtain explicit consent BEFORE running
circle terms accept
. The agent MUST NEVER accept Circle's Terms of Use or Privacy Policy on the user's behalf. The CLI's
CIRCLE_ACCEPT_TERMS=1
env-var hint is NOT a workaround the agent may take on its own — ignore it and use the consent flow below.

在用户接受Circle的服务条款和隐私政策之前，Circle CLI会阻止所有

circle wallet

操作命令（包括

circle wallet status

）。该限制会显示如下内容：

By using the Circle CLI, you agree to:
  Terms of Use:    https://agents.circle.com/terms-of-use
  Privacy Policy:  https://www.circle.com/legal/privacy-policy

Error: Circle CLI Terms acceptance is required before use.
  Hint: Set CIRCLE_ACCEPT_TERMS=1 to accept in non-interactive shells (CI, scripts, sandboxed agents).

首次出现该限制时（通常在步骤2或步骤3中）执行本环节。一旦记录用户已接受，后续运行时该限制将自动失效，本环节将被跳过。

重要提示：Agent必须向用户展示条款并获得明确同意后，方可执行
circle terms accept
。Agent绝不能代表用户接受Circle的服务条款或隐私政策，也绝不能自行使用CLI的
CIRCLE_ACCEPT_TERMS=1
环境变量提示作为变通方案——忽略该提示，使用下方的同意流程。

Read current acceptance status

查看当前接受状态

bash

circle terms show --output json

data.accepted

true

, the user has already accepted on this machine. Return to the step that triggered this section.

bash

circle terms show --output json

若

data.accepted

为

true

，说明用户已在本机接受条款，返回触发本环节的步骤。

Fetch the Terms info to present to the user

获取条款信息并展示给用户

When

data.accepted

false

bash

circle terms show --init --output json

The response includes

termsOfUseUrl

privacyPolicyUrl

, and

termsNotice

. Use the live values from this response when presenting the Terms — do NOT summarize, paraphrase, or hardcode them. They may change between Terms versions.

当

data.accepted

为

false

时：

bash

circle terms show --init --output json

响应包含

termsOfUseUrl

、

privacyPolicyUrl

和

termsNotice

。**展示条款时必须使用该响应中的实时值——不得总结、改写或硬编码。**条款版本更新时这些值可能会变化。

Show the Terms and request consent

展示条款并请求同意

Tell the user:

Circle CLI requires acceptance of its Terms of Use and Privacy Policy before I can run any wallet commands.
Terms of Use:
<termsOfUseUrl from the JSON response>
Privacy Policy:
<privacyPolicyUrl from the JSON response>
<termsNotice from the JSON response>
Please review both links. Do you accept these Terms and authorize me to record acceptance on your behalf? (yes/no)

Wait for an explicit yes/no. Ambiguous replies, silence, "ok" without context, or "go ahead" without referencing the Terms are NOT consent — ask again.

告知用户：

Circle CLI要求接受其服务条款和隐私政策后，才能执行任何钱包命令。
服务条款：
<JSON响应中的termsOfUseUrl>
隐私政策：
<JSON响应中的privacyPolicyUrl>
<JSON响应中的termsNotice>
请查看上述链接。您是否接受这些条款并授权我代表您记录接受状态？（是/否）

**等待用户明确的是/否回复。**模糊回复、沉默、无上下文的“好的”或未提及条款的“继续”均不视为同意——需再次询问。

After explicit consent only

仅在获得明确同意后执行

bash

circle terms accept --output json

When

data.acceptance.accepted

true

, the gate is cleared. Return to the step that triggered this section.

If the user later asks to revoke acceptance:

bash

circle terms reset

Run this only if the user explicitly asks to revoke. Do NOT suggest or execute a reset proactively.

bash

circle terms accept --output json

当

data.acceptance.accepted

为

true

时，限制解除，返回触发本环节的步骤。

若用户后续要求撤销接受：

bash

circle terms reset

仅当用户明确要求撤销时执行此命令，不得主动建议或执行重置操作。

Rules

规则

Security

安全

NEVER guess or hardcode the user's email address for agent wallet login.
OTP codes provided during an active authentication session are safe to handle — accept them in chat, use them immediately, do not retain or reuse afterward.
NEVER include real private keys, API keys, or other persistent secrets in skill files or persist them anywhere.
NEVER run
```
circle terms accept
```
without explicit user consent in the current session. The agent MUST NEVER accept Circle's Terms on the user's behalf, and MUST NEVER call
```
circle terms accept
```
automatically as part of error recovery, retries, or any flow the user has not explicitly approved.
ALWAYS show the live
```
termsOfUseUrl
```
,
```
privacyPolicyUrl
```
, and
```
termsNotice
```
returned by
```
circle terms show --init --output json
```
when prompting for consent. Do NOT summarize, paraphrase, or hardcode them.
If the user declines the Terms, stop the flow. Do not retry, work around the gate, or call
```
circle terms reset
```
/
```
circle terms accept
```
.

绝不能猜测或硬编码用户的邮箱地址用于Agent钱包登录。
主动认证会话中提供的OTP验证码可安全处理——在聊天中接收后立即使用，不得保留或重复使用。
绝不能在技能文件中包含真实私钥、API密钥或其他持久化机密，也不得在任何地方存储这些信息。
未经当前会话中用户的明确同意，绝不能执行
```
circle terms accept
```
。Agent绝不能代表用户接受Circle的条款，也绝不能在错误恢复、重试或任何用户未明确批准的流程中自动调用
```
circle terms accept
```
。
请求同意时，必须展示
```
circle terms show --init --output json
```
返回的实时
```
termsOfUseUrl
```
、
```
privacyPolicyUrl
```
和
```
termsNotice
```
。不得总结、改写或硬编码这些内容。
若用户拒绝条款，立即停止流程。不得重试、绕过限制或调用
```
circle terms reset
```
/
```
circle terms accept
```
。

Best practices

最佳实践

ALWAYS check
```
circle wallet status
```
before attempting login. Many session "failures" are actually just stale assumptions.
Parse and store the request ID from
```
circle wallet login --init
```
output — you'll need it for the OTP completion step.
Request IDs are single-use and expire after 10 minutes. If you see "Invalid or expired request ID", restart from
```
--init
```
.
For general CLI rules (
```
--output json
```
,
```
--chain
```
,
```
--help
```
-first, follow-up phrasing, confirmation defaults), see the
```
use-circle-cli
```
master skill's Rules section — they apply here too.

尝试登录前，务必检查
```
circle wallet status
```
。许多会话“失败”实际上只是过时的假设导致的。
解析并存储
```
circle wallet login --init
```
输出中的请求ID——完成OTP验证步骤需要用到它。
请求ID仅可使用一次，有效期为10分钟。若出现“Invalid or expired request ID”提示，从
```
--init
```
步骤重新开始。
关于通用CLI规则（如
```
--output json
```
、
```
--chain
```
、优先使用
```
--help
```
、后续话术、确认默认值等），请查看
```
use-circle-cli
```
主技能的规则部分——这些规则同样适用于本技能。

Reference Links

参考链接

Setup walkthrough (full bootstrap doc): https://agents.circle.com/skills/setup.md
Login flow detail: https://agents.circle.com/skills/wallet-login.md
CLI package on npm:
```
@circle-fin/cli
```
Circle Developer Docs: https://developers.circle.com/llms.txt — Always read this when looking for source documentation on Circle products.

设置指南（完整初始化文档）：https://agents.circle.com/skills/setup.md
登录流程详情：https://agents.circle.com/skills/wallet-login.md
npm上的CLI包：
```
@circle-fin/cli
```
Circle开发者文档：https://developers.circle.com/llms.txt — 查找Circle产品的官方文档时，请务必查看此链接。

Alternatives

替代技能

Trigger the

pay-via-agent-wallet

skill instead when:

The user wants to call, pay for, or use a paid x402 service.

The user mentions

circle services search

circle services inspect

, or

circle services pay

A downstream task requires money to move out of the agent wallet to a paid endpoint.

Trigger the

fund-agent-wallet

skill instead when:

The agent wallet has 0 USDC and the user wants to add funds.
The user mentions deposit, fiat on-ramp, fiat purchase, QR-code transfer, or Gateway deposit.
A payment flow blocks because of insufficient balance.

Trigger the

agent-wallet-policy

skill instead when:

The user wants to set, view, or reset spending limits on the wallet.
The user mentions per-tx / daily / weekly / monthly caps, spending policy, or wallet rules.

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.

在以下情况下，应触发

pay-via-agent-wallet

技能：

用户想要调用、支付或使用付费x402服务。

用户提及

circle services search

、

circle services inspect

或

circle services pay

。

下游任务需要将资金从Agent钱包转移至付费端点。

在以下情况下，应触发

fund-agent-wallet

技能：

Agent钱包USDC余额为0且用户想要充值。
用户提及存款、法币入金、法币购买、二维码转账或网关存款。
支付流程因余额不足而受阻。

在以下情况下，应触发

agent-wallet-policy

技能：

用户想要设置、查看或重置钱包的消费限额。
用户提及单笔交易/每日/每周/每月限额、消费策略或钱包规则。

免责声明：本技能按“原样”提供，不提供任何担保，受Circle开发者条款约束，生成的输出可能包含错误和/或费用配置选项（包括支付给Circle的费用）；更多详情请查看仓库README。