402 Payment Required pour les requêtes sans token, avec un champ accepts: [...] listant les chaînes / actifs / prix acceptables ; le client signe localement une autorisation (Permit2 / EIP-712 sur EVM, autorisation de transfert de token SPL sur Solana), place l’envelope encodée en base64 dans l’en-tête PAYMENT-SIGNATURE, puis renvoie la requête. Après vérification, le serveur effectue réellement le règlement on-chain, puis renvoie le résultat métier.
Le client X402 d’Ace Data Cloud appelle directement l’API cible, et utilise le402 Payment Requiredetacceptsrenvoyés en temps réel par cette requête comme base de prix et de signature. La capacité de paiement du Facilitator peut être vérifiée sur/.well-known/x402.
@acedatacloud/sdk et acedatacloud exposent tous deux un crochet paymentHandler : lorsqu’une requête émise par le SDK lui-même reçoit un 402, il appelle le handler que vous injectez pour obtenir l’en-tête PAYMENT-SIGNATURE, puis renvoie la requête d’origine. En combinant @acedatacloud/x402-client / acedatacloud-x402 avec le SDK, l’ensemble du processus est totalement transparent pour le code métier — vous utilisez uniquement client.openai.chat.completions.create(...), ce qui semble identique au mode token, mais le paiement s’effectue à l’appel sous-jacent, sans nécessiter de recharge préalable.
Cet article :
- parcourt réellement la chaîne « sans token + injection du handler X402 » côté TS (validation T12)
- liste les différences entre les deux chaînes de signature EVM / Solana
- fournit trois adaptations : mode clé privée
viem, mode portefeuille navigateur, mode PythonEVMAccountSigner - clarifie le champ
preferScheme/prefer_scheme, dans lequel il est facile de tomber dans un piège
I. Vue d’ensemble du protocole (à lire absolument)
Un appel X402 réussi implique 3 RTT HTTP :PAYMENT-SIGNATURE après encodage en base64. Structure (extrait) :
x402Version: 2, et utilise l’objet accepted pour déclarer le scheme et le network sélectionnés pour cette fois-ci (identifiant CAIP-2).
preferScheme / prefer_scheme permet de sélectionner une préférence lorsque le serveur propose simultanément plusieurs schemes. Si le serveur n’expose que exact, ce champ sera ignoré ; si upto est défini mais que le serveur ne l’expose pas, un repli vers le premier élément correspondant aura lieu.
II. TypeScript : deux usages, portefeuille navigateur + viem côté serveur
Installation
Signature complète de createX402PaymentHandler
(ctx) => Promise<{ headers: Record<string, string> }>, qui correspond exactement à la signature du crochet paymentHandler du SDK.
Usage 1 : navigateur (MetaMask / WalletConnect)
MaxUint256, écrit on-chain) ; la seconde est la signature EIP-712 de l’envelope X402 (elle n’est pas on-chain, elle sert seulement à la vérification du facilitator). Les appels suivants ne nécessitent que la seconde signature ; en termes d’expérience, c’est « cliquer une fois pour signer → obtenir le résultat ».
Usage 2 : serveur Node + clé privée viem (adapté au backend / CLI)
Côté TS,@acedatacloud/x402-client n’accepte que les providers EIP-1193 — il ne gère pas directement les clés privées. Dans les scénarios Node / CLI, la pratique standard consiste à utiliser viem pour encapsuler la clé privée dans un WalletClient, puis à passer par l’adaptateur EIP-1193 de @ethereumjs/util ou interne à viem.
Si vous pensez que l’adaptation EIP-1193 de viem n’est pas suffisamment stable, vous pouvez aussi passer parsignEVMUptoPayment, qui est plus bas niveau, pour relier vous-même le cheminaccepts → signed envelope → PAYMENT-SIGNATURE headeret ignorer le hook SDK ; toutefois, il est tout de même recommandé de privilégiercreateX402PaymentHandler, afin d’éviter de devoir maintenir vous-même les mises à niveau du protocole.
Utilisation 3 : Solana
exact est actuellement exposé, donc preferScheme ne fonctionne pas sur Solana.
III. Python : mode clé privée
acedatacloud-x402 en Python suit la voie de la signature directe avec une clé privée (sans abstraction EIP-1193), ce qui est plus adapté aux serveurs / exécuteurs de tâches.
Installation
EVM (Base)
Solana
Approbation unique (uniquement lors de la première utilisation EVM)
Sur EVM Base, X402 utilise Permit2, ce qui nécessite que le portefeuille effectue une fois une approbationMaxUint256 de l’USDC au contrat Permit2. acedatacloud-x402 intègre approve_permit2 :
IV. Vérification d’exécution réelle
Objectif du test : le SDK TS ne reçoit pas de token, injecte un handler X402, et peut normalement construire et initier des requêtes (vérification légère qui ne consomme pas de véritables USDC on-chain).- Sans transmettre
apiToken, la construction du SDK ne renvoie pas d’erreur, ce qui prouve que le mode X402 est bien une alternative valide au token. createX402PaymentHandlerrenvoie une fonction (hook), que le SDK n’appellera qu’après réception d’un 402.- Le test de bout en bout du paiement réel on-chain n’est pas inclus dans ce tutoriel, car il implique une déduction réelle d’USDC ; vous pouvez vous référer à l’exemple e2e dans le guide d’intégration X402.
Côté Python,create_x402_payment_handlereffectue également la même vérification —— la valeur de retour de la fonction est callable, et la construction deAceDataCloud(...)ne renvoie pas d’erreur lors de l’injection depayment_handler=.... Les sémantiques des deux côtés sont alignées.
V. Comparaison avec le « mode token Bearer »
VI. Pièges courants
- Les catégories chat doivent obligatoirement utiliser
preferScheme=upto: utiliserexactfera déduire au facilitator des USDC selonmaxAmountRequired(et non selon l’utilisation réelle). - Ne transmettez pas une clé privée brute à
createX402PaymentHandlercôté Node : le package TS n’accepte pas{ privateKey }, elle doit être encapsulée dans un provider EIP-1193 (leWalletClientde viem est recommandé). - Le premier appel nécessite une double signature : la première signe l’approbation Permit2 (on-chain, avec gas), la deuxième signe l’enveloppe X402 (hors chaîne). Les appels suivants ne conservent que la deuxième.
- Solana n’a pas de concept Permit2 : signez directement l’autorisation de transfert de token SPL, sans besoin d’approve ; mais actuellement, seule la méthode
exactest prise en charge on-chain sur Solana. - Distinguez les erreurs métier des erreurs de paiement : 402 → l’échec du handler lève
X402SignError(le type spécifique dépend de la chaîne) ; après une nouvelle tentative, les erreurs de l’interface métier (401 / 422 / 5xx) sont toujours classées comme des exceptions SDK ordinaires. - La manière la plus fiable d’adapter
viem:evmProvider: walletClient as anyperd la vérification de types mais offre la meilleure compatibilité ; si vous souhaitez conserver les types, encapsulez séparément.transport.requestde viem dans un objet{ request }et transmettez-le.

