Bazaar — サービスディスカバリー

Bazaar とは?

Bazaar は x402 のディスカバリ層です。「ここで何が買えて、いくらするのか?」に答えます。エージェントは /.well-known/x402.json で、サービス、価格、入出力スキーマの構造化カタログを閲覧します。

仕組み

/.well-known/x402.json を公開します:

{
  "x402Version": 2,
  "name": "Your Service",
  "description": "What your service does",
  "network": "base",
  "facilitator": "coinbase",
  "payTo": "0xYourWallet",
  "services": [
    {
      "method": "POST",
      "path": "/api/generate",
      "description": "Generate content",
      "amount": "100000",
      "discoverable": true,
      "outputSchema": {
        "input": {
          "type": "http",
          "method": "POST",
          "bodyFields": {
            "prompt": { "type": "string", "required": true }
          }
        },
        "output": {
          "type": "json",
          "schema": { "result": { "type": "string" } }
        }
      }
    }
  ]
}

必須フィールド

x402Version — 仕様バージョン(2 を使用。スキャナは 1 も受け付けます — 下記参照)
name — プロバイダ名
network — ブロックチェーン(例: base、または v2 では CAIP 形式の eip155:8453)
facilitator — 決済プロバイダ(例: coinbase)
payTo — 支払いを受け取るウォレットアドレス
services[] — method と path を持つ有料エンドポイントの配列

v1 と v2

x402 v2 は 2025 年 12 月にローンチされ、現行の仕様ですが、v1 のサーバーも依然として多く存在します。AgentGrade はどちらも受け付けます。プロトコルレベルの違いをすべて挙げます:

ヘッダー名: v1 は X- プレフィックス付きのヘッダー(リトライリクエストの X-PAYMENT、成功時の X-PAYMENT-RESPONSE)を使っていました。v2 は X- プレフィックスを廃止します(PAYMENT-SIGNATURE、PAYMENT-RESPONSE)— X- の慣例は 2012 年に RFC 6648 で非推奨になりました。
チャレンジの置き場所: v1 は決済チャレンジを 402 レスポンスの JSON ボディ に入れていました。v2 はそれを PAYMENT-REQUIRED レスポンスヘッダー(base64 エンコードされた JSON)に移し、ボディは人間向けの paywall ページに使えるようにしています。
amount フィールドのリネーム: v1 の accepts[] エントリは価格に maxAmountRequired を使っていました。v2 はこれを amount にリネームしました。
resource の形: v1 は resource(文字列 URL)、description、mimeType を各 accepts[] エントリの中に入れていました。v2 はこれらを url、description、mimeType フィールドを持つトップレベルの resource オブジェクトに移動 — 402 レスポンス全体に対して一度だけ宣言され、accepts エントリごとに重複しません。
チェーンの識別: v1 は network フィールドに "base" のような自由文字列を使っていました。v2 は CAIP ID(例: eip155:8453)で標準化し、同じフィールドで非 EVM チェーンやオフチェーンレールにも対応できます。
動的な payTo: v1 はディスカバリカタログでサービスごとに静的な受取先を 1 つ宣言していました。v2 はサーバーがリクエストごとに payTo を計算できるため、マーケットプレイスが個々の販売者へ支払いを振り分けるのに便利です。
セッション: v1 はすべての呼び出しで決済フロー全体を要求しました。v2 はウォレットベースのセッション(Sign In With X402)を追加し、一度署名すればサーバーがセッションを発行し、以降の呼び出しはハンドシェイクをスキップします。

新しく作るなら v2 で作りましょう。既存の v1 サーバーを監査している場合、スキャナは v1 のままでも減点しません — が、v2 の違いは実際の効率向上として効いてきます。

live 402 ヘッダーの extensions.bazaar

エージェントが支払いなしで有料エンドポイントを呼び出すと、サーバーは base64 エンコードされた Payment-Required ヘッダー付きの HTTP 402 を返します。そのヘッダー内の JSON ペイロードに extensions.bazaar を宣言することで、エージェントはこのエンドポイントが発見可能なカタログに含まれていることを知ることができます。base64 エンコード前の JSON ペイロード(v2 形式):

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "amount": "100000",
      "asset": "0xUSDC...",
      "payTo": "0xYourWallet",
      "maxTimeoutSeconds": 60
    }
  ],
  "extensions": {
    "bazaar": { "discoverable": true }
  }
}

extensions.bazaar が無いと、402 を受け取ったエージェントは、このエンドポイントが /.well-known/x402.json にもカタログされているという手掛かりが何も得られません — 閲覧可能なサービスの一部としてではなく、単発の有料エンドポイントとして扱ってしまう恐れがあります。

仕様の成熟度

x402 v2 の一部。 Bazaar ディスカバリは x402 仕様内で定義されています。

さらに詳しく

x402.org — x402 プロトコル仕様 (Bazaar を含む)