{
  "lang": "ja",
  "ページ": "https://x402-catalog-history.ai-business-surface.workers.dev/ja/schema-change",
  "title": "x402 のスキーマ変更を壊れる前に検知する：互換判定4経路の実測",
  "h1": "x402 のスキーマ変更を壊れる前に検知する — 宣言・差分・互換判定の実測",
  "description": "x402 の API 変更で連携が壊れる前に知る方法を、公開URLへの無課金 GET / POST の実測値で示します。402 の出力宣言を読む /contract、前回からの差分を取る /changes、v1/v2 の読み方を判定する /compat-check、schema と actual を突き合わせる /compat（POST 専用）。4経路の 402・価格・本文サイズ・応答時間と、無料サンプルの実測を表にします。",
  "検索語": "x402 schema change / api breaking change detector",
  "読者の問い": "この API の変更は自分の連携を壊すのか。壊れる前に、どの経路で何を見ればよいのか。",
  "実測日": "2026-10-18 JST",
  "実測": {
    "caption": "x402 の変更検知に使う4経路の実測（2026-10-18 JST・公開URL・支払いなし）",
    "columns": [
      "経路",
      "呼び方",
      "応答",
      "宣言価格（USDC）",
      "本文",
      "応答時間"
    ],
    "rows": [
      [
        "/compat-check?url=…",
        "GET",
        "402",
        "0.02",
        "22,470 B",
        "530 ms"
      ],
      [
        "/compat",
        "GET（誤り）",
        "405",
        "—",
        "194 B",
        "401 ms"
      ],
      [
        "/compat（schema と actual）",
        "POST",
        "402",
        "0.02",
        "16,285 B",
        "662 ms"
      ],
      [
        "/changes",
        "GET",
        "402",
        "0.02",
        "15,351 B",
        "201 ms"
      ],
      [
        "/contract?url=…",
        "GET",
        "402",
        "0.02",
        "21,985 B",
        "198 ms"
      ],
      [
        "/contract/sample?url=…",
        "GET",
        "200（無料）",
        "—",
        "1,855 B",
        "162 ms"
      ],
      [
        "/contract/sample?url=<自社 /history>",
        "GET",
        "200（無料）",
        "—",
        "2,779 B",
        "521 ms"
      ],
      [
        "/status",
        "GET",
        "200（無料）",
        "—",
        "16,988 B",
        "512 ms"
      ]
    ],
    "note": "/compat は POST 専用です。GET は 405（194 B）、schema / actual を欠いた POST は 400（171 B）で、どちらも課金されません。正しい POST だけが 402 を返しました。402 の本文 accepts[0] は scheme=exact / network=base / maxAmountRequired=20000 / asset=0x8335… / payTo=0x6f60… / maxTimeoutSeconds=60 を宣言し、extra は name と version の2キーでした。"
  },
  "見出し": [
    "結論",
    "実測（2026-10-18 JST）",
    "/compat は GET では呼べない（405 → 400 → 402）",
    "無料で先に読める宣言（/contract/sample の実測）",
    "変更検知の順番",
    "次の一歩"
  ],
  "本文": [
    {
      "見出し": "結論",
      "html": "<p>x402 の変更で連携が壊れるかは、<strong>「宣言」「差分」「互換判定」の3つを別々に見る</strong>と切り分けられます。宣言は無料の <code>/contract/sample</code> で読めます。差分は <code>/changes</code>、v1/v2 の読み方は <code>/compat-check</code>、schema と実データの突き合わせは <code>/compat</code> が返します。後ろの3本は 0.02 USDC で、<strong>購入前に 402 の宣言だけは無料で確認できます</strong>。</p>\n<p>最初に覚えることは1つです。<strong><code>/compat</code> は GET では呼べません</strong>。GET は 405、本文を欠いた POST は 400 で、正しい <code>{schema, actual}</code> を POST したときだけ 402（0.02 USDC）になります。</p>"
    },
    {
      "見出し": "実測（2026-10-18 JST）",
      "html": "<p>公開URLへ支払いなしの GET / POST を1回ずつ投げた実測です。応答時間は wall clock、本文はバイト数、金額は USDC の小数6桁です。どの呼び出しでも送金は発生していません。</p>\n<table>\n<thead><tr><th>経路</th><th>呼び方</th><th>応答</th><th>宣言価格（USDC）</th><th>本文</th><th>応答時間</th></tr></thead>\n<tbody>\n<tr><td><code>/compat-check?url=…</code></td><td>GET</td><td>402</td><td>0.02</td><td>22,470 B</td><td>530 ms</td></tr>\n<tr><td><code>/compat</code></td><td>GET（誤り）</td><td>405</td><td>—</td><td>194 B</td><td>401 ms</td></tr>\n<tr><td><code>/compat</code>（schema と actual）</td><td>POST</td><td>402</td><td>0.02</td><td>16,285 B</td><td>662 ms</td></tr>\n<tr><td><code>/changes</code></td><td>GET</td><td>402</td><td>0.02</td><td>15,351 B</td><td>201 ms</td></tr>\n<tr><td><code>/contract?url=…</code></td><td>GET</td><td>402</td><td>0.02</td><td>21,985 B</td><td>198 ms</td></tr>\n<tr><td><code>/contract/sample?url=…</code></td><td>GET</td><td>200（無料）</td><td>—</td><td>1,855 B</td><td>162 ms</td></tr>\n<tr><td><code>/contract/sample?url=&lt;自社 /history&gt;</code></td><td>GET</td><td>200（無料）</td><td>—</td><td>2,779 B</td><td>521 ms</td></tr>\n<tr><td><code>/status</code></td><td>GET</td><td>200（無料）</td><td>—</td><td>16,988 B</td><td>512 ms</td></tr>\n</tbody>\n</table>\n<p>同じ時刻に測った <code>/x402-check</code> は 200・1,391 B・142 ms でした。402 を返した3本（<code>/compat-check</code>・<code>/compat</code>・<code>/contract</code>）は、本文 <code>accepts[0]</code> に <code>scheme / network / maxAmountRequired / resource / mimeType / payTo / maxTimeoutSeconds / asset / extra</code> の9項目を持ち、<code>extra</code> は <code>name</code> と <code>version</code> の2キーでした。</p>"
    },
    {
      "見出し": "/compat は GET では呼べない（405 → 400 → 402）",
      "html": "<p>同じ <code>/compat</code> でも、呼び方で応答が3つに分かれました。ここは実際に踏んで確かめた順番です。</p>\n<ol>\n<li><strong>GET すると 405</strong>（194 B・401 ms）。経路はあるが、GET は受け付けません。</li>\n<li><strong>空の JSON を POST すると 400</strong>（171 B・143 ms）。本文は <code>{\"error\":\"invalid_request\",\"message\":\"The body must be a JSON object with exactly the fields schema and actual.\",\"required\":[\"schema\",\"actual\"]}</code> で、<code>schema</code> と <code>actual</code> の2つが必要だと分かります。ここまで課金はありません。</li>\n<li><strong><code>{schema, actual}</code> を POST すると 402</strong>（16,285 B・662 ms・0.02 USDC）。<code>schema</code> は JSON Schema、<code>actual</code> は検証したい実データです。402 を通過した後は <code>status</code> / <code>mismatchCount</code> / <code>issues</code> / <code>checker</code> / <code>inputSha256</code> が返る形です。</li>\n</ol>\n<p>つまり「変更で壊れたか」を1回で見たいときは、<strong>GET ではなく POST に <code>schema</code> と <code>actual</code> を入れる</strong>のが正しい呼び方です。GET の 405 を「相手が死んでいる」と読み違えないでください。</p>"
    },
    {
      "見出し": "無料で先に読める宣言（/contract/sample の実測）",
      "html": "<p>有料の <code>/contract</code> に入る前に、<code>/contract/sample?url=…</code> が同じ形を無料で返します。2つの対象で測ると、返る内容が変わることが分かります。</p>\n<table>\n<thead><tr><th>対象</th><th>応答</th><th>本文</th><th>宣言された出力</th><th>弱点の申告</th></tr></thead>\n<tbody>\n<tr><td><code>https://example.com</code>（x402 ではない）</td><td>200</td><td>1,855 B</td><td>0件（<code>no_output_contract</code>）</td><td>—</td></tr>\n<tr><td>自社の <code>/history</code>（x402）</td><td>200</td><td>2,779 B</td><td>5件（<code>changes</code> / <code>latest</code> / <code>period</code> / <code>product_id</code> / <code>snapshot</code>）</td><td><code>error_shape_undeclared</code></td></tr>\n</tbody>\n</table>\n<p>自社 <code>/history</code> のサンプルは <strong>18キー</strong>を返し、<code>output.fields</code> は <strong>5件</strong>、<code>fields_from</code> は <code>properties</code>、<code>declared_keys</code> は <code>properties / required / type</code> の3つでした。<code>challenge_present</code> は <code>true</code> で、<code>weakness</code> には「失敗時の形が宣言されていない」という <code>error_shape_undeclared</code> が入っています。<strong>宣言が無いことを「変更が無い」と読み替えない</strong>ための材料です。</p>"
    },
    {
      "見出し": "変更検知の順番",
      "html": "<ol>\n<li><strong>生きているか（無料）</strong>。<code>/status</code> は 200・16,988 B・512 ms で、経路ごとの納品記録を返します。ここで 402 が返らない経路は、変更以前に応答していません。</li>\n<li><strong>今の宣言を読む（無料）</strong>。<code>/contract/sample?url=&lt;URL&gt;</code> で、出力の項目名・型・必須・弱点を確認します。この時点の形を控えておくと、次に測ったときの比較対象になります。</li>\n<li><strong>前回との差分（0.02 USDC）</strong>。<code>/changes</code> は同じ保存領域の期間差分を返します。<code>added</code> と <code>changed</code> は別物で、変わらなかった件数は「変化が無い」の証拠になります。</li>\n<li><strong>v1/v2 の読み方（0.02 USDC）</strong>。<code>/compat-check?url=&lt;URL&gt;</code> は、対象が実際に返した 402 を v2 クライアントと v1 クライアントのそれぞれで読めるか、必須項目の欠けは何かを1つの判定にまとめます。購入が parse error で落ちたときの切り分けに使います。</li>\n<li><strong>schema と実データ（0.02 USDC・POST）</strong>。<code>/compat</code> に <code>{schema, actual}</code> を POST し、<code>mismatchCount</code> と <code>issues</code> を見ます。変更後の実データが古い schema に合うかを、支払い後に自分で確かめる用途です。</li>\n</ol>\n<p>すべてを毎回買う必要はありません。まず無料の2つ（<code>/status</code>・<code>/contract/sample</code>）で「今の形」を控え、差分が要るなら <code>/changes</code>、クライアント側で落ちるなら <code>/compat-check</code>、データの整合なら <code>/compat</code> と切り分けます。</p>"
    },
    {
      "見出し": "次の一歩",
      "html": "<p>まず無料の <a href=\"https://x402-catalog-history.ai-business-surface.workers.dev/contract/sample?url=https%3A%2F%2Fexample.com\"><code>/contract/sample?url=https://example.com</code></a> を叩いて、宣言が無いときの返り方（<code>no_output_contract</code>）を見てください。次に対象の URL を変えて、出力の項目名と必須を控えます。課金は起きません。そのうえで差分が要るなら <a href=\"https://x402-catalog-history.ai-business-surface.workers.dev/changes\"><code>/changes</code></a>（0.02 USDC）、v1/v2 の判定が要るなら <a href=\"https://x402-catalog-history.ai-business-surface.workers.dev/compat-check?url=https%3A%2F%2Fexample.com\"><code>/compat-check</code></a>（0.02 USDC）です。</p>\n<p>相手の端点そのものが生きているか・いくら請求するかは、<a href=\"https://x402-catalog-history.ai-business-surface.workers.dev/ja/check-before-paying\"><code>/ja/check-before-paying</code></a> の手順（無課金 GET）で先に確認できます。</p>"
    }
  ],
  "一覧": "https://x402-catalog-history.ai-business-surface.workers.dev/ja"
}