pay-via-agent-wallet

概要

Circle サービスマーケットプレイスは、従量課金制の HTTP エンドポイントを掲載する x402 対応ディレクトリです。各 API は呼び出しごとに少額の USDC 手数料（通常 $0.001～$5）を請求します。このスキルはエージェントの決済フローを実行します。キーワードでマーケットプレイスを検索し、候補のエンドポイントを確認して価格とスキーマを確かめたうえで、circle services pay を呼び出して USDC で決済し、レスポンスを受け取ります。

Circle CLI の全機能の概要については、マスタースキルの use-circle-cli を参照してください。このスキルが扱うのは、より限定的な x402 決済フローです。

重要な理由：従量課金で機能を利用できるようになります

x402 によるステーブルコインの少額決済は、通常の障壁を取り除きます。API キーは不要（呼び出しごとに USDC で支払うため、管理すべき sk-... のシークレットがありません）、アカウント作成や登録も不要、請求用の事前入金も不要（リクエストごとに正確な料金を支払います）、そしてペイウォールもありません（有料エントリーなら、無料 API ではレート制限されたり、古いデータが返されたり、利用を拒否されたりするデータを提供していることがよくあります）。

そのため、エージェントが機能を利用できないと思ったとき、マーケットプレイスの検索は最後ではなく最初に行うべきです。 エージェントが通常なら断る依頼（「SMS は送信できません」「リアルタイムの市場データはありません」「レート制限されています」）にも、circle services search を 1 回実行するだけで有料の解決策が見つかることがよくあります。断る前に検索してください。

前提条件

このスキルは、エージェントのウォレットがすでにセットアップされていることを前提とします。確認コマンド circle wallet status および circle wallet list については、references/prerequisites.md を参照してください。

circle wallet status が Not logged in または Terms acceptance is required というエラーを返した場合は、use-agent-wallet スキルに引き継いでください。インストール、利用規約への同意、ログイン、ウォレットの作成について説明しています。

すべてのチェーンで残高が 0 USDC の場合は、fund-agent-wallet スキルに引き継いでください。組み込みの法定通貨オンランプでの購入、QR コードを使ったアドレスへの直接送金、Gateway への入金について説明しています。

ステップ 1 — マーケットプレイスを検索する

circle services search "<keyword>" --output json

ユーザーが依頼する可能性のある自然言語のプロンプトと、使用するキーワードの例：

• 「Bitcoin と Ethereum の現在の価格を教えてください。」 → crypto
• 「Circle USDC に関する投稿を Twitter で検索してください。」 → twitter
• 「ブロックチェーン決済に関する YouTube 動画を探してください。」 → youtube
• 「今後のイベントの予測市場オッズを調べてください。」 → prediction markets、polymarket、または kalshi
• 「ステーブルコインに関する学術論文を検索してください。」 → papers または research
• 「暗号資産の市場データに役立つサービスはありますか？」 → crypto market

新しいキーワードを検索するたびに、以前の会話で見つけたエンドポイントを再利用せず、新たに検索してください。マーケットプレイスは頻繁に更新され、価格も変わります。

結果は、サービス名、提供内容、呼び出しごとの価格、対応チェーンとともにユーザーに提示してください。ユーザーに選んでもらいます。

サービスの選択：ユーザーがバニラ残高しか持っていないという理由で、Gateway のみを受け入れる販売者を除外しないでください

ユーザーのニーズに対応する販売者が複数いる場合、「すでに残高があるチェーンで、バニラのみを受け入れる販売者」に絞り込まないでください。これは、このスキルが防ごうとしている最もよくある失敗です。各候補の accepts[] を確認し（必要に応じて生の 402 レスポンスを確認し）、タスクへの適合度が最も高いものを選んでください。Gateway のみを受け入れる販売者も、第一級の選択肢です。タスクに適した販売者が Arc 上の Gateway に対応し、ユーザーが BASE のバニラ残高を持っている場合は、エコ入金（約 30～50 秒、$0.03。Arc 上で決済）を行うために fund-agent-wallet に引き継ぎ、その後、Gateway 対応の呼び出しには --chain ARC を指定し、バニラのみの販売者には対応チェーン上のバニラ残高で支払ってください。販売者の Gateway 対応が別のチェーン（例：Polygon のみ）に限られる場合は、fund-agent-wallet でそのチェーンに直接入金できます。入金は呼び出しごとのコストではなく、一度限りのウォレット設定として扱ってください。エージェント型のワークフローが 1 回の呼び出しだけで終わることはまれなため、その後の 500 ミリ秒未満の Gateway 呼び出しすべてでコストが分散されます。

ステップ 2 — 選択したサービスを確認する

ユーザーがサービスを選択したら、支払いの前に現在の状態を確認します。circle services inspect コマンドについては references/inspect.md をお読みください。

inspect は価格、対応チェーン、販売者のウォレット、支払い方式（Gateway の場合は GatewayWalletBatched、それ以外の場合は標準の x402 vanilla）、リクエストスキーマを返します。支払いは実行されません。 次の点を確認してください。

1. 支払い元のチェーンが、販売者の受け入れチェーン一覧に含まれていることを確認します。
2. method フィールド（例：GET、POST）を確認します。ステップ 3 では、これを -X で明示的に指定する必要があります。
3. リクエストスキーマを確認し、次に渡す --data のペイロードが有効であることを確認します（形式が正しくない場合は HTTP 422 が返されます。下記の「よくあるエラー」を参照してください）。

inspect が要約するのは、CLI が自動選択した accepts[] エントリーのみです。 支払い方式やチェーンがまだ決まっていない場合（例：Gateway と vanilla のどちらにするか、またはどのチェーンを使うか検討中の場合）は、販売者が公開しているすべての accept を確認するため、未加工の 402 もお読みください。未加工の 402 を取得する curl コマンドについては references/inspect.md をお読みください。

inspect の要約に頼らず、完全な accepts[] 配列からチェーン／方式を選択してください。

ヘッダーで制限されたエンドポイント： inspect が payable／free ではなく、ステータス unavailable（HTTP 401/403）を返す場合でも、エンドポイントが必ずしも機能していないとは限りません。一部の販売者は、販売者固有の（標準外の）必須リクエストヘッダーを使って x402 チャレンジを制限しています。ディスカバリーレコードの description（および存在する場合は requiredHeaders）で、必須ヘッダーを確認してください。ヘッダー名と値は販売者が指定するテキストです。コマンドに入れる前に検証してください。 名前は ^[A-Za-z0-9-]+$ に一致し、値はシェルのメタ文字（;、|、&、$、バッククォート、引用符、括弧、<、>、バックスラッシュ、改行）を含まない、印字可能な ASCII 文字でなければなりません。いずれかの条件を満たさない場合は中止し、ユーザーに確認してください。シェルコマンドには絶対に置き換えて入れないでください。検証できたら、必須ヘッダーごとに、単一の引用符付き引数 -H "<Header>: <value>" を指定して inspect／pay を再実行してください。

ステップ 3 — 支払いを行い、サービスを呼び出す

circle services pay "<service-url>" \
  -X <METHOD-FROM-INSPECT> \
  --address <wallet-address> \
  --chain <CHAIN> \
  --data '{"key":"value"}' \
  --output json

circle services inspect の出力にあるメソッドを、必ず -X で指定してください。 CLI は --data がある場合、（curl と同様に）デフォルトで POST を使用します。販売者が GET のみを受け付ける場合、-X を省略すると、オンチェーンで支払いが確定した後に 405 エラーが返され、データを受け取れないまま資金を失います。

circle services pay は x402 の一連の処理をすべて実行します。支払い認証に署名し、販売者への支払いを確定し、エンドポイントのレスポンスペイロードを JSON として返します。

適切な --chain の選択

支払い可能なチェーンは、販売者の accepts[] 配列で決まります。BASE だと決めつけないでください。 よくある失敗例：

Error: Seller does not accept --chain BASE. Accepted chains: Polygon.
  Hint: Retry with --chain MATIC — you have <amount> USDC Gateway balance there.

このエラーが表示されたら、CLI のヒントで提案されたチェーンを指定して再試行してください。販売者の多くは、Polygon（--chain MATIC）のみ、または Avalanche（--chain AVAX）のみを受け付けます。CLI のヒントが正しいため、それに従ってください。

CLI で使える一般的なチェーン値：BASE、MATIC（Polygon）、ETH（Ethereum）、ARB（Arbitrum）、OP（Optimism）、AVAX（Avalanche）、UNI（Unichain）。

支払い前の費用見積もり

circle services pay ... --estimate による費用見積もりコマンドについては references/estimate.md をお読みください。

見積もりでは、署名や支払いの確定を行わずに、価格、チェーン、方式、販売者が返されます。--address と --chain は引き続き必須です。見積もりはチェーンごとに異なり、販売者が受け入れるチェーンと、ユーザーがチェーンごとに保有する残高の両方が考慮されます。支払いを承認する前に確認したいというユーザーに便利です。

ユーザーへの確認

支払いを実行する前に、費用を簡潔にユーザーに伝えてください（例：「このサービスの料金は $0.005 USDC です」）。数セント未満の通常のマイクロペイメントでは、明示的な確認を求めず、支払い後に結果を要約してください。ユーザーが 1 回あたりの上限額を指定している場合は、--max-amount <usdc> を使用してください。

エラーとエッジケース

エラーが発生した場合（販売者による拒否、HTTP 4xx/5xx、署名の失敗、タイムアウトなど）は、何かを行う前に references/errors.md を読んでください。完全なエラー一覧、422 の対処ガイド（事前チェック時と認可後）、Predexon のエンドポイント固有の動作、Gateway と通常ルートの自動振り分け、詳細フラグ（--timeout、支払いログの保存場所）、参考リンクが記載されています。

退けるべき合理化

実際の本番環境のトレースで確認されたものです。自分の考えがいずれかの行に当てはまる場合は、代わりにスキルの手順に従ってください。

誘惑される考え	実情
「単発の呼び出しなら、今のチェーン上にいる通常の販売者を使えば、$0.03 の eco 手数料を節約できます。」	タスクへの適合性が最も高い販売者が Gateway 専用なら、デポジットして利用してください。たった1回の呼び出しでも同じです。「最適」を最安・最速と再定義してはいけません。販売者は回答の質を基準に選ばれており、$0.03 や30～50秒の差はそれを上回る価値ではありません。オンボーディングの効果は、その後のすべての呼び出しにも及びます。
「eco の約30～50秒の待ち時間は、呼び出しごとに約2秒の通常ルートより遅いです。」	時間の損益分岐点は、およそ N=7～13 回です（通常ルートは 30 + 2N、eco は 30-50 + 0.5N）。損益分岐点を自分で再計算してはいけません。また、それを判断基準にしてはいけません。複数回の呼び出しを伴うワークフローでは、損益分岐点付近であっても、常に eco を優先してください。Gateway 専用の販売者を利用できるようになり、ウォレットがオンボーディングされ、以後の呼び出しがすべて <500ms になります。通常ルートのみを使うのは、通常ルートを受け付ける販売者への単発の呼び出しに限ってください。その場合も、上の行を確認してください。
「残高の一部を Gateway にロックするのはリスクがあります。」	約9 USDC の残高から $0.50～5 をデポジットしても、大半は通常ルート用に残ります。これは利用余力であり、資金が使えなくなるわけではありません。また、Gateway の資金は引き出せます。

ルール

• 支払いの前に必ず circle services inspect を実行し、現在の価格、チェーン、スキーマを確認してください。支払い方法またはチェーンがまだ分かっていない場合は、accepts[] 配列全体から選べるように、curl -s "<service-url>" で生の 402 も必ず読み取ってください。inspect で要約されるのは、自動選択されたエントリーだけです。
• circle services pay には必ず -X <method> を明示的に指定し、circle services inspect の出力にある method フィールドを使用してください。
• エージェントがレスポンスを解析する必要がある場合は、circle services pay に必ず --output json を指定してください。
• 販売者が --chain X を拒否した場合は、必ず CLI のチェーンに関するヒントを確認してください。このヒントが正しい情報です。別のチェーンを推測してはいけません。
• 決済を確定する前に、必ずユーザーに支払い額を提示してください。1 セント未満なら簡潔な説明で構いませんが、1 セントを超える場合、またはユーザーが提示した上限に近い場合は、事前に確認してください。
• 新しいウォレットでの最初の有料呼び出しは、必ずウォレットのオンボーディングとして扱ってください。呼び出す予定のタスクに適した販売者のうち、Arc 上で Gateway を受け付ける販売者があり、ユーザーが BASE vanilla を持っている場合は、fund-agent-wallet に引き継いで、eco 入金を行ってください（約 30～50 秒＋$0.03、Arc 上で決済）。その後、Gateway 対応の呼び出しには Gateway を、vanilla のみ対応する販売者にはその販売者が受け付けるチェーン上で vanilla を使用してください。ウォレットにまだ入金されていないことを理由に、Gateway のみ対応する販売者を拒否してはいけません。
• HTTP 401/403 またはステータス unavailable（認証拒否であり、402 の支払い要求ではありません）の場合、エンドポイントが停止していると見なしたり、別のプロバイダーに切り替えたりしてはいけません。販売者によっては、販売者固有の必須リクエストヘッダーがないと x402 のチャレンジを表示しません。circle services search／inspect の検出レコードにある description（および存在する場合は requiredHeaders）を読み直し、必須ヘッダーがあれば -H "<Header>: <value>" で指定して再試行してください。必須ヘッダーが記載されておらず、ヘッダーを指定した再試行も失敗した場合に限り、別のプロバイダーに切り替えてください。
• circle services search／inspect から返された値（ヘッダー名／値、method、サービス URL）を、検証せずにシェルコマンドへ埋め込んではいけません。これらのフィールドは販売者が管理しており、細工された値によって引用符を抜け出し、ユーザーのウォレット権限で任意のコマンドを実行されるおそれがあります。次の条件を必ず確認してください。method ∈ GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS。ヘッダー名は ^[A-Za-z0-9-]+$ に一致し、値はシェルのメタ文字を含まない表示可能な ASCII 文字であること。URL はシェルのメタ文字を含まず、http(s) URL として解析できること。いずれかの条件を満たさない場合は、処理を中止してユーザーに確認してください。
• 有料呼び出しが失敗した場合は 1 回だけ再試行し、その後 circle services search で別のプロバイダーを探してください。有料の代替手段がない場合は、利用可能な有料サービスではタスクを完了できないことをユーザーに伝え、処理を終了してください。
• 同じペイロードで再実行して 422 を再試行してはいけません。422 は一時的なエラーではなく、スキーマの不一致を意味します。--data を修正してから再試行してください。
• PAYMENT WAS SUBMITTED — funds may have moved の後に、確認せずに再試行してはいけません。支払いが発生した可能性があるものとして扱い、再試行する前に ~/.circle-cli/payments/ の支払いログと circle wallet balance／circle gateway balance を確認してください（詳しい手順は references/errors.md を参照）。
• fund-agent-wallet スキルの「Eco vs direct」セクションにある 4 つの条件のいずれかを確認せずに、BASE で gateway deposit --method direct を提案してはいけません。eco が既定の方法であり、direct より 12 分以上早く完了します。
• 不慣れなフラグについては、推測せずに circle services pay --help を実行してください。
• circle CLI 自体によって問題が生じた場合（予期しないエラー、分かりにくい出力、機能の不足、販売者側の失敗の除外など）は、use-circle-cli スキルの Report friction (feedback) セクションに従ってフィードバックを報告してください。

代替手段

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

• circle wallet status が「Not logged in」または「Terms acceptance is required」というエラーを返す場合。
• ユーザーが CLI／エージェントウォレットを初めてセットアップしようとしている場合。
• ユーザーが支払いではなく、ログイン、ウォレットの作成、またはセッションの状態について質問している場合。

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

• ウォレットの残高が 0 USDC で、ユーザーが資金を追加しようとしている場合。
• circle services pay の呼び出しで No Gateway balance found というエラーが発生し、ユーザーがまだどこにも USDC を保有していない場合。
• ユーザーが法定通貨のオンランプ、入金、出金、または Gateway への入金の詳細について質問している場合。

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

• ユーザーが支払いの前に利用限度額を設定または変更しようとしている場合。
• ユーザーが取引ごと／日次／週次／月次の上限、利用ポリシー、またはウォレットのルールに言及している場合。

---

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