クライアント / サーバー
x402プロトコルにおけるクライアントとサーバーの役割と責務を説明します。
x402を使ったプログラム決済のサービスを設計・構築・統合するには、これらの役割を理解することが不可欠です。
クライアントとはHTTPリクエストを送信する技術コンポーネントのことです。実際にはリソースのバイヤー（買い手）にあたります。
サーバーとはリクエストに応答する技術コンポーネントのことです。実際にはリソースのセラー（売り手）にあたります。
クライアントの役割
クライアントは有料リソースへのアクセスリクエストを開始するエンティティです。人間が操作するアプリケーション・自律型エージェント・プログラム的サービスが含まれます。
責務
- リクエストの開始：リソースサーバーにHTTPリクエストを送信する
- 支払い要件の処理：402 Payment Requiredレスポンスを読み取り、支払い詳細を抽出する
- 支払いペイロードの作成：提示された支払い要件をもとに有効な支払いペイロードを構築する
- 支払い付きリクエストの再送：署名済み支払いペイロードを含む
PAYMENT-SIGNATUREヘッダーを付けてリクエストをリトライする
クライアントはクリプトウォレット以外のアカウント・認証情報・セッショントークンを管理する必要がありません。すべてのやり取りはステートレスで、標準的なHTTPリクエストで行われます。
サーバーの役割
サーバーはサービスへのアクセスに対して支払いを強制するリソースプロバイダーです。APIサービス・コンテンツプロバイダー・あらゆるHTTPアクセス可能なリソースが含まれます。
責務
- 支払い要件の定義：未認証リクエストに対して
HTTP 402 Payment Requiredを返し、必要な支払い詳細をレスポンスボディに含める - 支払いペイロードの検証：受信した支払いペイロードをローカルまたはファシリテーターサービスを通じて検証する
- トランザクションの決済：検証成功後、支払いを決済処理に送信する
- リソースの提供：支払いが確認されたら、リクエストされたリソースをクライアントに返す
Solanaでの二重決済について
注意
ファシリテーターを使わずSolanaで直接決済する場合、同じ署名済みトランザクションが複数回送信されるレースコンディションに注意が必要です。悪意のあるクライアントがこれを悪用し、1回分の支払いで複数のリソースにアクセスする可能性があります。
これを防ぐため、Solana決済を直接処理するサーバーは決済中トランザクションの短命なインメモリキャッシュを維持する必要があります。 ファシリテーターを使用している場合、SettlementCache による保護が組み込まれています。
通信フロー
- 1クライアントがサーバーに有料リソースをリクエスト
- 2サーバーが
402 Payment Requiredとレスポンスボディに支払い要件を含めて返答 - 3クライアントが支払いペイロードを作成し、
PAYMENT-SIGNATUREヘッダー（Base64エンコード）に含めて送信 - 4サーバーが支払いペイロードをローカルまたはファシリテーターサービスで検証
- 5サーバーが支払いを決済し、トランザクション完了を確認
- 6サーバーがリソース（成功時）またはエラーレスポンスを返す。どちらも
PAYMENT-RESPONSEヘッダーに決済詳細を含める
まとめ
- クライアント はリソースをリクエストし、署名済み支払いペイロードを提供する
- サーバー は支払い要件を強制し、トランザクションを検証し、支払い確認後にリソースを提供する
このやり取りはステートレスで、HTTPネイティブであり、人間が操作するアプリケーションと自動化エージェントの両方に対応しています。