use-agent-wallet

概要

Circle CLI（@circle-fin/cli、コマンドは circle）は、プログラムから利用できるエージェントウォレットを提供します。これは、AI エージェントが認証し、残高を保有し、Circle のマーケットプレイスにある有料の x402 サービスに支払うために設計された、ノンカストディアル型の USDC ウォレットです。このスキルは、そのウォレットを利用するための初期設定を担います。インストールの確認、利用規約への同意、ログイン、ウォレットの作成、ステータスの確認を行います。初期設定が完了した後の操作（サービスへの支払い、資金の入金、支出ポリシーの設定）は、専用スキルに引き継がれます。

ブリッジ、スマートコントラクトの実行、トランザクションの確認など、Circle CLI のすべての機能の概要については、マスタースキルの use-circle-cli を参照してください。このスキルは、初期設定と ID 確認に特化しています。

ワークフロー

1. CLI がインストールされていることを確認し、何よりも先に circle wallet status でセッションの状態を確認します。
2. 利用規約のゲートが表示された場合は、まず利用規約の表示と同意のフローを完了します。ユーザーに代わって同意してはいけません。
3. ログインしていない場合は、メールアドレスと OTP による 2 段階ログインを行い、セッションを確認します。
4. 既存のエージェントウォレットを一覧表示し、存在しない場合は作成します（--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 は、AI エージェントなどの非対話型環境向けに設計された、OTP による 2 段階ログインに対応しています。ユーザーにメールアドレスを尋ね（決して推測したり、ハードコードしたりしないでください）、--init で OTP をリクエストしてから、返されたリクエスト ID と OTP コード（例：ABC-123456）を使ってログインを完了し、circle wallet status で確認します。リクエスト ID は 1 回のみ使用でき、有効期限は 10 分です。

正確なコマンドと想定される出力、OTP の形式に関する注意事項、失敗時の対応、ログアウトやアカウント切り替えの方法については、references/install-and-login.md を読み込んでください。

ステップ 4 — エージェントウォレットを確認または作成する

circle wallet list と circle wallet balance には、--chain フラグが必須です。 ユーザーがチェーンを指定していない場合は、デフォルトとして ARC を使用してください。既存のエージェントウォレットを一覧表示します。存在しない場合は、circle wallet create でサポートされている各 EVM チェーン上にエージェント管理の SCA ウォレットを作成し、JSON 出力からチェーンごとのアドレスを読み取ります。

正確な circle wallet list、circle wallet create、circle wallet balance コマンドと、JSON 出力の読み取り方については、references/wallet-management.md を読み込んでください。

ステップ 5 — ウォレット残高を確認する

保存されている各アドレスの残高を確認してください（references/wallet-management.md を参照）。残高が 0 USDC で、ユーザーがサービスへの支払いを希望する場合は、fund-agent-wallet スキルに引き継いでください。このスキルでは、組み込みの法定通貨オンランプでの購入、QR コードを使ったアドレスへの直接送金、Gateway への入金を扱います。ユーザーが状態の確認のみを希望し、まだ支払う予定がない場合は、ここで終了してください。初期設定は完了です。

ブートストラップ後

ウォレットが作成されたら、ユーザーは次にそれを使おうとする可能性が高いです。CLI には独自のスキルカタログがあります。circle skill list でインストール可能なスキルを確認でき、circle skill info --name <skill> でトリガーとフロントマターの詳細を確認でき、circle skill install --tool <host> --name <skill> で現在のホストにスキルをインストールできます。資金の追加、有料サービスの検索、支出上限の設定など、自然な次の手順を提案してください。ユーザーから依頼されるまでは、資金を移動する操作より、許可不要の操作（残高確認、検索）を優先してください。

利用規約の確認ゲート

ユーザーがこのマシンで Circle の利用規約とプライバシーポリシーに同意するまで、CLI はすべての運用用 circle wallet コマンド（circle wallet status を含む）を厳しく制限します。このゲートが初めて表示された時点（通常はステップ 2 またはステップ 3）で実行してください。一度同意が記録されると、以降の実行ではゲートは何もせず、スキップされます。

重大：エージェントは、circle terms accept を実行する前に、利用規約を必ずユーザーに提示し、明示的な同意を得なければなりません。エージェントは、ユーザーに代わって Circle の利用規約またはプライバシーポリシーに同意してはなりません。CLI の CIRCLE_ACCEPT_TERMS=1 環境変数のヒントは、エージェントが独自に使ってよい回避策ではありません。無視して、references/terms-of-use.md に記載された同意フローを使用してください。

ゲートの正確なエラーテキスト、circle terms show／circle terms show --init／circle terms accept／circle terms reset コマンド、および利用規約を提示して同意を求める必須フローについては、references/terms-of-use.md を読んでください。

ルール

セキュリティ

• エージェントウォレットのログイン時に、ユーザーのメールアドレスを決して推測したり、ハードコードしたりしないでください。
• 有効な認証セッション中に提供された OTP コードは安全に扱えます。チャットで受け取り、すぐに使用し、その後は保持も再利用もしないでください。
• スキルファイルに実際の秘密鍵、API キー、その他の永続的なシークレットを決して含めないでください。また、それらをどこにも保存しないでください。
• 現在のセッションでユーザーから明示的な同意を得ずに、circle terms accept を決して実行しないでください。エージェントはユーザーに代わって 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 スキルの 問題の報告（フィードバック） セクションに従ってフィードバックを送信してください。
• CLI の一般的なルール（--output json、--chain、--help 優先、後続の操作の表現、確認時のデフォルト設定）については、use-circle-cli マスタースキルの「ルール」セクションを参照してください。ここでも同じルールが適用されます。

参考リンク

• インストールとログイン（コマンド）：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 Developer Docs：https://developers.circle.com/llms.txt — Circle 製品のソースドキュメントを探す際は、必ずこちらを読んでください。

代替手段

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

• ユーザーが有料の x402 サービスを呼び出す、料金を支払う、または利用したい場合。
• ユーザーが circle services search、circle services inspect、または circle services pay に言及した場合。
• 後続のタスクで、エージェントウォレットから有料エンドポイントへ資金を移動する必要がある場合。

次の場合は、代わりに fund-agent-wallet スキルを呼び出してください。

• エージェントウォレットの USDC が 0 で、ユーザーが資金を追加したい場合。
• ユーザーが入金、法定通貨のオンランプ、法定通貨での購入、QR コード送金、または Gateway 入金に言及した場合。
• 残高不足により決済フローがブロックされる場合。

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

• ユーザーがウォレットの利用限度額を設定、表示、またはリセットしたい場合。
• ユーザーが取引ごと／日次／週次／月次の上限、利用ポリシー、またはウォレットのルールに言及した場合。

---

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