単体テストはすべて成功するが、結合テストでは失敗する場合がある x402 の落とし穴はほぼすべて境界条件に集中しています：402 応答ヘッダーは送信されたがブラウザで読み取れない（CORS 透過ヘッダーが不足）、署名計算は正しいが facilitator が拒否（nonce の重複／金額の単位エラー）、支払いは完了したが帳簿が一致しない（対帳元の誤り）。このツールは「無料で問題を発見 → 402 → 署名による支払い → データ取得 → オンチェーン対帳」の 5 ステップに従い、一度で実行可能な連携テストスクリプトと、各ステップの「期待値 ＋ よくある失敗原因」を記載したチェックリストを生成します。
—
—
| 現象 | 真犯人 | 修正方法 |
|---|---|---|
| パケットキャプチャで 402 を確認できますが、JavaScript 内ではヘッダーを読み取れません。 | 未設定 Access-Control-Expose-Headers | payment-required などのカスタムヘッダーを exposed リストに追加します |
| facilitator が invalid nonce を報告します | nonce の再利用、または署名ドメインとチェーン ID の不一致| | 毎回ランダムな nonce を再生成；domain の chainId を確認すること |
| facilitator が amount mismatch を報告します | 金額の単位が誤っています（USDC は小数点以下6桁） | 0.01 USDC = 10000 であり、1e16 ではありません| |
| 購入者がガスを持っていなくても支払い可能です（これは正しい動作です）。 | EIP-3009 transferWithAuthorization gas 料金は facilitator が代わりに支払います| | 購入者は USDC を保有するだけでよい |
| 钱到账但对账对不上 | チェーン上のイベントではなく、プラットフォーム自身の記録で対帳します。 | Transfer イベントのみをオンチェーンで認識し、許容誤差は ±$0.02 です| |
| 入金が一向に反映されない | 最低決済額に達していない / 決済日になっていない | 自然月単位で集計し、翌月10日が決済日です。最低決済額は $50 です| |
| 探活把端点判成已死 | MCP エンドポイントが SSE を返し、クライアント側での JSON 解析に失敗しました | HTTP ステータスコードのみで判定し、200 および 402 の両方が「生存中」と見なされます |
1 · 402 が送信されましたが、ブラウザで読み取れません。パケットキャプチャではレスポンスヘッダーが確認できますが、JavaScript 内では取得できません——カスタムレスポンスヘッダーは明示的に追加する必要があります Access-Control-Expose-Headers、さもないとブラウザがセキュリティポリシーに従って直接ブロックします。
2 · 探活误判。JSON クライアントで SSE を返す MCP エンドポイントを検査すると、常に「死亡」と判定されます。正しい方法はステータスコードのみを確認し、200 および 402 の両方を「生存中」と見なすことです。
3 · 金额单位。USDC は小数点以下6桁です。0.01 は 10000 と記述しなければなりません。1e16 と記述すると facilitator によって即座に拒否され、エラー情報には単位の誤りは明記されません。
4・対帳はブロックチェーン上でのみ実施されます。プラットフォーム自身の記録は、プロセス再起動やメモリ内の古くなった値による上書きなどにより不正確になる可能性があるため、照合は必ずブロックチェーン上の Transfer イベントを基準とすること。