x402

💸 x402 マネタイズスキル

あらゆるローカル HTTP サービスをプラットフォームネットワーク上の有料サービスに変え（Base + Monad + Robinhood + X Layer、x402 V2 プロトコル、exact スキーム、EIP-3009 経由の USDC/USDG — 購入者はガス代ゼロ）、さらにユーザーの Privy ウォレットを使って他のエージェントの x402 サービスに支払う購入者としても動作します。

アーキテクチャ: リバースプロキシサイドカー。 ゲートウェイ（gateway/app.py）はユーザーの未改変のサービスの前に位置します。単一の統合ゲートウェイで、3 つの課金モードを設定プリセットとして提供し、エラー契約はすべてのモードで同一です。

buyer agent ──402/PAYMENT-SIGNATURE──> gateway :840x ──plain HTTP──> user service :port
                     │
               facilitator (verify + settle on Base/Monad/Robinhood/X Layer/Solana) ──USDC/USDG──> user's Privy wallet

参照ファイル（該当タスクの前に必ず読むこと）

詳細な資料は skills/x402/references/ にあり、これは本スキルの一部です。これらのファイルが扱う内容を推測したり即興で補ったりしないでください:

その前に…	まず read_file すべきファイル
基本的な pay_per_use 以外の販売モードをデプロイする（完全なコマンド、プリペイドおよびマルチプラン契約、管理者トークン、テンプレート、ゲートウェイのライフサイクル、常時稼働/更新モード）	skills/x402/references/selling.md
期間限定無料プロモーションを有効化 / デバッグ / 説明する（amount=0、決済なし、P1〜P5 ACL、購入者の無料フロー、リソース分離、検証マトリクス）	skills/x402/references/selling.md → 期間限定無料プロモーション
無料プロモーションのエラー（課金されたまま、アップストリーム 401、amount が 0 でない、誤ったサービスがアンロックされる）	skills/x402/references/troubleshooting.md → 期間限定無料プロモーション
その他あらゆるエラーをデバッグする（ファシリテーターの検証エラー、エラー契約、セキュリティモデル、ポートの所有権、プロキシ）	skills/x402/references/troubleshooting.md
セッション EOA 署名者を使う、購入者ウォレットに入金する、または Base-USDC 以外のチェーン/トークンで支払う	skills/x402/references/buying-advanced.md

期間限定無料プロモーション（販売者向けクイックルール）

掲載された有料マーケットプレイスサービスの場合、オーナーは無料期間を開くことができます（最大 90 日間）。完全なプレイブック: references/selling.md → 期間限定無料プロモーション。

エージェントは必ず:

1. UI プロンプトから無料プロモーションを盲目的に PUT しない — まず P1〜P5 のセルフチェックを実行する。
2. 無料 = ウォレットアイデンティティ + amount 0 の検証 + 決済/引き落としなしであり、匿名ではなく、期間終了後の無料生涯サブスクリプションでもないことを覚えておく。
3. プラットフォームゲートウェイでは: amount-0 チャレンジと決済/引き落としのスキップは組み込みである。
4. カスタムアップストリームキー（P3/P4）または自作 x402では: 必ず ACL にパッチを当てる / amount="0" を強制する / 決済をスキップする — selling.md のステップ C を参照。
5. アクセス分離には x402 の **resource（パス）**を使用する — ワイヤ上で service_id を勝手に考案しない。
6. 有効化後: 無料ステータス、402 の amount=0、決済なしの無料呼び出しを検証し、その後キャンセル/期限切れ後に有料パスが戻ることを確認する。

購入者向けのヒント: 未払いの 402 が accepts[].amount == "0" を示す場合、0 に署名します（USDC は不要）。無料期間中に定価の署名を強制しないでください。

販売 — サービスをマネタイズする（クイックスタート）

FAC=https://starchild-x402-facilitator.fly.dev
# pay_per_use: verify -> settle on EVERY request (simplest mode)
# --networks defaults to "all" (Base + Monad + Robinhood + X Layer + Solana mainnet); the 402 challenge
# returns a multi-accepts list — the buyer picks one chain per payment.
python3 skills/x402/scripts/monetize.py --name my-api --upstream-port 5173 \
    --mode pay_per_use --price 0.01 --facilitator $FAC

# lock to a single chain (custom)
python3 skills/x402/scripts/monetize.py --name my-api --upstream-port 5173 \
    --mode pay_per_use --price 0.01 --networks eip155:8453 --facilitator $FAC

プラットフォームモードはコミュニティゲートウェイの課金契約に従います: accepts をリストとして持つ 402 JSON ボディ（マルチアクセプト、ネットワークごとに 1 エントリ — 購入者は支払いごとに 1 つのチェーンを選択）、accepts[].pricingModel、ファシリテーターが「支払い済み」の唯一の信頼できる情報源であり、すべての決済が記録のためにコミュニティゲートウェイへ自動コールバックします。

課金モードの決定表

モード	ティア	購入者 UX	使用場面
pay_per_use	platform	リクエストごとに X-PAYMENT、呼び出しごとに決済	シンプルなデータエンドポイント、エージェント間の単発利用
lifetime	platform	一度支払えば永続アクセス（facilitator 検証済み）	一度きりのアンロック、買い切り価格
monthly	platform	暦月ごとに一度支払い	SaaS 形式のサブスクリプション
weekly / quarterly / yearly	platform	固定期間パス：最新の支払いから 7 / 90 / 365 日	短期トライアル、年間割引
prepaid	platform	オンチェーンで一度入金 → 呼び出しごとにオフチェーンで引き落とし	高頻度 / サブセント / 使用量課金の API
payperuse	legacy	SDK V2 ヘッダー、リクエストごとに支払い	2.0 以前のデプロイ
subscription	extended	x402 トップアップ → API キー + N クレジット、1 呼び出しあたり 1 クレジット	プリペイドクレジット、呼び出しごとの支払いレイテンシーを回避
metered	extended	subscription と同様、ルート加重ユニット	安価/高価なエンドポイントの混在（LLM 呼び出しなど）
timepass	extended	x402 支払い → API キーに N 日間のパス	固定期間のパス（暦月ではない）

⚠️ lifetime/monthly/weekly/quarterly/yearly には --facilitator-admin-token が必須です （起動時にフェイルクローズ）。マルチプラン：--plan MODE=PRICE（繰り返し指定可能）。 → これらのモードをデプロイする前に必ず references/selling.md をお読みください — 正確なコマンド、コントラクトの詳細、テンプレート一覧が記載されています。

出力には gateway_port が含まれます。アップストリームではなく GATEWAY ポートを公開してください （preview またはコミュニティ公開経由）。pay_to はデフォルトでユーザーの Privy EVM ウォレットになります — 収益はそこに直接入金されます。 レジストリ：/data/workspace/.x402/services.json；サービスごとの設定/ログ/状態： /data/workspace/.x402/<name>/。

ネットワークとファシリテーター

このプラットフォームは複数のチェーンをサポートしています。デフォルトでは、サービスは プラットフォームのメインネット完全セット(--networks all、これがデフォルト)に従います — 現在は Base + Monad + Robinhood + X Layer + Solana です。402 チャレンジは multi-accepts リスト(チェーンごとに 1 エントリ)を返します。購入者は支払いごとに 1 つのチェーンを選択します。 --networks eip155:8453,eip155:143,eip155:4663,eip155:196(カスタム)で特定の チェーンに固定できます。

ネットワーク	CAIP-2	ステーブルコイン	EIP-712 名	Gas
Base メインネット	eip155:8453	USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	USD Coin	ETH(プラットフォーム負担)
Base Sepolia(テストネット)	eip155:84532	USDC 0x036CbD53842c5426634e7929541eC2318f3dCF7e	USDC	ETH(プラットフォーム負担)
Monad メインネット	eip155:143	USDC 0x754704bc059f8c67012fed69bc8a327a5aafb603	USDC	MON(プラットフォーム負担)
Monad テストネット	eip155:10143	USDC 0x534b2f3A21130d7a60830c2Df862319e593943A3	USDC	MON(プラットフォーム負担)
Robinhood メインネット	eip155:4663	USDG 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168	Global Dollar	ETH(プラットフォーム負担)
Robinhood テストネット	eip155:46630	USDG 0x7E955252E15c84f5768B83c41a71F9eba181802F	Global Dollar	ETH(プラットフォーム負担)
X Layer メインネット	eip155:196	USDC 0x74b7F16337b8972027F6196A17a631aC6dE26d22	USD Coin	OKB(プラットフォーム負担)
X Layer テストネット	eip155:1952	USDC 0x74b7F16337b8972027F6196A17a631aC6dE26d22	USD Coin	OKB(プラットフォーム負担)

ファシリテーター	ネットワーク	使用場面
platform(https://starchild-x402-facilitator.fly.dev、メインネットのデフォルト。X402_FACILITATOR_URL または --facilitator で上書き)	Base + Monad + Robinhood + X Layer + Solana メインネット	本番 — プラットフォームのセトラーがすべてのチェーンで Gas を支払います
https://x402.org/facilitator(テストネットのデフォルト)	Base Sepolia + Monad + Robinhood + X Layer テストネット	テスト専用 — メインネットでは拒否されます(起動時のガード)

プラットフォームのファシリテーターは、サポートされるすべてのチェーンで /verify + /settle を処理します。 そのセトラーキーは Gas を支払うだけで、資金の流れは購入者の署名によって固定されており、 ユーザー資金に触れることは決してありません。Gas/手数料はすべてのチェーンでプラットフォームが支払い (Base では ETH、Monad では MON、Robinhood では ETH、X Layer では OKB、Solana では SOL)、サービス プロバイダーに転嫁されることはありません。 安全性: Gas を消費する前の必須の eth_call シミュレーション、 支払者ごとのレート制限、認可ノンスの冪等性。 テストネット USDC(Base Sepolia): 0x036CbD53842c5426634e7929541eC2318f3dCF7e、 フォーセットは faucet.circle.com にあります。価格は自動変換されます: $0.01 → 10000 の USDC アトミック単位。

マルチチェーン構成(networks_mode)

構成	動作
--networks all(デフォルト)または networks_mode: all	402 accepts = プラットフォームのメインネット完全セット(Base + Monad + Robinhood + X Layer + Solana)。ファシリテーターが x402.org の場合はテストネット完全セット
--networks eip155:8453 または networks_mode: custom + networks: [...]	402 accepts = リストされたチェーンそのもの(カスタム固定)
(networks フィールドなし)	all と同じ

プラットフォームに新しいチェーンを拡張するには、platform_modes.py の ASSETS + MAINNET_NETWORKS(およびファシリテーターの KNOWN_ASSETS)を更新するだけで済みます — all で構成されたすべてのサービスは、次回の 402 で新しいチェーンを取得し、 ビジネステーブルの更新は一切不要です。

⚠️ Robinhood USDG に関する注意: USDG コントラクトは、非標準の EIP-712 ドメインを持つ Diamond プロキシを使用しています。ファシリテーターは検証のためにチェーンから DOMAIN_SEPARATOR() を 読み取ります。購入者側の生ダイジェスト署名は TODO です(client.py の _CHAIN_DOMAIN_SEP_CHAIN_IDS を参照)。現時点では標準の型付きデータ署名が 使用されており、オンチェーンのドメインがメタデータと一致する場合は機能します。

従来の Base のみの構成は一度だけ移行されます(SQL/構成の一括更新で networks_mode: all へ)。resolve_networks は「ベアの Base は all を意味する」とは推測しません。

キープアライブ（マシンごとに 1 回登録）

1 つのウォッチドッグがすべての x402 ゲートウェイを監視します（cloudflare-skill パターン: 冪等、 状態変化時のみ出力 → 正常時はスケジュールタスクが無音）:

1. 起動時: /data/workspace/setup.sh に追記: bash /data/workspace/skills/x402/scripts/keepalive.sh || true
2. ウォッチドッグ: scheduled_task(action="schedule", schedule="every 10 minutes", command="bash skills/x402/scripts/keepalive.sh", deliver="origin") — 出力が空 = 無音。 ⚠️ 相対パス（skills/x402/...）を使用し、絶対に /data/workspace/skills/... を使わないでください — スケジューラーのパスサニタイザーが絶対コマンドから workspace/ を削除し、 存在しない /data/skills/... に改変してタスクが毎回失敗します。登録後、 get_log で最初の実行が成功することを確認してください。

ゲートウェイがダウン → その設定から再起動されます。上流がダウン → 報告されますが 再起動はされません（上流にはプレビュー経由の独自のスーパーバイザーがあります — 競合しないでください）。

LISTED の有料サービスは 24 時間 365 日到達可能でなければなりません（アイドルサスペンド + 自動更新 の再起動がこれに影響します）→ 公開前に references/selling.md § Always-on availability を読んで、更新モードの確認/切り替えフローを確認してください。

購入 — 他のエージェントの x402 サービスに支払う

クイックスタート — プリセット CLI スクリプト（これらを最初に使用、カスタムコードは不要）

ステップごとに 1 プロセス、stdout に 1 つの JSON オブジェクト — 残高/署名/レール選択に関する 呼び出しごとの LLM 推論は不要:

# 1. FREE probe: is it x402? which rails? (never pays)
python3 skills/x402/scripts/discover.py --url https://host/api/thing
python3 skills/x402/scripts/discover.py --query "weather api"   # catalog search

# 2. Preflight: signer + policy + live USDC per rail + recommended_rail
python3 skills/x402/scripts/preflight.py --usd 0.05

# 3. Pay — resolve → probe → pick final rail → preflight THAT rail's own
#    price+network → pay the SAME resolved URL (rail pinned; --max-usd is
#    only a spend ceiling). Exit 2 = blocked/over-cap/network-not-accepted,
#    nothing signed. --network not in accepts fails fast (no silent fallback).
python3 skills/x402/scripts/buy.py --url https://host/api/thing --max-usd 0.05
python3 skills/x402/scripts/buy.py --url https://host/x402/q \
    --json '{"q":"hello"}' --max-usd 0.10 --network eip155:8453

生のクライアント（上級 / カスタムフロー）:

python3 skills/x402/client.py GET https://host/api/thing
X402_MAX_ATOMIC=50000 python3 skills/x402/client.py POST https://host/x402/topup

まずプリフライト（1 回のラウンドトリップ、直列の壁ではない）

ユーザーに購入の確認を求める前に、 client.payment_preflight(amount_atomic, networks=<the 402's accept networks>) を実行し、すべてのブロッカーをまとめて提示してください。これは一度に以下をチェックします: ① 署名者が到達可能か、② ウォレットポリシーの健全性 — ルールが EMPTY の ENABLED ポリシーは全拒否で、すべての署名を拒否します（新しい Privy ウォレットは 全許可にすべきです。見つかった場合は、支払い前にポリシーカードを提案して署名を得てください）、 ③ 候補レールごとの USDC 残高（直接 RPC）。資金のあるレールがない場合は、 すべてのオプションを一度に提示してください — 別の資金のあるチェーンから支払う、ブリッジ、 フィアットオンボーディング — 次の壁につながるだけの「ウォレットに資金を入れてください」だけでは 決して不十分です。ユーザーに資金を修正させ、その後ポリシーブロックを発見し、次に 依存関係エラーを 3 回の別々のラウンドトリップで発見させることは決してしないでください。

依存関係: 購入者パスには web3>=7 が必要です。マシンに古い web3 が 固定されている場合（トレーディングボットはしばしば 6.x を固定）、絶対にグローバルに アップグレードしないでください — bash skills/x402/scripts/ensure_env.sh を実行します（ゼロインタラクション、冪等）: これは PIP_USER/PYTHONPATH/ユーザーサイトの干渉を受けない隔離された .venv-x402 を作成し（venv は --without-pip + PYTHONNOUSERSITE=1 で構築）、使用するインタープリターを stdout の最後の行に出力します。payment_preflight はバージョン競合を検出し、ここを指し示します。 これはセットアップ時に行い、購入の途中では行わないでください。

マルチチェーン選択（購入者が複数の accepts を受け取る）

サービスが accepts を リスト として含む 402 を返す場合（ネットワークごとに 1 エントリ、 例: Base + Monad + Robinhood + X Layer + Solana）、購入者エージェントはユーザーに どのチェーンを使うか尋ねる必要はありません — チェーン選択は完全に自動 です、 paid_request と bazaar_pay の両方で。ロジックは:

1. payment_preflight（確認前に実行）: すべての候補レールの USDC 残高を チェックし、funded_rails[] を返します。複数のレールに資金がある場合、 自動セレクターが最良のものを選びます。資金のあるレールが 1 つもない場合は、 すべての資金調達オプションを一度に提示してください（ブリッジ、オンボーディング、別の チェーンから支払う）— 答えが「どれでもない」場合に「どのチェーン?」と尋ねることは決してしないでください。

2. 自動レールランキング — 残高を考慮、Base がデフォルト（bazaar.probe_402 の表示と paid_request の支払いで共有 — つまり、プローブ時に表示されるチェーンが実際に支払われるチェーンです）。選択順序:

   • ① 資金のあるレールを優先: そのレール上のライブ USDC 残高 ≥ 金額（直接 RPC、約 60 秒キャッシュ）。0 USDC の署名に適したチェーンが、資金のあるチェーンより選ばれることは決してないため、選択されたレールで残高不足により決済が失敗することはありません。
   • ② Base (eip155:8453) がデフォルトチェーン（資金が同点の場合、プラットフォームウォレットは Base 上に USDC を保有）。
   • ③ 静的なタイブレーク (network_rank): Base（主要 USDC チェーン） → Solana / EIP-7702 委任なしのその他の EVM（プレーンな ECDSA、例: Monad） → 委任コードありの EVM（Kernel EIP-1271）。signer_mode="eoa": Solana は除外され、すべての EVM が同等。
   • ④ 同じランク内では、より安い金額 / 最初に accept したものが優先されます。
   • 残高チェックの失敗 = 不明であり、資金なしではありません（ランキングに対してフェイルオープン）。

3. ユーザー指定チェーン (prefer_network): ユーザーが特定のチェーンで支払うよう明示的に要求した場合（例: 「Base で支払う」、「Monad を使う」）、paid_request または bazaar_pay に prefer_network="eip155:8453"（Monad の場合は "eip155:143"）を渡します。これは自動ランキングを上書きし、一致する accept を最初に選択します（402 チャレンジに存在する場合）。環境変数 X402_PREFER_NETWORK でも利用可能です。指定されたチェーンがサービスの accepts にない場合、自動ランキングがフォールバックとして引き継ぎます。一般的な CAIP-2 ID: Base eip155:8453、Monad eip155:143、Solana solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp。

   # User says "pay on Base"
   paid_request("GET", url, prefer_network="eip155:8453")
   # User says "pay on Monad"
   bazaar_pay(url, prefer_network="eip155:143")
   # User says "pay on Solana" / "use Solana"
   paid_request("GET", url, prefer_network="solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp")
   # Via env (CLI)
   X402_PREFER_NETWORK=eip155:8453 python3 skills/x402/client.py GET https://host/api
   

4. プリペイドデポジットの再試行: 最初の支払いが 402 insufficient_balance（プリペイドのトップアップが必要）をトリガーした場合、再試行は購入者がすでに選択した同じチェーン（_pick_accept の prefer_network パラメータ）にとどまります — フローの途中で別のチェーンにジャンプすることはありません。

5. 結果の検証: すべての paid_request の結果には network（実際に使用されたチェーン）と signer_type が含まれます — 支払いがどこに着地したかをユーザーが把握できるよう、常にこれらをユーザーに報告してください。

paid_request は両方の 402 フレーバーを自動検出します: V2 ヘッダーチャレンジ（PAYMENT-REQUIRED → x402 SDK パス）とプラットフォームの JSON ボディチャレンジ（accepts.pricingModel → 手動 EIP-3009 署名 → X-PAYMENT で再試行）。ライフタイム/月額サービスでは、支払い期間内の繰り返し呼び出しは検証されますが決済はされません — 結果は paid: true となり、新しいオンチェーン tx はありません。 バイヤー署名者 = デフォルトで Privy ウォレット（signer_mode="auto"）。スマート アカウントは検出され、ERC-1271 互換のパスを介して自動的に署名されます。マルチアクセプト ルーティングは、Privy がプレーン署名を行うレールを優先します（ファシリテーター互換性が最大、 EOA への資金供給が不要）：① Base（主要な USDC チェーン）→ ② 支払者が EIP-7702 コードを持たない Solana / EVM チェーン（プレーン ECDSA、例：Monad）→ ③ 委任コードを持つ EVM チェーン（Kernel EIP-1271、例：Base）を最後の手段として — 仕様上は正しいものの、一部の売り手 ファシリテーターはこれを拒否します。拒否する Base 専用の売り手に対しては、 signer_mode="eoa" を使用してください。ウォレットの委任を失効させないでください（これがガス スポンサーシップを支えています）。auto は FAIL-CLOSED です：Privy 署名者を 初期化できない場合、paid_request は別の ID から支払うのではなく例外を発生させます — セッション EOA へのフォールバックは、 allow_fallback_eoa=True / 環境変数 X402_FALLBACK_EOA=1 / signer_mode="eoa" によってのみ明示的に許可してください。 すべての結果には signer_type（"privy" | "session_eoa"）が含まれます。オプトインした フォールバックは signer_warning も設定します — どの ID が実際に支払ったかを確認するには、これらをチェックしてください。⚠️ 2 つの署名者は異なる支払者 ID です： サブスクリプション / プリペイド残高は、両者の間で引き継がれません。 同様に、EVM と Solana のプリペイド残高は別々です（異なる pay_to アドレス） — Solana への入金は EVM では使用できず、 その逆も同様です。ゲートウェイは表示上用に両方の残高を合算しますが、 入金が行われたチェーンから引き落とします。 → EOA への資金供給手順と署名者の内部詳細：セッション EOA を使用する前に references/buying-advanced.md を読んでください。

支出ガード：X402_MAX_ATOMIC（デフォルト 1_000_000 = 1 USDC）を超える署名を拒否します。⚠️ 署名 = 決済されると実際にお金を使うことになります — 不慣れなサービスへの支払いや上限の引き上げの前に、 ユーザーに確認してください。支払い済みのレスポンスボディは完全に返されます。未払い / エラーのボディは 2000 文字に制限されます（環境変数 X402_BODY_MAX、0 = 無制限）。結果には settlement.transaction（オンチェーンのトランザクションハッシュ）が含まれます — これを報告し、 トランザクション検証ルールに従って検証してください。

支払い台帳（すべての支払いはローカルに記録されます）

client.py は署名したすべての支払いを $WORKSPACE/.x402/payments.jsonl に追記します（パスの上書き：環境変数 X402_LEDGER）。各行は 1 つの JSON イベントです：signed（認可が送信された — url、amount、 payTo、payer、caller）と result（HTTP ステータス、paid、settlement tx）。caller フィールドは誰がお金を使ったかを識別します（SC_CALLER_ID / JOB_ID / pid）。そのため、バックグラウンドセッションから行われた支払いも追跡可能です。

「この USDC はどこへ行ったのか」に答えるには：まず台帳を読み、次に ウォレットのオンチェーン USDC 送金と照合してください — すべての送金が 台帳の行と一致しなければなりません。台帳への書き込みはベストエフォートであり、支払いをブロックすることはありません。

自動化されたセッションの支出ルール

• バックグラウンド / スケジュール / スポーンされたセッションは、そのタスクが明示的に予算を付与しない限り、 x402 支払いを行ってはなりません。そのセッションの予算を X402_MAX_ATOMIC に設定してください。
• 自動化されたセッションが行うすべての支払いは、その最終出力に 現れなければなりません（金額、url、settlement tx） — 台帳にのみ存在する支払いは監査可能ですが、 それでも未報告の作業としてカウントされます。
• 4xx の支払い拒否が発生した場合、新たな支払いで再試行しないでください：再試行ごとに 再度支出する可能性があります。まず診断してください。

公開有料 URL (Cloudflare Monetization Gateway 相当)

任意のローカルサービスを PUBLIC な有料 API にできます (あらゆる呼び出し元からあらゆるリソースに対して課金、アカウント / API キーは不要 — Cloudflare の Monetization Gateway と同じ機能セットを、自分のマシン上で実行できます):

1. python3 skills/x402/scripts/make_public.py --name my-api --upstream-port <port> --mode payperuse --route 'GET /api/*=$0.01' --pay-to <wallet> — output/my-api/start.py + 設定を生成します (デフォルトは --networks all: Base + Monad + Robinhood + X Layer + Solana)
2. preview(action='serve', dir='output/my-api', command='python3 start.py', port=<gateway_port>) — 注意: アップストリームがまだ起動していない場合は、同じコマンド内で起動してください
3. community-publish スキル → publish_preview(preview_id, slug='my-api') → 公開 URL
4. 価格の検出は組み込みです: GET <public-url>/.well-known/x402 が機械可読な routes/prices/payTo/networks を返します (Bazaar 互換の形状、accepts はマルチチェーンのリストです)。

公開 URL はマーケットプレイスの掲載ではありません。 手順 1〜4 はサービスを到達可能にするだけです — LIST チェーン (community-publish スキル) を完了するまで、Service Marketplace には何も表示されない (または「無料」と表示される) 状態が続きます:

5. create_paid_service(name=..., service_type=..., api_endpoint=<public paid route>, provider_wallet=..., pricing_model=..., price=..., pricing_options=[...] for multi-plan) → サービスレコード。
6. publish_service(service_id) → 公開中の有料掲載。レビューは ADVISORY (勧告) です: 任意で submit_for_review(service_id) + get_review_status() を実行すると、5 項目のセルフレポート (402 到達可能、価格の一貫性、x402 の妥当性、レスポンスの一致、ドキュメントの完全性) が得られます — これをオーナーに提示してください。公開をブロックすることは決してありません。

⚠️ LIST チェーンは必ず community-publish スキルの関数を経由しなければなりません — ゲートウェイのペイロードを手作業で構築しないでください。create_paid_service() はすべての有料フィールドを必須引数にします。フィールドが欠けた手作業のペイロードはゲートウェイに拒否されます (また、古いゲートウェイでは無料サービスが黙って作成され、後で誤解を招く 400 とともにレビューに失敗します)。

手順 5〜6 を省略することが、「なぜ有料サービスが無料として表示されるのか / マーケットプレイスに表示されないのか」の最大の原因です。

有料プロジェクト: 2 つの形態

有料プロジェクトとは、アクセスに対して課金する Starchild プロジェクトです。2 つの形態があり、プラットフォームは両方をサポートしており、同じ service_type="paid_project" + project_slug の掲載構造を共有します:

形態 1: ページ全体をペイウォールの背後に置く (ユーザーがアクセス制御を実装)

ページ自体にアクセスするために支払いが必要です。ユーザー (サービス提供者) が自身のアクセス制御を実装します — コンテンツを提供する前に支払い資格情報をチェックする、ログインのようなコンポーネントです。

プラットフォームの責務: プロジェクトを公開し、有料 API エンドポイントをマーケットプレイスに掲載します。x402 ゲートウェイが支払いプロトコル (402 チャレンジ → 決済 → 資格情報) を処理します。

ユーザーの責務: 自身のアプリにアクセス制御インターセプターを実装します:

• フロントエンドのペイウォール / ログインコンポーネント (資格情報の入力 → localStorage)
• 資格情報を検証してコンテンツを返すバックエンドエンドポイント
• 資格情報は、x402 支払いの成功後にユーザー自身の API によって発行されます — ユーザーの API が購入者に資格情報を返します

フロー:

1. Visitor opens the page → sees a paywall (user's frontend code)
2. Visitor pays via x402 (Agent or direct) → user's API returns a credential
3. Visitor enters the credential → user's backend validates it → serves content
4. Credential cached in localStorage → subsequent visits skip the paywall

プラットフォームが提供するもの:

• x402 ゲートウェイ: 402 支払いチャレンジ + オンチェーン決済を処理します
• /x402/topup エンドポイント: 購入者が支払い、API キーを取得します (timepass/サブスクリプションモード)。または x402 署名自体が資格情報になります (プラットフォームモード)
• /x402/balance エンドポイント: ユーザーのアプリはこれを使って API キーが有効かどうかを確認できます (任意 — ユーザーが独自の検証を実装することもできます)

ユーザーが実装するもの (自身のコード、自身のロジック):

• フロントエンド: ペイウォール UI、資格情報の入力、localStorage へのキャッシュ
• バックエンド: 資格情報の検証 (ゲートウェイの /x402/balance を呼び出す、独自の検証ロジックを実装する、または x402 署名を直接使用することができます)
• ペイウォールページ上の「支払い方法」ドキュメント

「Agent での支払い方法」ドキュメント

ユーザーのペイウォールページには、購入者が x402 支払いを通じてアクセス資格情報を取得する方法を説明する「支払い方法」セクションを含める必要があります。Agent は、サービスの実際の価格、期間、URL に基づいてこのドキュメントを生成するべきです。固定テンプレートをコピーしないでください。ドキュメントには以下を含める必要があります。

• 価格と支払いネットワーク（例：「Base、Monad、または Robinhood 上の $2.99 USDC/USDG — 購入者は支払いごとに 1 つのチェーンを選択」）
• Agent 経由で支払う方法（/x402/topup への x402 クライアント呼び出し）
• 直接支払う方法（X-PAYMENT ヘッダーを使用する任意の x402 互換クライアント）
• 支払い後に購入者が受け取るもの（api_key 資格情報）

フォーム 2: 無料ページ + 有料 API（フロー D）

ページは自由に閲覧できます（イントロ/ドキュメント/ランディングページ）が、API 呼び出しには費用がかかります。これがフロー D です。詳細はコミュニティ公開スキルを参照してください。アップストリームアプリは、無料のイントロページを / で提供し、有料 API を /api/* で提供します。

まとめ: 有料プロジェクト = 無料プロジェクト + 有料 API（同じパターン）

どちらのフォームも service_type="paid_project" + project_slug を使用します。違いは、ユーザーが実装する内容のみにあります。

フォーム	ページアクセス	API アクセス	ユーザーが実装するもの
ページ全体が有料	ペイウォール（ユーザーのアクセス制御）	x402 経由で有料	ペイウォール UI + 資格情報の検証
無料ページ + 有料 API	無料（イントロ/ドキュメントページ）	x402 経由で有料	追加実装は不要（ゲートウェイが処理）

プラットフォーム（x402 ゲートウェイ + コミュニティゲートウェイ）は、どちらのケースでも支払いプロトコルとマーケットプレイスへの掲載を処理します。ユーザーは、フォーム 1 のアクセス制御インターセプターを実装するだけで済みます。

たった1つの URL から任意の x402 サービスを利用する

サービス URL だけが与えられた場合（ドキュメントもガイダンスもなし）、次の手順でオンボーディングと検証を行います。必要なものはすべてプロトコル内で自己記述されています。

1. 検出（支払いなし）: 支払いヘッダーなしで GET <url> を実行します。402 レスポンスがそのまま価格表です。accepts はリスト（マルチ accepts、ネットワークごとに1エントリ）であり、各エントリには amount（アトミック USDC）、pricingModel、network、asset、payTo が含まれます。支払いに使うチェーンを1つ選びます。マルチプランサービスの場合、plans マップに各オプションの accepts が格納されています。任意で GET <base>/.well-known/x402 を実行すると、すべてのルート・価格・ネットワークの機械可読なインデックスが取得できます。
   • amount == "0" の場合（またはマーケットプレイスの無料ステータスが有効な場合）、そのサービスは期間限定の無料プロモ中です。identity 用に amount 0 で署名します。決済は行われないことを想定してください。これは一時的なもので、free_end 以降は同じ URL が再び定価を返します。
2. プランのプローブ（支払いなし、マルチプランのみ）: X-Pricing-Model: <plan> を付けて未払いの GET を繰り返します。各 402 はそのプランの正確な amount を返します。不明なプランは HTTP 400 を返し、有効なプランを列挙します。
3. 支払いと呼び出し: client.paid_request("GET", url, max_amount_atomic=<cap>) がフロー全体（402 → EIP-3009 署名 → X-PAYMENT を付けて再試行）を処理します。pricing_model="<plan>" でプランを選択します。支払者はデフォルトで Privy ウォレットです（signer_mode="auto"）。有償の quote の場合、ウォレットはサービスのネットワーク上に USDC を保持している必要があります。無料プロモの amount 0 の場合は、署名用ウォレットがあれば十分です（定価分の USDC は不要）。セッション EOA への入金が必要なのは、signer_mode="eoa" を固定した場合、または結果が signer_type: "session_eoa" を報告した場合のみです（上記の Buyer side を参照）。cap は支出ガードです（無料期間中は 0 でも構いません）。実際にお金を支払う前にユーザーに確認してください。結果の signer_type を確認してください。実際に支払った identity がどれかを示します。Privy 署名者が利用できない場合、auto はセッション EOA から黙って支払うのではなく（fail-closed で）例外を発生させます。signer_warning が表示されるのは、フォールバックが明示的に許可されていた場合のみです。
4. 課金セマンティクスの検証（サブスクリプションモード）: もう一度呼び出します。結果は 200 で、新しい決済がない必要があります（paid: true、新しい tx なし）。マルチプランサービスでは、1つのプランを保持したまま別のプランを要求しても再課金されてはなりません。手順 3 の settlement.transaction がオンチェーンの証明です。これを報告し、トランザクション検証ルールに従って検証してください。無料プロモ中は、手順 3 は初回アクセスでも新しい決済がないことを示すはずです。

同じ手順は、任意の x402 デプロイメントのスモークテストとしても機能します。手順 1〜2 は無料で、チャレンジコントラクトを検証します。手順 3〜4 は決済とアクセス計測をエンドツーエンドで検証します。

検出と支払い — まずマーケットプレイス、次に CDP

購入者のフローは マーケットプレイス優先 です。トラックを統合しないでください。サードパーティの x402 ディレクトリをスクレイピングしないでください。

ステップ	ルール
1. 検出	discover_services(query) または community-publish.explore_marketplace を優先します。CDP（bazaar_search）は、マーケットプレイスにヒットがない場合のフォールバックです。
2. 支払い URL の解決	掲載済みサービス → community.iamstarchild.com/proxy/{service_id}（+ パス）または内部の /{user}-{slug}/...。プロキシが存在する場合、リストの生の外部 URL に絶対に支払わないでください。
3. 支払い	bazaar_pay(url) はマーケットプレイスのプロキシに再解決し、その後 probe_402 → paid_request を実行します。コミュニティは 透過プロキシ を行い、HTTP 200 で記帳 します。未掲載の外部 URL は 拒否 されます — まずマーケットプレイスにサービスを掲載し、その後そのプロキシ URL に支払ってください。

import sys; sys.path.insert(0, "/data/workspace/skills/x402")
from bazaar import discover_services, resolve_marketplace, probe_402, bazaar_pay

discover_services("weather", limit=5)          # marketplace first, CDP fallback
resolve_marketplace("https://example.com/api") # → pay_url via community when listed
bazaar_pay(url, max_usd=0.01)                  # proxy-first pay; refuse non-standard

probe_402 / bazaar_pay は、既知のネイティブ USDC レール（bazaar.PAYABLE_USDC を参照）上の standard-v2 exact のみを支払います: Base、Polygon、Arbitrum、World Chain、Solana mainnet、Monad、Avalanche、Ethereum、Optimism、Linea、Celo、Unichain。 マルチアセプト → Privy ネイティブのレールを優先します（Base → Solana/ノーコード EVM → 委任 EVM。購入者署名者のセクションを参照）。同じセレクター（client.network_rank）が bazaar の probe_402 の順序を決定するため、プローブ時に表示されるレールが auto が実際に支払うレールです。signer_mode="eoa" は SVM 署名者を決して登録せず、Solana のアセプトをハードフィルタリングします — 固定されたセッション EOA 支払者アイデンティティが代用されることは決してありません。結果と元帳の行には、実際に選択された network/payer/signer_type が含まれます（Solana の決済では、支払者として Privy Solana アドレスが報告されます）。Solana は Privy wallet_sol_sign（base64 の生メッセージ）を介して署名します。未対応: EURC/代替ステーブル、テストネット。その他の形式（wrong-rail、tx-hash、non-standard、no-payment）は、いかなる署名の前にも拒否されます。購入者が署名し、売り手のファシリテーターが決済します。

エラーと診断

支払いまたはゲートウェイが失敗した場合 → 必ず references/troubleshooting.md を読んでください（エラー契約、ファシリテーターの検証エラー、セキュリティモデル、ポート所有権のチェック、プロキシ設定）。いつでも簡単な e2e チェック: python3 skills/x402/scripts/verify_setup.py（資金不要。--funded を付けると実際の決済テストが追加されます）。

セットアップ

Python SDK は x402 v2.10+ です。依存関係は自動インストールされません: マシンごとに一度 bash skills/x402/setup.sh を実行してください（再起動時に再インストールされるよう、/data/workspace/setup.sh にも追記してください）。