ライフサイクルフック

x402の支払いフローをサーバー・クライアント・ファシリテーターの各レイヤーでカスタマイズする方法を解説します。

ライフサイクルフックを使うと、コアのビジネスロジックを変更せずに支払いフローの各ポイントに処理を追加できます。ログ収集・アクセス制御・分析など幅広い用途に対応します。

サーバーサイドフック

x402ResourceServer

トランスポート非依存のフックで、検証・決済イベントに対応します：

• onBeforeVerify — 検証前に支払いを拒否できます。不正なクライアントのブロックや独自の事前検証に活用。
• onAfterVerify — 検証成功後に実行されます。ログ収集や分析データの記録に活用。
• onAfterSettle — 決済成功後に実行されます。カスタムアクセス権付与やWebhook通知などに活用。
• onVerifyFailure / onSettleFailure — 失敗時のリカバリー処理を実装できます。

x402HTTPResourceServer

HTTP固有のシナリオに対応します：

• onProtectedRequest — 保護されたルートへのリクエストを受け取る際に実行。APIキー保持者への支払い免除・サブスクライバーへのアクセス許可・特定クライアントのブロックなどに活用。

クライアントサイドフック

x402Client

• onBeforePaymentCreation — 支払いペイロードの作成前に実行。支出上限の強制・承認要求・条件チェックに活用。
• onPaymentCreationFailure — 支払い作成が失敗した場合に実行。フォールバック処理の実装に活用。

x402HTTPClient

• on402Response — 402レスポンスを受け取った際に実行。支払い開始前にAPIキーなどの代替ヘッダーでリトライを試みることができます。

ファシリテーターフック

x402Facilitator は検証・決済フックをサポートし、以下の用途に活用できます：

• ディスカバリーカタログ（Bazaar）への登録・更新
• コンプライアンスチェックの実行
• クロスペイメントのメトリクス収集
• カスタム決済後処理

フックのチェーン

複数のフックをメソッドチェーンで順番に登録できます。フックはTypeScript・Python（sync版含む）・Goで実装例が用意されています。詳細はx402リポジトリのサンプルをご参照ください。