fund-agent-wallet

概述

如需了解 Circle CLI 的完整功能集概览，包括桥接、智能合约执行、x402 支付等，请参阅 use-circle-cli 主技能。本技能仅介绍范围更窄的资金充值流程。

为 Agent 钱包充值，就是将 USDC 存入 CLI 可用于支付的余额中。需要注意两种余额池：

• 链上（普通 x402）——存放在特定链上钱包地址中的 USDC。各条链的余额相互独立。用于支付 accepts[] 不包含 GatewayWalletBatched 的端点。在一个区块内完成结算。
• 微支付（由 Gateway 提供支持）——存放在 Circle Gateway 余额中的链下 USDC，由 Gateway 为你跨受支持的链批量处理并结算。按源链区分——支付时不会跨链汇集余额。用于支付 accepts[] 包含 GatewayWalletBatched 的端点。余额到位后，结算时间小于 500ms。

Gas 说明

Agent 钱包支付流程已抽象 Gas——用户无需预先充值原生 Gas，即可使用 USDC 支付。

本技能介绍如何为这两种余额池充值。选择最快完成的路径，并向用户隐藏链的复杂性。

前置条件

# Confirm session is good
circle wallet status

# Get the wallet address
circle wallet list --chain ARC --type agent --output json

# Check current on-chain balance (per chain)
circle wallet balance --address <addr> --chain ARC --output json

# Check current Gateway balance (per chain)
circle gateway balance --address <addr> --chain ARC --output json

如果 circle wallet status 报错，提示“Not logged in”或“Terms acceptance is required”，请转交给 use-agent-wallet 技能——该技能介绍安装、条款接受、登录和钱包创建。

第 1 步——选择充值路径

询问用户：“你想如何为钱包充值？”

• 法币（美元或当地货币）——通过 CLI 内置的法币入金通道，使用银行卡或银行转账购买 USDC。适合尚未持有加密货币的用户。
• 已有的 USDC——从用户已有的钱包（MetaMask、Coinbase、Phantom 等）发送 USDC。速度更快，且无需支付入金通道费用。
• Gateway 入金（高级）——将已有的链上 USDC 转入 Gateway 余额，以便进行低延迟批量支付。只有在所支付的卖家支持特定链上的 Gateway 时才有用。

默认建议：已有的 USDC → Arc。 Arc 使用 USDC 作为原生 Gas 代币（无需额外持有 Gas 资产），且最终性不到一秒，因此在 Arc 上进行 direct Gateway 入金可以快速结算——从 BASE 进行的 eco 入金也会转入 Arc，所以无论选择哪条路径，最终都会到达同一条链。支付仅接受这些链的卖家时，请使用 BASE/Polygon。

第 2 步——非交互模式下的必需标志

在交互模式下运行时，CLI 会提示填写缺失的值。Agent 处于非交互模式，因此，针对主网运行的每条 circle wallet fund 命令都必须包含：

• --address <addr>——来自 circle wallet list 的钱包地址
• --chain <chain>——例如 ARC（或 BASE、MATIC 等）
• --method <fiat|crypto>——缺少时会报错：Error: --method is required in non-interactive mode.
• --amount <number>——USDC 数量；缺少时会报错：Error: --amount is required.

--token usdc 是默认值，可以省略；但如果用户明确要求使用 USDC，请显式传入。

路径 A——法币入金通道

在用户的默认浏览器中打开法币入金通道窗口。资金会直接存入所选链上的钱包。

阅读 references/fiat-on-ramp.md，了解 circle wallet fund --method fiat --open 命令、结算说明和购买后余额验证。

路径 B——加密货币转账（已有的 USDC）

用户已在某处持有 USDC（例如其他钱包或交易所），并希望将其发送到 Agent 钱包。

推荐——浏览器渲染的 QR 码（最佳体验）

circle wallet fund --address <addr> --chain ARC --amount 10 --token usdc --method crypto --open

--open 会在本地 HTML 页面中渲染 EIP-681 QR 码，并在用户的默认浏览器中打开。默认使用此方式。在 Agent 界面（Claude Code、Codex 等）中，终端渲染的 QR 码经常被截断或无法扫描；浏览器页面会以完整分辨率渲染 QR 码，并可在桌面设备和移动设备上正常使用。

用户使用任意移动钱包（MetaMask、Coinbase Wallet、Rainbow、Phantom）扫描 QR 码，然后确认转账。

替代方案 — PNG 导出或手动转账

如果用户无法扫描浏览器二维码，请阅读 references/crypto-transfer-alternatives.md（通过 --export 将二维码导出为 PNG、手动转账详情，包括 USDC 合约地址）。

转账后验证

转账确认后，使用 circle wallet balance 验证 — 参见 references/crypto-transfer-alternatives.md 中的“转账后验证”部分。

路径 C — 网关充值（由 Gateway 提供支持，高级）

仅在以下情况下建议通过 Gateway 充值：

• 用户有链上 USDC，并且
• 用户想向某项服务付款，且该服务的 accepts[] 中包含特定链上的 GatewayWalletBatched，并且
• 该链是 Gateway 支持的链之一（Arc、Polygon、BASE、ETH、ARB、OP、AVAX、UNI）。

Eco 与 direct — 除非符合以下四个条件之一，否则选择 eco

circle gateway deposit --method eco 会将 BASE 普通 USDC 存入 Gateway，并在约 30-50s 后到账于 Arc（Gateway domain 26），固定费用为 $0.03。后续付款使用 pay --chain ARC。

仅在以下情况使用 --method direct：

1. 用户明确要求使用 direct — 例如“在 BASE 上充值，不要转到 Arc”、“留在 BASE 上”或“使用 direct 充值”。隐含偏好和你自己的推断不算。
2. 来源链不受 eco 支持 — 目前 eco 仅支持 BASE 作为来源链；请使用 circle gateway deposit --help 查看当前支持列表。尝试使用不支持的来源链会返回“Unknown method”或链不受支持的错误。
3. 卖家不接受 Arc 上的 Gateway — 通过读取卖家的原始 402 accepts[] 进行验证（不要使用 circle services inspect）。Eco 会将资金存入 Arc，因此如果卖家无法在该链上收款（例如仅支持 Polygon 的 Gateway 卖家），此笔付款将无法使用 Gateway 余额；请改为在卖家接受的链上直接充值。
4. 用户已有卖家接受的快速链上的普通 USDC — direct --chain <fast-chain> 仅在快速最终性链（Arc、MATIC、AVAX）上速度快，并可免去 eco 费用。（例如，用户在 Polygon 上有 5 USDC 普通 USDC → direct --chain MATIC；或者在 Arc 上有普通 USDC → direct --chain ARC。）

如果不符合条件 1–4，应选择 eco。仍然选择 direct 在 BASE 上会很慢：在 BASE（以及 ETH/ARB/OP/UNI）上使用 direct，需要等待约 13–19 分钟以达到最终性，还需支付 gas；相比之下，eco 只需约 30-50s，并收取 $0.03。 （上述快速耗时仅适用于 Arc/MATIC/AVAX — 切勿将其用于 BASE。）

按工作流比较，而不是按调用次数比较

Eco 的冷启动成本（约 30-50s + $0.03）只需支付一次；之后每次 Gateway 调用都少于 500ms。普通 USDC 无需充值，但每次调用都会永久耗时约 2s，且无法摊销。Agentic 工作流很少只有一次调用，因此应将充值视为一次性钱包接入成本，而非单次调用成本。（时间上的盈亏平衡点约为 N=7-13 次调用，但仅支持 Gateway 的卖家以及之后每次调用都少于 500ms 的优势，从第 1 次调用起就已显现。）

Eco 充值（BASE → Arc）

请阅读 references/gateway-eco-deposit.md，了解 circle gateway deposit --method eco 命令（--amount、--address、--chain、--method 均为必填项）以及 Gateway 余额验证方法。

充值验证通过后，将后续操作交给 pay-via-agent-wallet 技能进行实际付款 — 该技能负责 circle services pay 流程（包括其允许的工具白名单和注意事项）。

常见错误： 当 Gateway 余额已存入 Arc 时，在 pay 调用中使用 --chain BASE。pay 的链必须与余额所在链一致。

Direct 充值和 Gateway 提款

如果符合上述 --method direct 的任一条件，或用户想从 Gateway 提取 USDC，请阅读 references/gateway-direct-and-withdraw.md — 了解 direct 命令语法、支持的链和耗时，以及仅限同链提款 + circle bridge transfer 的操作模式。

故障排除

遇到任何资金错误（缺少标志、二维码无法扫描、Wallet not deployed、Insufficient balance、使用 eco 后链错误、提现限额）时，请阅读 references/troubleshooting.md，查看错误表和参考链接。

如果旧版 Eco 意图已过期、处于 WaitingForRefund 状态，或已将 USDC 退还至 eoaOwnerAddress，请停止充值并转交给 recover-eco-funds 技能。在使用任何可执行的恢复阶段前，请验证链上固定的退款接收方。当前 Gateway v2 充值会将 refundRecipient 设为 SCA，因此应使用常规状态和余额核对流程。

规则

• 绝 NEVER 提示用户将 USDC 发送到你生成的地址。始终使用用户在 circle wallet list 中自己的钱包。
• 绝 NEVER 存储、记录或显示私钥。
• 调用 circle wallet fund 时始终传入 --method <fiat|crypto>——Agent 以非交互模式运行，CLI 不会提示。
• 调用 circle wallet fund 时始终传入 --amount <number>——先与用户确认金额。
• 始终优先使用 --method crypto --open，不要在终端中渲染二维码——在 Claude Code、Codex 等 Agent UI 中，终端二维码会被截断，导致无法扫描。
• 对于法币，使用 --method fiat --open，以便在浏览器中打开入金服务。
• 除非已通过发现 API 或卖家的原始 402 accepts[] 验证目标服务支持在 Arc 上使用 Gateway，否则绝不要建议进行 Gateway eco 充值。
• 绝不要将用户 100% 的普通余额存入 Gateway。钱包需要保留普通余额，以便用户接下来可能使用仅支持普通余额的卖家。
• 金额计算公式：amount = max(price × N + fee + slack, Gateway minimum)，其中 N 为工作流预期的调用次数。通常将约 50% 的普通余额作为软性余额余量底线。Gateway 会在服务端强制要求最低充值金额；低于此金额会报错，因此建议金额不得低于该最低值。运行 circle gateway deposit --help 查看当前范围。
• 如果所需金额明显高于工作流总成本（低价端点示例：$0.0024/次 × 5 = $0.012，但 Gateway 最低充值额会设定下限），或超过用户指定的 --max-amount 上限，请在充值前告知用户。不要悄悄存入约为任务成本 100 倍的金额。
• 新链上的第一笔真实交易会部署 SCA——目前没有专用的“部署”命令。如果出现 Wallet not deployed 错误，请查阅 circle wallet --help 了解当前可用选项。
• 始终使用与余额所在链一致的 --chain。Eco 资金到账 Arc → pay --chain ARC。直接到账源链 → pay --chain <same>。
• Gateway 不会在付款时进行跨链转账。源链很重要。
• 除非用户明确要求技术细节，否则不要向用户展开链的具体细节。用户只是要求给钱包充值，不需要了解 EVM 最终性。
• 如果 circle CLI 本身在充值过程中造成阻碍（意外错误、输出令人困惑、缺少功能），请按照 use-circle-cli 技能中的 Report friction (feedback) 部分提交反馈。

替代方案

遇到以下情况时，请改用 recover-eco-funds skill：

• 旧版 Eco 意图已过期、正在等待退款，或未显示在 Gateway 中。
• 退款的 USDC 已到账至经 SCA API 验证的资金支持 EOA。
• 用户需要在链上期限过后，无需许可地自行申请 Eco 退款。

遇到以下情况时，请改用 use-agent-wallet skill：

• 用户尚未登录 CLI 或接受条款。
• circle wallet status 报错，提示 "Not logged in" 或 "Terms acceptance is required"。
• 用户询问的是钱包设置、登录或会话状态，而非资金入账。

遇到以下情况时，请改用 pay-via-agent-wallet skill：

• 用户想要调用付费 x402 服务或为其付款。
• 资金入账已完成，用户已准备好使用市场。
• 用户提到 circle services pay、circle services search 或任何“付费使用”提示。

遇到以下情况时，请改用 agent-wallet-policy skill：

• 用户想在资金入账前设置支出限额（这种情况较少见——大多数用户会先入账，之后再设置限额）。
• 用户提到单笔／每日／每周／每月上限、支出政策或钱包规则。

对于跨链 USDC 转账，Agent 应直接使用 circle bridge transfer——它是 Circle CLI 的一部分（请参阅 references/gateway-direct-and-withdraw.md，了解先提现再跨链转账的模式）。

---

免责声明：此 skill 按“原样”提供，不附带任何保证，且受 Circle 开发者条款约束。生成的输出可能包含错误和／或费用配置选项（包括将费用支付给 Circle 的选项）；更多详情请参阅代码库的 README。