V1からV2への移行

x402 V1からV2への主要な変更点と移行手順を解説します。

主な変更点

• ヘッダー名の変更：X-PAYMENT → PAYMENT-SIGNATURE
• ネットワーク識別子の標準化：独自文字列形式 → CAIP-2標準（例：base-sepolia → eip155:84532）
• パッケージ構成の変更：スコープ付きパッケージ名に統一（@x402/core・@x402/express等）
• APIの変更：ビルダーパターンベースの登録システムに移行

ネットワーク識別子の対応表

バイヤー向け移行

TypeScript

V1

import { withPaymentInterceptor } from "x402-axios";

const client = withPaymentInterceptor(axios.create(), walletClient);

V2

import { wrapAxiosWithPayment } from "@x402/axios";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";

const client = new x402Client(signer)
  .register("eip155:*", new ExactEvmScheme());

const axiosClient = wrapAxiosWithPayment(axios.create(), client);

Python

V1

from x402.clients.httpx import X402Client

V2

from x402.http.clients import x402AsyncClient
from x402.mechanisms.evm import EthAccountSigner

signer = EthAccountSigner(account)
client = x402AsyncClient(signer)

セラー向け移行

ルート設定がシンプルなオブジェクトから明示的な RouteConfig / PaymentOption モデルに移行します：

V1

{
  "GET /weather": {
    price: "$0.001",
    network: "base-sepolia",
    address: "0xYourAddress",
  }
}

V2

{
  "GET /weather": {
    accepts: [
      {
        scheme: "exact",
        price: "$0.001",
        network: "eip155:84532",  // CAIP-2形式
        payTo: "0xYourAddress",   // payToに変更
      },
    ],
  }
}

トラブルシューティング

• パッケージを@x402/スコープ付き名称に更新する
• ネットワーク識別子をCAIP-2形式に変換する
• ファシリテーターURLが環境（テストネット/メインネット）と一致しているか確認する
• payToフィールドを追加する（V2では必須）