Intégration du protocole Solana x402 avec Kora RPC

Ce que vous allez construire

Ce guide vous accompagne dans la mise en œuvre d'une intégration complète x402 (paiement HTTP 402 requis) avec Kora, l'infrastructure de signature sans gas de Solana. À la fin, vous disposerez d'un système fonctionnel où :

Les API peuvent facturer des micropaiements pour l'accès via le protocole x402
Les utilisateurs paient en USDC sans avoir besoin de SOL pour les frais de gas
Kora prend en charge tous les frais de transaction en tant que facilitateur sans gas
Les paiements sont réglés de manière atomique sur la blockchain Solana

Le résultat final sera une API entièrement fonctionnelle protégée par des paiements :

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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"
    }
}

Qu'est-ce que x402 ?

x402 est un standard de paiement ouvert qui permet des micropaiements transparents pour l'accès aux API. Au lieu des modèles d'abonnement traditionnels ou des clés API, x402 permet aux serveurs de facturer des appels API individuels, créant ainsi une véritable infrastructure à la consommation.

Principaux avantages de x402 :

Micropaiements instantanés : Payez des fractions de centime par appel API
Permettre aux agents IA de payer les appels API : Réglez les appels API avec des agents IA
Sans abonnement : Les utilisateurs ne paient que ce qu'ils utilisent
Paiements Web3 : Paiements transparents et vérifiables sur la blockchain
HTTP standard : Fonctionne avec l'infrastructure web existante en utilisant un code de statut HTTP 402 lorsqu'un paiement est requis

Les serveurs utilisant x402 pour exiger des micropaiements pour l'accès aux API renverront un code de statut HTTP 402 lorsqu'un paiement est requis. Pour accéder aux endpoints protégés, les clients doivent transmettre un paiement valide au serveur dans un en-tête X-PAYMENT. x402 s'appuie sur des « Facilitateurs » pour vérifier et régler les transactions, afin que les serveurs n'aient pas à interagir directement avec l'infrastructure blockchain.

Comprendre les Facilitateurs

Les Facilitateurs sont un composant essentiel de l'écosystème x402. Ils agissent en tant que services spécialisés qui abstraient les paiements blockchain pour le compte des serveurs API.

Ce que font les Facilitateurs :

Vérifier les paiements : Valider que les charges utiles de paiement des clients sont correctement formées et suffisantes
Abstraire la complexité : Supprimer la nécessité pour les serveurs d'interagir directement avec l'infrastructure blockchain (signature et paiement des frais de réseau)
Régler les transactions : Soumettre les transactions validées à Solana (ou à d'autres réseaux)

Dans notre démo, nous créons un facilitateur qui exploite Kora pour vérifier et régler les transactions (plus de détails ci-dessous).

Qu'est-ce que Kora ?

Kora est un nœud de signature Solana qui fournit des services de signature et de transactions sans gas. Il permet aux applications d'abstraire les frais de gas, permettant aux utilisateurs de payer les coûts de transaction en tokens autres que SOL, ou de faire parrainer entièrement les frais.

Principales fonctionnalités de Kora :

Transactions sans gas : Les utilisateurs n'ont pas besoin de SOL pour exécuter des transactions
Abstraction des frais : Payer les frais en USDC ou en autres tokens SPL
Interface JSON-RPC : API HTTP simple pour la gestion des transactions
Signataires flexibles : Prise en charge de plusieurs backends de signature (mémoire, Vault, Turnkey, Privy)
Moteur de politiques : Contrôle granulaire sur la validation des transactions et les politiques de frais

Dans le contexte de x402, Kora constitue le backend idéal pour les facilitateurs : il gère les frais de réseau, signe les transactions et les valide.

Vue d'ensemble de l'architecture

Notre intégration x402 + Kora se compose de quatre composants interconnectés avec un cycle complet de requête/réponse :

Flux de paiement complet :

Le client demande une ressource protégée → L'API retourne 402 Paiement Requis
Le client crée une transaction de paiement avec le wrapper fetch x402 (qui assemble une transaction Solana avec une instruction de paiement)
Le client envoie le paiement au Facilitateur pour vérification
Le Facilitateur valide via Kora, qui signe et soumet à Solana
Transaction confirmée sur la blockchain, le Facilitateur notifie l'API
L'API retourne le contenu protégé avec un reçu de paiement au Client

Décomposition des composants

Serveur Kora RPC (Port 8080)
- Service central de transaction sans gas
- Gère la signature des transactions en tant que payeur de frais
- Valide les transactions selon les politiques configurées
Serveur Wrapper/Proxy Facilitateur (Port 3000)
- Adapte Kora au protocole x402
- Implémente les endpoints /verify, /settle et /supported
- Traduit entre les formats de données x402 et Kora
API Protégée (Port 4021)
- Serveur API de démonstration avec des endpoints protégés par paiement
- Utilise le middleware x402-express pour la gestion des paiements
- Renvoie les données uniquement après un paiement réussi
Application Cliente
- Illustre l'utilisation du wrapper fetch x402
- Signe les transactions avec la clé privée de l'utilisateur

L'approche multi-composants peut sembler complexe, mais elle reflète les systèmes de production réels où le traitement des paiements, la mise à disposition des API et les applications clientes sont des préoccupations distinctes.

Prérequis

Avant de commencer, assurez-vous d'avoir :

Rust (dernière version stable)
Node.js (LTS ou version ultérieure)
pnpm (dernière version)
Une compréhension de base des transactions Solana et des tokens SPL

Configuration du projet

Étape 1 : Cloner et compiler 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

Ceci installe le binaire kora sur votre système, que nous utiliserons pour exécuter le serveur RPC.

Étape 2 : Naviguer vers le répertoire de démonstration

cd docs/x402/demo

Étape 3 : Installer les dépendances

Installez les dépendances Node.js pour tous les composants de la démo :

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

Ce script installe les dépendances pour :

Le service wrapper du facilitateur
Le serveur API protégé
L'application de démonstration cliente

Étape 4 : Compiler le SDK Kora

Compilez le SDK Kora afin de pouvoir utiliser le SDK TypeScript de Kora dans le Facilitateur :

pnpm run build:kora-sdk

Étape 5 : Configurer l'environnement

La démo inclut un fichier .env.example avec les variables d'environnement requises. Commençons par configurer la configuration de base :

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

Vous devez maintenant générer ou fournir des keypairs pour la démo. Exécutez la commande suivante pour générer les keypairs :

pnpm run setup

Ceci générera les keypairs et les ajoutera au fichier .env :

KORA_SIGNER_ADDRESS - L'adresse du signataire Kora
KORA_SIGNER_PRIVATE_KEY - La clé privée du signataire Kora
PAYER_ADDRESS - L'adresse du payeur qui paiera pour accéder à l'API protégée
PAYER_PRIVATE_KEY - La clé privée du payeur

Étape 5 : Mettre à jour les fichiers de configuration

kora.toml

Le fichier kora/kora.toml configure le serveur Kora RPC. Vous ne devriez pas avoir besoin d'apporter des modifications à ce fichier, mais vous pouvez vérifier les paramètres suivants :

Token de paiement : Assurez-vous que le mint USDC Devnet est dans la liste d'autorisation :

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

Authentification API : La démo utilise une clé API pour l'accès à Kora. Cela doit correspondre à KORA_API_KEY dans le fichier .env :

[kora.auth]
api_key = "kora_facilitator_api_key_example"

Politique du payeur de frais : Configurée pour restreindre la signature de transactions indésirables :

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

Programmes autorisés : Assurez-vous que le System Program, le Token Program, le programme de token associé et le programme de budget de calcul sont dans la liste d'autorisation :

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

signers.toml

Le fichier kora/signers.toml configure le signataire Kora. Vous ne devriez pas avoir besoin d'apporter des modifications à ce fichier, mais vous pouvez vérifier les paramètres suivants :

Variable d'environnement du signataire : Assurez-vous que la variable d'environnement du signataire, private_key_env, est définie sur KORA_SIGNER_PRIVATE_KEY (correspondant au nom de la variable d'environnement dans le fichier .env).

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

Étape 6 : Alimenter les comptes

SOL Devnet

L'adresse de notre signataire Kora aura besoin de SOL pour payer les frais de transaction. Vous pouvez effectuer un airdrop de SOL Devnet vers l'adresse du signataire Kora en utilisant la CLI Solana :

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

Vous pouvez également utiliser le Faucet Solana pour effectuer un airdrop de SOL vers l'adresse du signataire Kora.

USDC Devnet

Votre PAYER_ADDRESS définie dans le fichier .env aura besoin d'USDC pour payer les frais de transaction.

Obtenez de l'USDC Devnet depuis le Faucet de Circle. Assurez-vous de sélectionner « Solana Devnet » et d'utiliser votre PAYER_ADDRESS pour demander des USDC.

Exécution de la démo

Vous aurez besoin de quatre fenêtres de terminal pour exécuter tous les composants depuis le répertoire docs/x402/demo.

Terminal 1 : Démarrer le serveur Kora RPC

Exécutez la commande suivante pour démarrer le serveur Kora RPC :

pnpm run start:kora

Vous devriez voir une série de logs indiquant que le serveur Kora RPC est en cours d'exécution, notamment :

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

Terminal 2 : Démarrer le Facilitateur

Exécutez la commande suivante pour démarrer le Facilitateur :

pnpm run start:facilitator

Vous devriez voir :

Server listening at http://localhost:3000

Terminal 3 : Démarrer l'API Protégée

Exécutez la commande suivante pour démarrer l'API Protégée :

pnpm run start:api

Vous devriez voir :

Server listening at http://localhost:4021

Terminal 4 : Exécuter la démo cliente

pnpm run demo

Comprendre l'implémentation

Voici ce qui se passe lors d'un flux de paiement réussi :

Requête du client → L'API retourne 402 avec les exigences de paiement
Création du paiement → Le client crée une transaction Solana avec le paiement
Soumission du paiement → Le client envoie la requête au serveur avec le paiement dans l'en-tête X-PAYMENT
Vérification → Le Facilitateur vérifie via signTransaction de Kora
Règlement → Le Facilitateur règle via signAndSendTransaction de Kora (en envoyant la transaction de paiement à Solana)
Accès accordé → Le Facilitateur retourne la signature de la transaction et l'API retourne le contenu protégé avec un reçu de paiement

Examinons en détail le fonctionnement de chaque composant :

Kora RPC (Port 8080) : Gère la signature des transactions sans gas
Facilitateur (Port 3000) : Fait le pont entre le protocole x402 et Kora
API Protégée (Port 4021) : Votre endpoint API monétisé
Client : Illustre le flux de paiement automatique

Le Serveur Wrapper/Proxy Facilitateur

Le Facilitateur s'exécute sur le port 3000. C'est le serveur qui gère la communication avec Solana (dans notre cas, via Kora). Il est utilisé pour vérifier et régler les paiements x402.

Le facilitateur (facilitator/src/facilitator.ts) est le pont entre le protocole x402 et Kora RPC. Il implémente trois endpoints clés :

1. Endpoint `/verify`

Cet endpoint :

Reçoit une charge utile de paiement x402 depuis le serveur de l'API Protégée
Extrait la transaction Solana à l'aide des helpers x402
Utilise signTransaction de Kora pour vérifier la validité sans diffuser
Retourne le statut de vérification, isValid

2. Endpoint `/settle`

Cet endpoint :

Reçoit la charge utile de paiement x402 après que le paiement a été vérifié par l'endpoint /verify
Utilise signAndSendTransaction de Kora pour signer et diffuser la transaction
Retourne la signature de la transaction comme preuve de règlement

3. Endpoint `/supported`

Cet endpoint annonce effectivement les capacités du facilitateur, notamment :

La version x402 prise en charge
Le schéma de paiement (paiements exacts)
Le réseau (solana-devnet)
L'adresse du payeur de frais que nous récupérons depuis Kora en utilisant la méthode getPayerSigner

L'API Protégée

Le serveur API (api/src/api.ts) utilise le middleware x402-express pour protéger les endpoints :

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
    }
  )
);

Le middleware :

Intercepte les requêtes vers les endpoints protégés (dans notre cas, l'endpoint /protected)
Retourne le statut 402 si le paiement est manquant
Valide et gère les paiements via le facilitateur
Autorise l'accès après un paiement réussi

Bien que nous utilisions Express, la bibliothèque x402 inclut une prise en charge des middlewares pour de nombreux frameworks courants. Consultez les packages TypeScript x402 pour plus d'informations.

L'application cliente

Le client (client/src/index.ts) illustre automatiquement le fonctionnement de x402 en envoyant une requête avec un appel fetch standard, puis en réessayant la requête avec le wrapper de paiement :

// 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

Le wrapper fetch x402 :

Détecte les réponses 402
Crée automatiquement une transaction de paiement selon les exigences de paiement de l'API protégée
Signe avec la clé privée de l'utilisateur
Envoie le paiement au facilitateur pour vérification et traitement
Réessaie la requête avec la preuve de paiement dans l'en-tête x-payment-response
Retourne une réponse réussie

En conclusion

Félicitations ! 🔥 Vous avez réussi à implémenter un flux de paiement x402 complet avec l'infrastructure sans frais de Kora. Cette démonstration montre comment :

Le protocole x402 permet une monétisation fluide des API via des micropaiements
Kora RPC fonctionne comme facilitateur pour les paiements x402 en vérifiant et en réglant les transactions
Les utilisateurs peuvent payer pour accéder aux API sans détenir de SOL ni gérer les frais de gas

Cette architecture constitue une base solide pour :

Les places de marché pour agents IA
Les API à la consommation
Les plateformes de contenu à micropaiements
La tarification SaaS basée sur l'usage
Tout service nécessitant des paiements instantanés et vérifiables

La combinaison de x402 et de Kora apporte la puissance de Solana à l'infrastructure web traditionnelle.

Continuez à construire

Personnaliser la tarification : Modifiez l'API pour facturer des montants différents selon les endpoints
Ajouter plusieurs tokens : Configurez Kora pour accepter différents tokens SPL en paiement
Déploiement en production : Déployez sur le réseau principal avec des signataires de production (Vault, Turnkey ou Privy)
Créez votre propre API : Développez un vrai service qui se monétise via les paiements x402

Posez vos questions sur Solana Stack Exchange avec les tags kora et x402
Ouvrez des tickets sur le dépôt GitHub de Kora

Guide complet de démo - Intégration x402 avec Kora