use-agent-wallet

概述

Circle CLI（@circle-fin/cli，命令 circle）提供程序化 Agent 钱包——一种非托管 USDC 钱包，专为 AI Agent 设计，可用于身份验证、持有余额，以及在 Circle 的市场上为付费 x402 服务付款。此技能是该钱包的引导入口：检查安装、接受条款、登录、创建钱包和检查状态。引导完成后，下游操作（支付服务费用、充值、支出策略）将交由专用技能处理。

如需了解 Circle CLI 的全部功能——跨链转账、智能合约执行、交易检查等——请参阅主技能 use-circle-cli。此技能仅涵盖引导和身份相关操作。

工作流

1. 确认 CLI 已安装，然后先运行 circle wallet status 检查会话状态。
2. 如果出现使用条款关卡，先完成查看条款并征求同意的流程——绝不可代替用户接受。
3. 如果尚未登录，执行两步式电子邮件 + OTP 登录，然后验证会话。
4. 列出已有的 Agent 钱包；如果没有，则创建钱包（--chain 默认为 ARC）。
5. 检查钱包余额；如果余额为 0 USDC 且用户想要付款，则交由 fund-agent-wallet 处理。否则，引导流程即告完成。

前提条件 / 设置

步骤 1 — 确认 CLI 已安装

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

如果未安装 circle，或者 circle --version 显示由服务端驱动的更新通知，请阅读 references/install-and-login.md，了解安装和更新通知的相关说明。

步骤 2 — 检查会话状态

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

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。

步骤 3 — 登录（电子邮件 + OTP）

Circle CLI 支持两步式 OTP 登录，适用于 AI Agent 和其他非交互场景：向用户询问其电子邮件（绝不可猜测或硬编码），使用 --init 请求 OTP，然后使用返回的请求 ID 和 OTP 验证码（例如 ABC-123456）完成登录，并通过 circle wallet status 验证。请求 ID 只能使用一次，有效期为 10 分钟。

请阅读 references/install-and-login.md，了解准确的命令、预期输出、OTP 格式说明、故障处理方法，以及如何登出 / 切换账户。

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

circle wallet list 和 circle wallet balance 命令必须使用 --chain 标志。 如果用户未指定链，则默认使用 ARC。列出现有的 Agent 钱包；如果没有，则 circle wallet create 会在每个受支持的 EVM 链上创建由 Agent 控制的 SCA 钱包，然后从其 JSON 输出中读取各链地址。

请阅读 references/wallet-management.md，了解准确的 circle wallet list、circle wallet create 和 circle wallet balance 命令，以及如何读取其 JSON 输出。

步骤 5 — 检查钱包余额

检查每个已保存地址的余额（参见 references/wallet-management.md）。如果余额为 0 USDC 且用户想要支付服务费用，则交由 fund-agent-wallet 技能处理——该技能涵盖内置法币入金购买、使用二维码直接向地址转账，以及 Gateway 充值。如果用户只是想确认状态（暂不付款），则到此为止。引导流程即告完成。

引导设置后

钱包创建后，用户接下来很可能会使用它。CLI 提供了自己的技能目录：circle skill list 可显示可安装的技能，circle skill info --name <skill> 可显示触发条件和 frontmatter 详情，circle skill install --tool <host> --name <skill> 可为当前主机安装技能。建议自然的后续操作，例如充值、搜索付费服务或设置支出限额；在用户提出要求之前，优先推荐无需许可的操作（余额查询、搜索），而不是资金转移操作。

使用条款门控

在用户接受本机上的 Circle 使用条款和隐私政策之前，Circle CLI 会严格拦截所有执行操作的 circle wallet 命令（包括 circle wallet status）。首次出现此门控时（通常在步骤 2 或步骤 3 中），请运行该门控。记录一次接受后，门控将不再执行，后续运行时会跳过。

重要：Agent 必须向用户展示条款，并在运行 circle terms accept 之前取得用户明确同意。Agent 绝不能代替用户接受 Circle 的使用条款或隐私政策。CLI 提示的 CIRCLE_ACCEPT_TERMS=1 环境变量并非 Agent 可以自行采用的变通方法——请忽略此提示，并使用 references/terms-of-use.md 中的同意流程。

请阅读 references/terms-of-use.md，了解门控的准确错误文本、circle terms show / circle terms show --init / circle terms accept / circle terms reset 命令，以及必须遵循的展示条款并征求同意流程。

规则

安全

• 绝不要猜测或硬编码用户用于 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。

最佳实践

• 尝试登录前，务必检查 circle wallet status。许多会话“故障”实际上只是过时的假设。
• 解析并保存 circle wallet login --init 输出中的请求 ID——完成 OTP 步骤时需要用到它。
• 请求 ID 只能使用一次，并会在 10 分钟后过期。如果看到“Invalid or expired request ID”，请从 --init 重新开始。
• 如果设置过程中某条 circle 命令导致操作受阻（出现意外错误、输出令人困惑或缺少功能），请按照 use-circle-cli 技能中的 Report friction (feedback) 部分提交反馈。
• 常规 CLI 规则（--output json、--chain、优先使用 --help、后续操作措辞、确认默认设置）请参阅 use-circle-cli 主技能的 Rules 部分——这些规则在此处同样适用。

参考链接

• 安装和登录（命令）：references/install-and-login.md
• 钱包管理（列出、创建、查询余额）：references/wallet-management.md
• 使用条款门控（命令和同意流程）：references/terms-of-use.md
• 设置指南（完整引导设置文档）：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 产品的源文档时，务必阅读此文档。

替代方案

在以下情况下，改为触发 pay-via-agent-wallet 技能：

• 用户想要调用、支付或使用付费 x402 服务。
• 用户提到 circle services search、circle services inspect 或 circle services pay。
• 下游任务需要将资金从 Agent 钱包转出到付费端点。

在以下情况下，改为触发 fund-agent-wallet 技能：

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

在以下情况下，改为触发 agent-wallet-policy 技能：

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

---

免责声明：此技能按「原样」提供，不作任何保证，且受 Circle Developer Terms 约束。生成的输出可能包含错误，和／或包含费用配置选项（包括支付给 Circle 的费用）；详情请参阅仓库中的 README。