Protocole de Paiement x402

Que fait Protocole de Paiement x402 ?

x402 permet des paiements instantanés en stablecoins directement via HTTP en utilisant le code d'état 402 Payment Required. Parfait pour les agents IA payant des API, des données ou du calcul à la demande.

Démarrage rapide

Installer le SDK

npm install x402
# ou
pnpm add x402

Configuration de l'environnement

# Stocker la clé privée du portefeuille de manière sécurisée
export WALLET_PRIVATE_KEY="0x..."

# Facultatif : spécifier un RPC réseau
export BASE_RPC_URL="https://mainnet.base.org"

Comment fonctionne x402

1. Requête → Le client appelle une API payante
2. Réponse 402 → Le serveur renvoie les détails du paiement dans l'en-tête PAYMENT-REQUIRED
3. Payer et réessayer → Le client signe le paiement, réessaie avec l'en-tête PAYMENT-SIGNATURE
4. Accès → Le serveur vérifie, règle et retourne la ressource

Utilisation du client x402

TypeScript/Node.js

import { x402Client } from 'x402';

const client = x402Client({
  privateKey: process.env.WALLET_PRIVATE_KEY,
  network: 'base', // ou 'ethereum', 'arbitrum', etc.
});

// Gestion automatique du 402
const response = await client.fetch('https://api.example.com/paid-endpoint');
const data = await response.json();

Avec un wrapper fetch

import { wrapFetch } from 'x402';

const fetch402 = wrapFetch(fetch, {
  privateKey: process.env.WALLET_PRIVATE_KEY,
});

// Utilisation comme un fetch normal - les 402 sont gérés automatiquement
const res = await fetch402('https://paid-api.com/data');

Flux manuel (curl)

Étape 1 : Découvrir les exigences de paiement

curl -i https://api.example.com/paid-resource
# Renvoie 402 avec l'en-tête PAYMENT-REQUIRED (JSON en base64)

Étape 2 : Décoder les détails du paiement

# L'en-tête PAYMENT-REQUIRED contient du JSON encodé en base64 :
# {
#   "amount": "1000000",      # 1 USDC (6 décimales)
#   "currency": "USDC",
#   "network": "base",
#   "recipient": "0x...",
#   "scheme": "exact"
# }

Étape 3 : Signer et payer

# Utiliser la CLI x402 ou le SDK pour créer une signature de paiement
npx x402 pay \
  --amount 1000000 \
  --recipient 0x... \
  --network base

Étape 4 : Réessayer avec la preuve

curl -H "PAYMENT-SIGNATURE: <base64_payload>" \
  https://api.example.com/paid-resource

Modèles courants

Payer pour des appels API

// API météo qui coûte 0,001 USDC par appel
const weather = await client.fetch('https://weather-api.x402.org/forecast?city=NYC');

Payer pour l'inférence IA

// API LLM avec tarification par token
const completion = await client.fetch('https://llm.example.com/v1/chat', {
  method: 'POST',
  body: JSON.stringify({ prompt: 'Hello' }),
});

Vérifier le solde avant de payer

import { getBalance } from 'x402';

const balance = await getBalance({
  address: walletAddress,
  network: 'base',
  token: 'USDC',
});

if (balance < requiredAmount) {
  console.log('Solde USDC insuffisant');
}

Réseaux pris en charge

Réseau	ID de chaîne	Statut
Base	8453	✅ Principal
Ethereum	1	✅ Pris en charge
Arbitrum	42161	✅ Pris en charge
Optimism	10	✅ Pris en charge
Polygon	137	✅ Pris en charge

Schémas de paiement

• exact : Payer un montant fixe (ex. 0,01 $ par appel API)
• upto : Payer jusqu'à un maximum en fonction de l'utilisation (ex. tokens LLM)
• subscription : Accès basé sur portefeuille avec sessions (V2)

Gestion des erreurs

try {
  const res = await client.fetch(url);
} catch (err) {
  if (err.code === 'INSUFFICIENT_BALANCE') {
    // Nécessite d'alimenter le portefeuille
  } else if (err.code === 'PAYMENT_FAILED') {
    // La transaction a échoué sur la chaîne
  } else if (err.code === 'INVALID_PAYMENT_REQUIREMENTS') {
    // Le serveur a envoyé une réponse 402 mal formée
  }
}

Notes de sécurité

• Ne jamais exposer les clés privées dans les logs ou le chat
• Utiliser des variables d'environnement pour les identifiants du portefeuille
• Préférer op run ou similaire pour l'injection de secrets
• Examiner les montants de paiement avant de confirmer les transactions importantes

Fonctionnalités V2 (décembre 2025)

• Identité basée sur portefeuille : Éviter de repayer à chaque appel avec des sessions
• Auto-découverte : Les API exposent les métadonnées de paiement à /.well-known/x402
• Multi-facilitateur : Choisir entre les processeurs de paiement
• Normes CAIP : Identifiants universels de chaîne/actif

Ressources

• Spécification : https://github.com/coinbase/x402
• Documentation : https://docs.cdp.coinbase.com/x402
• API de démonstration : https://www.x402.org