fund-agent-wallet

概要

ブリッジ、スマートコントラクトの実行、x402 決済など、Circle CLI の全機能の概要については、マスタースキル use-circle-cli をご覧ください。このスキルでは、より限定的な資金調達フローを扱います。

エージェントウォレットへの資金調達とは、CLI で使用できるように USDC を入金することです。把握しておくべき残高プールは2 種類あります。

• オンチェーン（通常の x402） — 特定のチェーン上のウォレットアドレスに保管されている USDC です。チェーンごとに別々です。accepts[] に GatewayWalletBatched が含まれていないエンドポイントへの支払いに使用します。1 ブロックで決済されます。
• ナノペイメント（Gateway による） — Circle Gateway の残高にオフチェーンで保管され、対応チェーン間でまとめて決済される USDC です。送信元チェーンごとの残高であり、支払い時にチェーンをまたいでプールされることはありません。accepts[] に GatewayWalletBatched が含まれているエンドポイントへの支払いに使用します。残高があれば 500 ミリ秒未満で決済されます。

ガスに関する注意

エージェントウォレットの決済フローではガス代が抽象化されます。ユーザーはネイティブガスを事前に入金しなくても、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 — 資金調達方法を選ぶ

ユーザーに次のように尋ねてください。「ウォレットにはどの方法で資金を入れますか？」

• 法定通貨（USD または現地通貨） — CLI に組み込まれた法定通貨オンランプを使い、カードまたは銀行振込で USDC を購入します。まだ暗号資産を持っていないユーザーに最適です。
• 既存の USDC — すでに所有しているウォレット（MetaMask、Coinbase、Phantom など）から USDC を送金します。オンランプ手数料がかからず、より迅速です。
• Gateway 入金（上級者向け） — 既存のオンチェーン USDC を Gateway 残高に移し、低レイテンシの一括決済に利用します。支払い先の販売者が特定のチェーンで Gateway に対応している場合にのみ有用です。

既定の推奨方法：既存の USDC → Arc。 Arc は USDC をネイティブのガストークンとして使用するため（別のガス資産を保有する必要がありません）、ファイナリティも 1 秒未満です。そのため、Arc での direct Gateway 入金はすばやく決済されます。また、BASE からの eco 入金も Arc に着金するため、どちらの方法でも最終的に同じチェーンに集約されます。BASE または Polygon のみを受け付ける販売者に支払う場合は、BASE／Polygon を使用してください。

ステップ 2 — 非対話型利用で必須のフラグ

対話型で実行すると、CLI は指定されていない値を入力するよう促します。エージェントは非対話型であるため、メインネットに対する 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 — 法定通貨オンランプ

ユーザーの既定のブラウザーで法定通貨オンランプ画面を開きます。選択したチェーン上のウォレットに直接入金されます。

circle wallet fund --method fiat --open コマンド、決済に関する注意事項、購入後の残高確認については、references/fiat-on-ramp.md をお読みください。

パス B — 暗号資産の送金（既存の USDC）

ユーザーが別のウォレットや取引所などですでに USDC を保有しており、それをエージェントウォレットに送りたい場合に利用します。

推奨 — ブラウザーに表示する QR コード（最も使いやすい方法）

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

--open は EIP-681 QR コードをローカルの HTML ページに表示し、ユーザーの既定のブラウザーで開きます。既定ではこの方法を使用してください。エージェントの UI（Claude Code、Codex など）では、ターミナルに表示する QR コードが途中で切れたり、スキャンできなかったりすることがよくあります。ブラウザーページなら QR コードが完全な解像度で表示され、デスクトップでもモバイルでも使用できます。

ユーザーは任意のモバイルウォレット（MetaMask、Coinbase Wallet、Rainbow、Phantom）で QR コードをスキャンし、送金を確定します。

代替手段 — PNG へのエクスポートまたは手動転送

ユーザーがブラウザーの QR コードをスキャンできない場合は、references/crypto-transfer-alternatives.md を読み込んでください（--export による QR コードの PNG へのエクスポート、USDC のコントラクトアドレスを含む手動転送の詳細）。

転送後の確認

転送が完了したら、circle wallet balance で確認してください。詳しくは、references/crypto-transfer-alternatives.md の「転送後の確認」セクションをご覧ください。

パス C — Gateway 入金（Gateway を利用、高度な手順）

次の条件を満たす場合に限り、Gateway 入金を提案してください。

• ユーザーがオンチェーン USDC を保有していること、かつ
• 特定のチェーンで accepts[] に GatewayWalletBatched を含むサービスへの支払いを希望していること、かつ
• そのチェーンが Gateway の対応チェーン（Arc、Polygon、BASE、ETH、ARB、OP、AVAX、UNI）のいずれかであること。

Eco と direct の比較 — 4 つの条件のいずれかに該当しない限り eco を選択

circle gateway deposit --method eco は、BASE のバニラ USDC を Gateway に入金し、約 30〜50 秒で Arc（Gateway ドメイン 26）に着金します。手数料は一律 $0.03 です。後続の支払いでは pay --chain ARC を使用します。

--method direct を使用するのは、次のいずれかに該当する場合に限ります。

1. ユーザーが direct を明示的に指定した場合 — 例：「Arc に移さず BASE で入金して」「BASE のままにして」「direct deposit を使って」。暗黙の希望や独自の推測は該当しません。
2. 送金元チェーンが eco に対応していない場合 — eco が送金元として対応しているのは現在 BASE のみです。最新の一覧は circle gateway deposit --help で確認してください。未対応の送金元を指定すると、「Unknown method」またはチェーン未対応のエラーが返されます。
3. 販売者が Arc での Gateway 決済を受け付けない場合 — 販売者の raw 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 分かかり、さらにガス代も必要です。一方、eco は約 30〜50 秒で、手数料は $0.03 です。（上記の高速処理時間は Arc／MATIC／AVAX のみです。BASE については絶対に引用しないでください。）

呼び出しごとではなく、ワークフローごとに比較

eco の初回入金コスト（約 30〜50 秒と $0.03）は一度だけ発生します。その後の Gateway 呼び出しはすべて 500 ミリ秒未満です。バニラでは入金不要ですが、呼び出しのたびに約 2 秒かかり、その時間は短縮されません。エージェントによるワークフローが単一の呼び出しだけで済むことはまれです。入金は呼び出しごとのコストではなく、ウォレットの初回設定として扱ってください。（時間の損益分岐点は約 7〜13 回の呼び出しですが、Gateway のみ対応する販売者を利用できることと、その後の呼び出しが 500 ミリ秒未満になることを考えれば、1 回目からすでに有利です。）

Eco 入金（BASE → Arc）

circle gateway deposit --method eco コマンド（--amount、--address、--chain、--method はすべて必須）と Gateway 残高の確認方法については、references/gateway-eco-deposit.md を読み込んでください。

入金を確認したら、実際の支払いのために 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 のパターンが記載されています。

トラブルシューティング

資金調達に関するエラー（フラグの不足、QR コードをスキャンできない、Wallet not deployed、Insufficient balance、Eco の後にチェーンが異なる、出金限度額）が発生した場合は、必ず references/troubleshooting.md を読み、エラー一覧と参照リンクを確認してください。

レガシー Eco インテントの期限が切れた場合、WaitingForRefund の状態になった場合、または USDC が eoaOwnerAddress に返金された場合は、資金調達を中止し、recover-eco-funds スキルに引き継いでください。実行可能な復旧フェーズを使用する前に、オンチェーンの固定された返金先を確認してください。現在の Gateway v2 の入金では refundRecipient が SCA に設定されているため、通常のステータスと残高の照合を使用してください。

ルール

• 生成したアドレスに USDC を送金するよう、ユーザーに絶対に依頼しないでください。必ず circle wallet list でユーザー自身のウォレットを使用してください。
• 秘密鍵を保存、ログ出力、表示しないでください。
• 必ず circle wallet fund に --method <fiat|crypto> を渡してください。エージェントは非対話型であり、CLI はプロンプトを表示しません。
• 必ず circle wallet fund に --amount <number> を渡してください。先に金額をユーザーに確認してください。
• ターミナル QR コードは Claude Code、Codex などのエージェント UI 内で途中までしか表示されず、スキャンできなくなるため、必ず QR コードをターミナルに表示するよりも --method crypto --open を優先してください。
• 法定通貨の場合は、--method fiat --open を使い、オンランプをブラウザーで開いてください。
• Gateway の Eco 入金を提案するのは、ディスカバリー API または販売者の生の 402 accepts[] により、対象サービスが Arc 上の Gateway に対応していることを確認できた場合に限ってください。
• ユーザーの通常残高を Gateway に 100％入金しないでください。ユーザーが次に利用する可能性のある、通常入金のみ対応の販売者に備えて、ウォレットには通常残高の余裕が必要です。
• 金額の算出式：amount = max(price × N + fee + slack, Gateway minimum)。N はワークフローで想定される呼び出し回数です。通常、通常残高の約 50％を余裕分の目安として確保してください。Gateway ではサーバー側で最低入金額が設定されており、それを下回る金額ではエラーが返されるため、提案額はその最低額以上にしてください。現在の上限と下限を確認するには、circle gateway deposit --help を実行してください。
• 必要な金額がワークフローの合計コストより大幅に大きい場合（低価格エンドポイントの場合：1 回あたり $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 スキルを起動してください。

• レガシーの Eco インテントが期限切れになった、返金待ちになっている、または Gateway に表示されない場合。
• 返金された USDC が、SCA によって API で確認された裏付け用 EOA に着金した場合。
• ユーザーがオンチェーンの期限後に、パーミッションレスな Eco の自己返金を行う必要がある場合。

次の場合は、代わりに use-agent-wallet スキルを起動してください。

• ユーザーがまだ CLI にログインしていない、または利用規約に同意していない場合。
• circle wallet status が「Not logged in」または「Terms acceptance is required」というエラーを返す場合。
• ユーザーの質問がウォレットの設定、ログイン、またはセッション状態に関するもので、資金の入金に関するものではない場合。

次の場合は、代わりに pay-via-agent-wallet スキルを起動してください。

• ユーザーが有料の x402 サービスを呼び出す、またはその料金を支払う場合。
• 資金の入金が完了し、ユーザーがマーケットプレイスを利用する準備ができている場合。
• ユーザーが circle services pay、circle services search、または「支払い」に関するプロンプトに言及した場合。

次の場合は、代わりに agent-wallet-policy スキルを起動してください。

• ユーザーが入金前に支出上限を設定したい場合（まれなケースです。ほとんどのユーザーは先に入金し、後から上限を設定します）。
• ユーザーが取引ごと／日次／週次／月次の上限、支出ポリシー、またはウォレットのルールに言及した場合。

クロスチェーンで USDC を移動する場合、エージェントは circle bridge transfer を直接使用してください。これは Circle CLI の一部です（出金後にブリッジする方法については、references/gateway-direct-and-withdraw.md を参照してください）。

---

免責事項：このスキルは「現状有姿」で提供され、保証はありません。また、Circle Developer Terms が適用されます。生成された出力には誤りが含まれる場合や、手数料設定オプション（Circle 宛ての手数料を含む）が含まれる場合があります。詳細については、リポジトリの README を参照してください。