Passer au contenu principal
Ce tutoriel utilise une requête API minimale pour expliquer le processus complet d’Ace Data Cloud X402. L’objectif n’est pas d’écrire d’abord du code complexe, mais de comprendre d’abord : pourquoi la première requête renvoie 402, ce que contient accepts, et comment PAYMENT-SIGNATURE transforme la même requête API en requête payée.

Préparatifs

Vous devez préparer : Aucun API Token n’est requis lors de l’appel de l’API Ace Data Cloud avec X402. La première requête du SDK ne contient pas Authorization, Gateway renvoie 402 Payment Required et les exigences de paiement ; le SDK réessaie automatiquement après signature.

Installer le SDK

Sources et adresses des paquets : TypeScript :
Python :
Pour utiliser Solana, vous devez également installer les dépendances correspondantes :
La dépendance du signer Solana pour la version Python est déjà incluse dans acedatacloud-x402. La sortie de vérification de l’installation et des imports dans un environnement temporaire propre :
Explication des résultats :
  • Les paquets npm et PyPI sont tous deux des paquets réellement publiés, et non des noms fictifs dans la documentation.
  • acedatacloud-x402[cli] installe la CLI, et la sous-commande approve-permit2 peut être utilisée pour l’autorisation Permit2 dans les scénarios upto.

La première requête renvoie 402

Vous pouvez d’abord utiliser curl pour voir ce que renvoie une requête non payée. L’exemple ci-dessous ne générera aucun débit, car il ne contient pas PAYMENT-SIGNATURE :
Le corps de la réponse contient un tableau accepts, avec une structure courante comme suit :
Le même contenu de challenge est également placé sous forme base64 dans l’en-tête de réponse PAYMENT-REQUIRED, afin que le client puisse lire les exigences de paiement sans analyser le body. Le résumé de sortie du programme pour une requête non payée à l’API de production est le suivant :
Explication des résultats :
  • La première requête ne contient ni Authorization ni PAYMENT-SIGNATURE, elle renvoie donc HTTP 402 et ne génère aucun débit.
  • accepts est la seule base de signature fiable pour cette requête ; il contient les réseaux disponibles, le scheme, le plafond de montant, l’adresse du bénéficiaire et l’adresse de l’actif.
  • network est un identifiant CAIP-2 ; le client doit effectuer la correspondance du réseau selon la chaîne CAIP-2.
  • Le montant maximal de cette requête de chat minimale gpt-4o-mini est de 95215 atomic USDC, soit 0.095215 USDC.
  • Chaque requête doit lire sa réponse 402 correspondante ; n’encodez pas en dur le montant de l’exemple dans le code métier.
Signification des champs :

Effectuer une nouvelle tentative de paiement avec le SDK

Voici l’exemple TypeScript minimal. Il spécifie network: 'base', et le handler sélectionne la payment requirement de Base depuis la réponse 402 de cette requête ; le montant réel et l’adresse du bénéficiaire restent déterminés par accepts :
Quatre étapes se produisent derrière ce code :
  1. Le SDK envoie une requête API ordinaire, sans Authorization.
  2. La Gateway renvoie 402 Payment Required et accepts.
  3. createX402PaymentHandler sélectionne le payment requirement de network = 'base' et signe PAYMENT-SIGNATURE.
  4. Le SDK réessaie avec le même corps de requête, et la Gateway appelle le Facilitator pour vérifier et régler avant d’autoriser l’accès à l’API cible.

Consulter les capacités prises en charge par le Facilitator

L’API X402 ne dépend pas d’un répertoire de ressources. Le client appelle directement une API connue et utilise le 402 Payment Required et accepts renvoyés en temps réel par cette requête comme seule base pour le prix et la signature. La déclaration de capacités du Facilitator se trouve à l’adresse :
Elle décrit uniquement /supported, /verify, /settle et les réseaux de paiement actuellement activés, sans répertorier les ressources API. L’adresse du Facilitator de production d’Ace Data Cloud est :
Vous pouvez voir quels réseaux et schemes il prend en charge :
Les kinds renvoyés listent les réseaux et schemes pris en charge par le Facilitator. Lors des appels réels, référez-vous toujours aux accepts renvoyés par l’API. Sortie du Facilitator /supported :
Le résultat indique :
  • /supported indique que le Facilitator dispose de capacités de vérification et de règlement pour ces réseaux et schemes.
  • Base et Solana prennent tous deux en charge exact ; upto n’est actuellement proposé que sur Base.
  • La question de savoir si une API spécifique autorise un réseau donné dépend toujours des accepts du 402 de cette API.