x402決済 2026 v2の実装と精算検証

x402決済は、APIの402レスポンスに決済条件を含めて実装します。Node.jsとテスト用ウォレットを用意してください。まず、Base Sepoliaでv2の署名と精算を検証します。有料レスポンスは、精算が成功した後に返すように設定してください。

金額・チェーン情報は、出典としてリンクしたx402・Base・Circleの公式ドキュメントに基づいています。

実習の準備とインストール

APIを変更できる開発環境とテスト用ウォレットを用意してください。サンプルはNode.js 22とx402 SDK 2.28.0を基準に構成しています。インストール構成は公式販売者ガイドに従います。

1. 決済を受け取るEVMウォレットのアドレスを用意してください。
2. 決済用のテストウォレットを別途用意してください。
3. 決済用ウォレットにBase Sepoliaのテスト用USDCを用意してください。
4. 以下のコマンドで実習用プロジェクトを作成してください。
5. 以降のTypeScriptファイルを同じフォルダーに保存してください。

mkdir x402-demo
cd x402-demo
npm init -y
npm pkg set type=module
npm install --save-exact [email protected] [email protected] @x402/[email protected] @x402/[email protected] @x402/[email protected] @x402/[email protected]
npm install --save-dev --save-exact typescript tsx @types/node @types/express

受取側のサーバーに、受取ウォレットの秘密鍵は必要ありません。決済用の秘密鍵は、クライアントプロセスでのみ読み込む構成にしてください。ウォレットの署名方式は公式購入者ガイドに基づいています。

このサンプルの検証範囲は、型チェックと模擬的な決済フローです。実際にテストネットでの送金まで完了したサンプルではありません。以下の実行手順で、オンチェーンの結果を直接確認してください。

×

重複リクエストの復旧をテストし、決済の再試行で二重精算が起きないことを確認しましょう。

x402 v1とv2の比較

v2を実装する際は、ヘッダーと本文のフィールドを両方そろえる必要があります。ヘッダー名だけを変更しても、データ構造が一致しません。次の表は公式移行ガイドに基づいています。

v1で決済条件を渡す場所は、HTTP v1仕様に明記されています。v2で標準となる受け渡し場所は、PAYMENT-REQUIREDヘッダーです。実装によっては本文も返す場合がありますが、ヘッダーを基準に処理してください。

HTTP v2仕様では、ステータスコードを次のように説明しています。

サーバーは、HTTP 402「Payment Required」ステータスコードを使って、決済が必要であることを示します。

出典：x402 HTTP v2仕様

v2の決済ヘッダーは、JSONをBase64でエンコードした値です。Base64は暗号化方式ではありません。外部向けサービスではHTTPSを使用してください。

HTTP 402リクエストと決済の順序

この実習では、EVMのexact方式の基本的な承認フローを使用します。exactは、指定された金額を決済する方式です。順序はx402 v2の基本仕様に従います。

1. クライアントが決済情報なしで有料APIをリクエストします。
2. サーバーがHTTP 402とPAYMENT-REQUIREDを返します。
3. クライアントがacceptsから許可された条件を選択します。
4. SDKが、選択した条件に合う決済承認に署名します。
5. クライアントがPAYMENT-SIGNATUREを付けて再リクエストします。
6. サーバーがfacilitatorの/verifyで承認を検証します。
7. 検証を通過すると、サーバーがリソースの処理を実行します。
8. サーバーが/settleで精算をリクエストします。
9. 精算が成功した後、有料の本文とPAYMENT-RESPONSEを返します。

この順序は、すべての決済方式に共通する固定の順序ではありません。v2には、精算のタイミングが異なるフローも定義されています。以下のコードでは、基本的なauthorizationフローのみを許可します。

Resource serverとfacilitatorの役割

Resource serverは、価格とコンテンツへのアクセス条件を決定します。Facilitatorは、決済の検証と精算を担当します。役割の区分は公式facilitatorドキュメントに基づいています。

/verifyは、オンチェーンの状態を変更しない検査です。そのため、検証の成功は入金の完了を意味しません。検証後も、残高や承認状態が変わる可能性があります。

検証や精算に失敗した場合は、有料の本文をブロックしてください。成功を確認できなかったときにブロックする処理を、fail-closedと呼びます。この動作は公式Express実装でも確認できます。

Baseメインネットとテストネットの比較

初回の実行では、Base Sepoliaだけを使用してください。Circleは、テストネットのUSDCに金銭的価値がないと明記しています。アドレスはCircleのUSDCコントラクト一覧に基づいています。

Chain IDとRPCは、Baseネットワークドキュメントで確認してください。同じウォレットアドレスでも、チェーンが異なれば残高は別です。テストネットでの成功を、実際の売上として記録してはいけません。

テスト用USDCは、Circle Testnet Faucetでリクエストできます。ネットワークにはBase Sepoliaを選択してください。受取アドレスには、決済用テストウォレットのアドレスを入力します。

Node.jsによる有料APIの実装

有料ルートの前にpaymentMiddlewareを組み込んでください。以下のサンプルは、呼び出し1回あたり0.001 USDCを要求します。金額は、公式販売者ガイドの価格例を使用しています。（確認値：呼び出し1回あたり0.001 USDC・出典：docs.x402.org・2026-10-28確認）

サーバーファイル

次のコードをserver.tsとして保存してください。サーバーは、ローカルインターフェースでのみリクエストを受け付けます。受取アドレスは、環境変数PAY_TOから読み込みます。

import express from "express";
import { getAddress, zeroAddress } from "viem";
import { paymentMiddleware } from "@x402/express";
import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";

const payTo = getAddress(process.env.PAY_TO ?? "");
if (payTo === zeroAddress) throw new Error("Invalid payTo");
const network = "eip155:84532";
const resourceServer = new x402ResourceServer(
  new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" }),
).register(network, new ExactEvmScheme());

const app = express();
app.use((_req, res, next) => {
  res.setHeader("Cache-Control", "private, no-store");
  next();
});
app.use(paymentMiddleware({
  "GET /paid-data": {
    accepts: [{ scheme: "exact", price: "$0.001", network, payTo }],
    description: "Sample paid JSON",
    mimeType: "application/json",
  },
}, resourceServer));
app.get("/paid-data", (_req, res) => {
  res.json({ content: "Paid sample content" });
});
app.listen(4021, "127.0.0.1");

https://x402.org/facilitatorは、公式ガイドに掲載されているテスト用のアドレスです。このサンプルでは、Base Sepoliaでの精算に使用します。本番用facilitatorの選択については、販売者ガイドのメインネット手順を確認してください。

価格計算の例

サンプルの価格は、USDCの最小単位で1000です。USDCの小数点以下の桁数は6桁です。SDKによる価格変換は、EVMサーバー実装に基づいています。

0.001 USDC × 10^6 = 1000 최소 단위

priceはSDKの設定値です。実際のv2決済条件では、amountが渡されます。整数の金額は、文字列またはbigintとして比較してください。

サーバーの起動と402の確認

1つ目のBashターミナルでサーバーを起動してください。入力する値は、秘密鍵ではなく公開の受取アドレスです。実行中は、このターミナルを開いたままにします。

read -r -p '수취 지갑 주소: ' PAY_TO
export PAY_TO
npx tsx server.ts

2つ目のターミナルから、決済なしのリクエストを送信してください。以下のコマンドは、決済に署名しません。HTTPステータスと、デコードした決済条件を出力します。

node --input-type=module <<'JS'
const response = await fetch("http://127.0.0.1:4021/paid-data");
const header = response.headers.get("PAYMENT-REQUIRED");
console.log(response.status);
console.log(header && JSON.parse(
  Buffer.from(header, "base64").toString("utf8")
));
JS

正常な決済なしのレスポンスは、HTTP 402です。出力された条件を、上の表と照合してください。有料コンテンツがそのまま返される場合は、ルートの保護設定から修正します。

決済条件の選択とクライアントの実装

許可した条件にのみ署名するように、クライアントを制限してください。このサンプルでは、Base SepoliaのUSDCによる指定価格の決済だけを許可します。決済オプションのフィルターには、公式x402Client実装のregisterPolicyを使用します。

1. 以下のコードをclient.tsとして保存してください。
2. 次の節のcheck-transfer.tsも保存してください。
3. 2つのファイルを用意してから、実行手順に進んでください。

import { writeFile } from "node:fs/promises";
import { getAddress, zeroAddress, type Hex, type Hash } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { decodePaymentResponseHeader } from "@x402/core/http";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { checkTransfer } from "./check-transfer.js";

const key = process.env.EVM_PRIVATE_KEY ?? "";
if (!/^0x[0-9a-fA-F]{64}$/.test(key)) throw new Error("Invalid test key");
const signer = privateKeyToAccount(key as Hex);
const payTo = getAddress(process.env.PAY_TO ?? "");
if (payTo === zeroAddress) throw new Error("Invalid payTo");
const network = "eip155:84532";
const token = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
const client = new x402Client().register(network, new ExactEvmScheme(signer));
client.registerPolicy((version, options) => version === 2
  ? options.filter(r =>
      r.scheme === "exact" && r.network === network &&
      r.asset.toLowerCase() === token.toLowerCase() &&
      r.payTo.toLowerCase() === payTo.toLowerCase() && r.amount === "1000" &&
      (!r.extra?.assetTransferMethod || r.extra.assetTransferMethod === "eip3009") &&
      (!r.extra?.paymentFlow || r.extra.paymentFlow === "authorization"))
  : []);

const paidFetch = wrapFetchWithPayment(fetch, client);
const response = await paidFetch("http://127.0.0.1:4021/paid-data", {
  redirect: "error",
});
const raw = response.headers.get("PAYMENT-RESPONSE");
if (!raw) throw new Error(`No settlement receipt: HTTP ${response.status}`);
const settlement = decodePaymentResponseHeader(raw);
await writeFile("settlement.json", JSON.stringify(settlement, null, 2));
if (!response.ok || !settlement.success || settlement.network !== network) {
  throw new Error("Payment unresolved; inspect settlement.json before retrying");
}
const evidence = await checkTransfer(
  network, settlement.transaction as Hash, signer.address, payTo, 1000n,
);
await writeFile("transfer.json", JSON.stringify(evidence, null, 2));
console.log(await response.text());

wrapFetchWithPaymentが、402の処理と署名付きの再リクエストを担当します。使い方は公式fetchサンプルに従います。許可された決済条件がなければ、決済の生成を中止します。

AIエージェントでも、このクライアントを使用できます。ただし、呼び出し1回あたりの価格制限は、累積支出の制限ではありません。エージェントによる繰り返し呼び出しの予算は、別途管理してください。

USDC Transferイベントの検証

精算結果のトランザクションハッシュを使って、USDCの送金ログを確認してください。トランザクションの成功状態だけでは、受取人まで確認できません。Transferのフィールドは、ERC-20標準に基づいています。

検証には、次の項目が必要です。

以下のコードをcheck-transfer.tsとして保存してください。照会には、viemのgetTransactionReceiptを使用します。イベントの解釈は、parseEventLogsに基づいています。

import {
  createPublicClient, http, getAddress, parseEventLogs,
  erc20Abi, type Address, type Hash,
} from "viem";
import { base, baseSepolia } from "viem/chains";

const configs = {
  "eip155:84532": {
    chain: baseSepolia,
    rpc: "https://sepolia.base.org",
    token: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  },
  "eip155:8453": {
    chain: base,
    rpc: "https://mainnet.base.org",
    token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  },
} as const;

export async function checkTransfer(
  network: keyof typeof configs, hash: Hash,
  payer: Address, payTo: Address, amount: bigint,
) {
  const cfg = configs[network];
  const rpc = createPublicClient({ chain: cfg.chain, transport: http(cfg.rpc) });
  if (await rpc.getChainId() !== cfg.chain.id) throw new Error("Wrong chain");
  const receipt = await rpc.getTransactionReceipt({ hash });
  if (receipt.status !== "success") throw new Error("Transaction failed");
  const logs = parseEventLogs({
    abi: erc20Abi,
    eventName: "Transfer",
    logs: receipt.logs.filter(
      log => getAddress(log.address) === getAddress(cfg.token),
    ),
    strict: true,
  });
  const transfer = logs.find(log =>
    getAddress(log.args.from) === getAddress(payer) &&
    getAddress(log.args.to) === getAddress(payTo) &&
    log.args.value === amount,
  );
  if (!transfer) throw new Error("Matching USDC Transfer not found");
  return {
    network, transaction: hash, logIndex: transfer.logIndex,
    blockHash: receipt.blockHash, blockNumber: receipt.blockNumber.toString(),
  };
}

この関数は、そのトランザクションでUSDCが送金された事実を確認します。特定のAPI注文に対応するものかどうかは、別途確認する必要があります。本番サーバーでは、保存済みの注文条件を比較値として使用してください。

クライアントがアップロードしたtransfer.jsonを、アクセス許可の証拠として信用してはいけません。このサンプルのサーバーは、facilitatorの検証・精算結果を使用します。独立した照会をアクセス許可の条件にする場合は、サーバー側で実行する必要があります。

レシートの照会に失敗しても、それだけで決済の失敗を意味するわけではありません。RPCエラーであれば、保存済みのトランザクションハッシュを再照会してください。追加の承認数とチェーン再編成への対応は、運用ポリシーで定めます。

テスト決済の実行と結果確認

すべてのファイルを保存してから、テスト用ウォレットで実行してください。型チェックでは、署名や送金は実行されません。以下のコマンドでは、先ほどインストールしたTypeScriptツールを使用します。

1. 次のコマンドで型をチェックしてください。
2. 2つ目のターミナルに、サーバーと同じ受取アドレスを入力してください。
3. テスト決済用ウォレットの秘密鍵を、非表示で入力してください。
4. クライアントを1回実行してください。
5. 保存された精算結果と送金ログを確認してください。

npx tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext server.ts client.ts check-transfer.ts
read -r -p '같은 수취 지갑 주소: ' PAY_TO
read -r -s -p '테스트 결제 지갑 개인키: ' EVM_PRIVATE_KEY
export PAY_TO EVM_PRIVATE_KEY
npx tsx client.ts
unset EVM_PRIVATE_KEY

クライアントを新たに実行すると、新しい決済が発生する場合があります。この最小限のサンプルには、注文ごとの重複を防ぐストアはありません。再試行機能は、次の節の条件を満たしてから追加してください。

検証失敗の条件別の処理

失敗テストでは、有料の本文が露出しないことを確認してください。HTTPステータスだけをチェックすると、ブロック漏れを見逃す可能性があります。基準となる動作は、公式Expressミドルウェアを参照します。

基本的な承認フローでは、精算前にハンドラーが実行されます。精算に失敗しても、外部での処理まで元に戻るわけではありません。このサンプルのように、副作用のない照会から適用してください。

メールの送信や外部での注文作成には、別途設計が必要です。決済と処理の状態を一緒に記録してください。失敗時の再実行範囲を決めることで、処理の重複を減らせます。

精算後のレスポンス消失と再送による復旧

決済の完了とコンテンツ配信の完了を、別々の状態として保存してください。決済が完了していても、レスポンスの接続が切れる場合があります。このような状況への対応の根拠となるのは、Payment-Identifier拡張ドキュメントです。

同じ処理を再リクエストしても重複処理しない性質を、冪等性と呼びます。payment-identifierは、そのための決済識別子を提供します。識別子を追加するだけで、自動的に完成する機能ではありません。

重複決済と再送の比較

同じ署名の再利用防止と、注文の重複防止は区別する必要があります。EIP-3009は、使用済みの承認nonceの再利用を防ぎます。この動作は、ERC-3009仕様に定義されています。

次の手順は、公式拡張を運用用ストアに接続する設計案です。前述の最小限のコードには含まれていません。本番運用に適用する場合は、永続ストアと同時リクエストの制御を追加してください。

1. サーバー側でpayment-identifier拡張への対応を宣言してください。
2. クライアント側で論理的なリクエストの識別子を保持してください。
3. サーバー側で識別子を支払者とリクエスト内容に関連付けてください。
4. 処理中の状態をアトミックに記録し、同時実行を防いでください。
5. 精算成功時に、トランザクションの証拠とレスポンス結果を保存してください。
6. 再リクエストの権限と内容が同じであれば、保存済みの結果を返してください。
7. 精算結果が不明確な場合は、既存の承認から確認してください。

決済識別子は、パスワードやアクセストークンではありません。識別子を知っているだけのリクエストに、有料キャッシュを返してはいけません。別のユーザーや異なるリクエスト本文に再利用されていないかもチェックしてください。

運用記録には、チェーン・トランザクションハッシュ・ログ位置を一緒に残してください。この記録を注文に関連付けて、別の注文での再利用をブロックします。Transferの一致だけでは、注文との対応関係までは証明できません。

決済実装でよくある間違い

バージョンフィールドと成功を示す情報を混同すると、決済の判定が誤ります。以下の表を、デプロイ時のレビューに活用してください。バージョンの違いは、x402移行ガイドに基づいています。

USDCの署名のドメイン情報にも、バージョン文字列が含まれます。その値は、x402のプロトコルバージョンとは目的が異なります。署名ドメインの構造は、ERC-3009仕様で確認してください。

セキュリティ点検と外部サービスの信頼範囲

決済の成功判定は、サーバー側で制御してください。外部facilitatorのレスポンスも、明示的な信頼対象です。自前での運用もできる構成については、facilitatorドキュメントに説明されています。

• クライアントの成功メッセージで、コンテンツへのアクセスを許可しないでください。
• サーバーが宣言したチェーン・トークン・金額・受取人を比較してください。
• 秘密鍵やシードフレーズをログに残さないでください。
• 承認署名の全体も、通常のアクセスログから除外してください。
• 決済ヘッダーのサイズとリクエストの処理時間を制限してください。
• 有料レスポンスが共有キャッシュに残らないように点検してください。
• テスト用キーと本番用キーの保管場所を分けてください。
• facilitatorの障害時に、決済なしで迂回する経路を作らないでください。
• 承認の期限切れと重複リクエストを、実際にテストしてください。

実習で固定した依存関係には、セキュリティチェックの警告が残っています。npm auditは、zodに関するアドバイザリを報告しました。関連する内容は、GitHubセキュリティアドバイザリで確認してください。

npm audit

本番環境へのデプロイ前に、修正版とのSDKの互換性を確認してください。メジャーバージョンを強制的に置き換えると、動作が変わる可能性があります。この実習を、セキュリティ検証済みのデプロイ構成として使用しないでください。

自前のサーバーとCloudflare Gatewayの比較

Cloudflare Gatewayを使うと、オリジンサーバーでの検証方法が変わります。2026年9月30日付のドキュメントでは、x402 v2の使用が明記されています。次の区分は、Cloudflare x402ドキュメントに基づいています。

PAYMENT-CONTEXTは、Gatewayとオリジンサーバーの間で使うヘッダーです。一般的なx402クライアントの署名ヘッダーではありません。オリジンでの検証は、Cloudflare Payment validationドキュメントに従ってください。

Gatewayを経由しても、JWTを単にデコードするだけではいけません。ドキュメントで指定されたキーを使って、署名を検証してください。ヘッダーがない場合や検証に失敗した場合は、有料コンテンツをブロックします。

実際の使用量と精算記録の区別

オンチェーンの送金件数だけでは、コンテンツの消費を証明できません。運用指標は、精算とレスポンスの配信を関連付けて集計してください。これは、決済フローと再送の動作に基づく設計上の提案です。

テストリクエストは、実際の使用量の集計で区別してください。同じ注文の再試行も、別途表示します。取引量そのものを、APIの需要や収益の保証として説明してはいけません。

Baseメインネットへの移行手順

テストネットで正常時と失敗時の経路を確認してから、メインネットを検討してください。ネットワーク文字列を変更するだけでは、移行は完了しません。基準となる手順は、公式販売者ガイドに従います。

1. 選択したfacilitatorがBaseメインネットに対応していることを確認してください。
2. /supportedで、v2・exact・eip155:8453への対応を確認してください。
3. 提供者が要求する認証と利用条件を設定してください。
4. サーバーとクライアントのネットワークを両方変更してください。
5. クライアントで許可するUSDCアドレスを、メインネットのアドレスに変更してください。
6. 402レスポンスの金額と、実際の受取アドレスを再度照合してください。
7. 重複リクエスト用ストアと障害復旧手順を組み込んでください。
8. 本番用の依存関係のセキュリティチェックを完了してください。
9. 設定した少額で、実際の送金とコンテンツの配信を確認してください。

マルチチェーン対応は、すべての組み合わせへの対応を意味しません。SDKとfacilitatorの対応範囲を、両方確認してください。確認の基準は、ネットワーク・トークン対応ドキュメントです。