Solana x402プロトコルとKora RPCの統合

構築するもの

このガイドでは、KoraのSolanaガスレス署名インフラストラクチャを使用した、完全なx402（HTTP 402 Payment Required）統合の実装手順を説明します。完了すると、以下の機能を持つ動作するシステムが構築できます：

APIがx402プロトコルを使用してアクセスのマイクロペイメントを請求できる
ユーザーがガス代にSOLを必要とせずUSDCで支払える
Koraがガスレスファシリテーターとしてすべてのトランザクション手数料を処理する
支払いがSolanaブロックチェーン上でアトミックに決済される

最終的には、完全に機能する支払い保護されたAPIが完成します：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
X402 + KORA PAYMENT FLOW DEMONSTRATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[1/4] Initializing payment signer
  → Network: solana-devnet
  → Payer address: BYJV...TbBc
  ✓ Signer initialized

[2/4] Attempting to access protected endpoint without payment
  → GET http://localhost:4021/protected
  → Response: 402 Payment Required
  ✅ Status code: 402

[3/4] Accessing protected endpoint with x402 payment
  → Using x402 fetch wrapper
  → Payment will be processed via Kora facilitator
  → Transaction submitted to Solana
  ✅ Status code: 200

[4/4] Processing response data
  ✓ Payment response decoded

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SUCCESS: Payment completed and API accessed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Response Data:
{
    "data": {
        "message": "Protected endpoint accessed successfully",
        "timestamp": "2025-09-25T20:14:04.242Z"
    },
    "status_code": 200,
    "payment_response": {
        "transaction": "5ULZpdeThaMAy6hcEGfAoMFqJqPpCtxdCxb6JYUV6nA4x8Lk2hKEuzofGUPoe1pop6BdWMSmF5oRPrXsbdWmpruf",
        "success": true,
        "network": "solana-devnet"
    }
}

x402とは？

x402は、APIアクセスのためのシームレスなマイクロペイメントを可能にするオープン決済標準です。従来のサブスクリプションモデルやAPIキーの代わりに、x402はサーバーが個々のAPI呼び出しに課金することを可能にし、真のペイ・パー・ユースインフラストラクチャを実現します。

x402の主なメリット：

即時マイクロペイメント：API呼び出しごとに数セントの端数を支払う
AIエージェントによるAPI呼び出しの支払いを実現：AIエージェントを使用してAPI呼び出しの支払いを行う
サブスクリプション不要：ユーザーは使用した分だけ支払う
Web3決済：オンチェーンで透明性が高く検証可能な支払い
標準HTTP：支払いが必要な場合にHTTP 402ステータスコードを使用して、既存のWebインフラストラクチャと連携する

x402を使用してAPIアクセスのマイクロペイメントを要求するサーバーは、支払いが必要な場合にHTTP 402ステータスコードを返します。保護されたエンドポイントにアクセスするには、クライアントはX-PAYMENTヘッダーでサーバーに有効な支払いを渡す必要があります。x402は、サーバーがブロックチェーンインフラストラクチャと直接やり取りする必要がないよう、トランザクションの検証と決済を行う「ファシリテーター」に依存しています。

ファシリテーターについて理解する

ファシリテーターはx402エコシステムにおける重要なコンポーネントです。APIサーバーに代わってブロックチェーン決済を抽象化する専門サービスとして機能します。

ファシリテーターの役割：

支払いの検証：クライアントの支払いペイロードが正しく形成され、十分であることを確認する
複雑性の抽象化：サーバーがブロックチェーンインフラストラクチャ（署名とネットワーク手数料の支払い）と直接やり取りする必要をなくす
トランザクションの決済：検証済みトランザクションをSolana（または他のネットワーク）に送信する

このデモでは、Koraを活用してトランザクションを検証・決済するファシリテーターを作成します（詳細は後述）。

Koraとは？

Koraは、署名およびガスレストランザクションサービスを提供するSolana署名者ノードです。アプリケーションがガス代を抽象化し、ユーザーがSOL以外のトークンでトランザクションコストを支払ったり、手数料を完全にスポンサーしてもらったりすることを可能にします。

Koraの主な機能：

ガスレストランザクション：ユーザーはトランザクションの実行にSOLを必要としない
手数料の抽象化：USDCまたは他のSPLトークンで手数料を支払う
JSON-RPCインターフェース：トランザクション処理のためのシンプルなHTTP API
柔軟な署名者：複数の署名者バックエンドをサポート（メモリ、Vault、Turnkey、Privy）
ポリシーエンジン：トランザクション検証と手数料ポリシーのきめ細かな制御

x402のコンテキストでは、Koraはファシリテーターの理想的なバックエンドとして機能します：ネットワーク手数料を処理し、トランザクションに署名し、トランザクションを検証します。

アーキテクチャの概要

x402 + Kora統合は、完全なリクエスト/レスポンスサイクルを持つ4つの相互接続されたコンポーネントで構成されています：

完全な支払いフロー：

クライアントが保護されたリソースをリクエスト → APIが402 Payment Requiredを返す
クライアントがx402フェッチラッパーで支払いトランザクションを作成する（支払いinstructionsを含むSolanaトランザクションを組み立てる）
クライアントが検証のためにファシリテーターに支払いを送信する
ファシリテーターがKora経由で検証し、KoraがSolanaに署名・送信する
トランザクションがオンチェーンで確認され、ファシリテーターがAPIに通知する
APIが支払い領収書とともに保護されたコンテンツをクライアントに返す

コンポーネントの詳細

Kora RPCサーバー（ポート8080）
- コアのガスレストランザクションサービス
- 手数料支払者としてトランザクション署名を処理する
- 設定済みポリシーに対してトランザクションを検証する
ファシリテーターラッパー/プロキシサーバー（ポート3000）
- Koraをx402プロトコルに適応させる
- /verify、/settle、/supportedエンドポイントを実装する
- x402とKoraのデータ形式間で変換する
保護されたAPI（ポート4021）
- 支払い保護されたエンドポイントを持つデモAPIサーバー
- 支払い処理にx402-expressミドルウェアを使用する
- 支払い成功後にのみデータを返す
クライアントアプリケーション
- x402フェッチラッパーの使用方法をデモする
- ユーザーの秘密鍵でトランザクションに署名する

マルチコンポーネントのアプローチは複雑に見えるかもしれませんが、支払い処理、APIサービング、クライアントアプリケーションが個別の関心事として分離された実際の本番システムを反映しています。

前提条件

開始する前に、以下が揃っていることを確認してください：

Rust（最新の安定版）
Node.js（LTS以降）
pnpm（最新版）
Solanaトランザクションと SPLトークンの基本的な理解

プロジェクトのセットアップ

ステップ1：Koraのクローンとビルド

# Clone the repository
git clone https://github.com/solana-foundation/kora.git
cd kora

# Checkout the release branch as Kora is currently in a feature freeze for audit
git checkout release/feature-freeze-for-audit

# Build and install Kora
make install

これによりkoraバイナリがシステムにインストールされ、RPCサーバーの起動に使用します。

ステップ2：デモディレクトリへの移動

cd docs/x402/demo

ステップ3：依存関係のインストール

すべてのデモコンポーネントのNode.js依存関係をインストールします：

# Install dependencies for all components (facilitator, API, and client)
pnpm run install:all

このスクリプトは以下の依存関係をインストールします：

ファシリテーターラッパーサービス
保護されたAPIサーバー
クライアントデモアプリ

ステップ4：Kora SDKのビルド

ファシリテーターでKora TypeScript SDKを使用できるように、Kora SDKをビルドします：

pnpm run build:kora-sdk

ステップ5：環境の設定

デモには必要な環境変数が含まれた.env.exampleファイルが含まれています。まず、基本設定をセットアップしましょう：

# Copy the example environment file
cp .env.example .env

次に、デモ用のkeypairを生成または提供する必要があります。以下のコマンドを実行してkeypairを生成してください：

pnpm run setup

これによりkeypairが生成され、.envファイルに追加されます：

KORA_SIGNER_ADDRESS - Kora署名者のアドレス
KORA_SIGNER_PRIVATE_KEY - Kora署名者の秘密鍵
PAYER_ADDRESS - 保護されたAPIへのアクセスに支払いを行う支払者のアドレス
PAYER_PRIVATE_KEY - 支払者の秘密鍵

ステップ5：設定ファイルの更新

kora.toml

kora/kora.tomlファイルはKora RPCサーバーを設定します。このファイルへの変更は不要ですが、以下の設定を確認できます：

支払いトークン：Devnet USDCミントがアローリストに含まれていることを確認してください：

allowed_tokens = [
    "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", # USDC devnet
]

API認証：デモはKoraアクセスにAPIキーを使用します。これは.envファイルのKORA_API_KEYと一致している必要があります：

[kora.auth]
api_key = "kora_facilitator_api_key_example"

手数料支払者ポリシー：不要なトランザクションへの署名を制限するよう設定されています：

[validation.fee_payer_policy]
allow_sol_transfers = false
# all other settings are false

許可プログラム：System Program、Token Program、Associated Token Program、およびCompute Budget ProgramがアローリストKに含まれていることを確認してください：

allowed_programs = [
    "11111111111111111111111111111111",             # System Program
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",  # Token Program
    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL", # Associated Token Program
    "ComputeBudget111111111111111111111111111111",  # Compute Budget Program
]

signers.toml

kora/signers.tomlファイルはKora署名者を設定します。このファイルへの変更は不要ですが、以下の設定を確認できます：

署名者環境変数：署名者環境変数private_key_envがKORA_SIGNER_PRIVATE_KEYに設定されていることを確認してください（.envファイルの環境変数名と一致）。

[[signers]]
name = "main_signer"
type = "memory"
private_key_env = "KORA_SIGNER_PRIVATE_KEY"
weight = 1

ステップ6：アカウントへの入金

Devnet SOL

Kora署名者アドレスはトランザクション手数料の支払いにSOLが必要です。Solana CLIを使用してKora署名者アドレスにDevnet SOLをエアドロップできます：

# Airdrop SOL
solana airdrop 1 <KORA_SIGNER_ADDRESS> --url devnet

または、Solana Faucetを使用してKora署名者アドレスにSOLをエアドロップすることもできます。

Devnet USDC

.envファイルに設定されたPAYER_ADDRESSはトランザクション手数料の支払いにUSDCが必要です。

CircleのFaucetからDevnet USDCを取得してください。「Solana Devnet」を選択し、PAYER_ADDRESSを使用してUSDCをリクエストしてください。

デモの実行

docs/x402/demoディレクトリからすべてのコンポーネントを実行するために、4つのターミナルウィンドウが必要です。

ターミナル1：Kora RPCサーバーの起動

以下のコマンドを実行してKora RPCサーバーを起動します：

pnpm run start:kora

Kora RPCサーバーが起動していることを示す一連のログが表示されます。以下を含みます：

INFO kora_lib::rpc_server::server: RPC server started on 0.0.0.0:8080, port 8080

ターミナル2：ファシリテーターの起動

以下のコマンドを実行してファシリテーターを起動します：

pnpm run start:facilitator

以下が表示されます：

Server listening at http://localhost:3000

ターミナル3：保護されたAPIの起動

以下のコマンドを実行して保護されたAPIを起動します：

pnpm run start:api

以下が表示されます：

Server listening at http://localhost:4021

ターミナル4：クライアントデモの実行

pnpm run demo

実装の理解

支払いフローが正常に機能する際に起こることを説明します：

クライアントリクエスト → APIが支払い要件とともに402を返す
支払いの作成 → クライアントが支払いを含むSolanaトランザクションを作成する
支払いの送信 → クライアントがX-PAYMENTヘッダーに支払いを含めてサーバーにリクエストを送信する
検証 → ファシリテーターがKoraのsignTransactionを介して検証する
決済 → ファシリテーターがKoraのsignAndSendTransactionを介して決済する（支払いトランザクションをSolanaに送信）
アクセス許可 → ファシリテーターがトランザクション署名を返し、APIが支払い領収書とともに保護されたコンテンツを返す

各コンポーネントの仕組みを詳しく見てみましょう：

Kora RPC（ポート8080）：ガスレストランザクション署名を処理する
ファシリテーター（ポート3000）：x402プロトコルをKoraに橋渡しする
保護されたAPI（ポート4021）：収益化されたAPIエンドポイント
クライアント：自動支払いフローをデモする

ファシリテーターラッパー/プロキシサーバー

ファシリテーターはポート3000で動作します。これはSolanaとの通信（今回はKora経由）を処理するサーバーです。x402支払いの検証と決済に使用されます。

ファシリテーター（facilitator/src/facilitator.ts）はx402プロトコルとKora RPCの橋渡し役です。3つの主要エンドポイントを実装しています：

1. `/verify`エンドポイント

このエンドポイントは：

保護されたAPIサーバーからx402支払いペイロードを受信する
x402ヘルパーを使用してSolanaトランザクションを抽出する
KoraのsignTransactionを使用してブロードキャストせずに有効性を検証する
検証ステータスisValidを返す

2. `/settle`エンドポイント

このエンドポイントは：

/verifyエンドポイントで支払いが検証された後、x402支払いペイロードを受信する
KoraのsignAndSendTransactionを使用してトランザクションに署名しブロードキャストする
決済の証明としてトランザクション署名を返す

3. `/supported`エンドポイント

このエンドポイントはファシリテーターの機能を公示します。以下を含みます：

サポートされるx402バージョン
支払いスキーム（正確な支払い）
ネットワーク（solana-devnet）
getPayerSignerメソッドを使用してKoraから取得する手数料支払者アドレス

保護されたAPI

APIサーバー（api/src/api.ts）はx402-expressミドルウェアを使用してエンドポイントを保護します：

app.use(
  paymentMiddleware(
    KORA_PAYER_ADDRESS, // Where payments should go
    {
      "GET /protected": {
        price: "$0.0001", // Price in USD
        network: NETWORK // solana-devnet
      }
    },
    {
      url: FACILITATOR_URL // Our facilitator wrapper
    }
  )
);

ミドルウェアは：

保護されたエンドポイント（今回は/protectedエンドポイント）へのリクエストをインターセプトする
支払いがない場合に402ステータスを返す
ファシリテーターを介して支払いを検証・処理する
支払い成功後にアクセスを許可する

Expressを使用していますが、x402ライブラリは多くの一般的なフレームワーク向けのミドルウェアサポートも含んでいます。詳細については、 x402 TypeScriptパッケージをご覧ください。

クライアントアプリケーション

クライアント（client/src/index.ts）は、標準のfetch呼び出しでリクエストを送信し、その後ペイメントラッパーでリクエストを再試行することで、x402の動作を自動的に示します：

// Create a signer from private key
const payer = await createSigner(NETWORK, PAYER_PRIVATE_KEY);

// Wrap fetch with x402 payment capabilities
const fetchWithPayment = wrapFetchWithPayment(fetch, payer);

// First attempt: Regular fetch (will fail with 402)
const expect402Response = await fetch(PROTECTED_API_URL);
console.log(`Status: ${expect402Response.status}`); // 402

// Second attempt: Fetch with payment wrapper (succeeds)
const response = await fetchWithPayment(PROTECTED_API_URL);
console.log(`Status: ${response.status}`); // 200

x402 fetchラッパーの機能：

402レスポンスを検出する
保護されたAPIの支払い要件に基づいて、支払いトランザクションを自動的に作成する
ユーザーの秘密鍵で署名する
検証・処理のためにファシリテーターへ支払いを送信する
x-payment-responseヘッダーに支払い証明を付けてリクエストを再試行する
成功レスポンスを返す

まとめ

おめでとうございます！🔥 Koraのガスレスインフラストラクチャを使用して、完全なx402支払いフローの実装に成功しました。このデモンストレーションでは以下を示しています：

x402プロトコルは、マイクロペイメントによるシームレスなAPI収益化を実現する
Kora RPCは、トランザクションを検証・決済することでx402支払いのファシリテーターとして機能する
ユーザーは、SOLを保有したりガス代を管理したりすることなく、APIアクセスの支払いが可能になる

このアーキテクチャは、以下のための強力な基盤を構築します：

AIエージェントマーケットプレイス
従量課金型API
マイクロペイメントコンテンツプラットフォーム
使用量ベースのSaaS価格設定
即時かつ検証可能な支払いを必要とするあらゆるサービス

x402とKoraの組み合わせにより、Solanaのパワーを従来のWebインフラストラクチャにもたらします。

開発を続けよう

価格のカスタマイズ：エンドポイントごとに異なる金額を請求するようAPIを変更する
複数トークンの追加：支払いにさまざまなSPLトークンを受け入れるようKoraを設定する
本番環境へのデプロイ：本番環境の署名者（Vault、Turnkey、またはPrivy）を使用してメインネットにデプロイする
独自APIの構築：x402支払いで収益化する実際のサービスを作成する

Solana Stack Exchangeでkoraおよびx402タグを使って質問する
Kora GitHubリポジトリでIssueを作成する

x402とKoraの統合 - 完全デモガイド