Skip to main content
X402 est un protocole de paiement en chaîne basé sur HTTP 402 Payment Required. Grâce aux capacités X402 d’Ace Data Cloud, l’appelant peut effectuer un paiement en chaîne directement en USDC à chaque requête API sans créer de jeton API ni précharger le solde du compte. Ce groupe de documents est organisé selon l’ordre d’intégration réel : d’abord exécuter une requête minimale, puis intégrer le SDK, et enfin comprendre le réseau, le plan de facturation, le paiement des commandes et le Facilitateur. Il est conseillé de lire le tableau ci-dessous de haut en bas.

​
Chemin d’intégration recommandé

Si vous souhaitez simplement appeler l’API Ace Data Cloud, utilisez d’abord le SDK officiel :
  • TypeScript : @acedatacloud/sdk + @acedatacloud/x402-client
  • Python : acedatacloud + acedatacloud-x402
Adresses des sources et des paquets publics : Le SDK gérera automatiquement la première requête sans authentification, analysera le 402 Payment Required, appellera le gestionnaire de paiement et réessaiera ces étapes avec PAYMENT-SIGNATURE. Vous devez simplement préparer un portefeuille contenant des USDC et choisir le réseau que vous souhaitez utiliser. Si vous souhaitez que votre API prenne également en charge les paiements X402, vous devez lire la documentation du Facilitateur pour comprendre la relation entre paymentRequirements, paymentPayload, /verify et /settle.

​
État de support

Ace Data Cloud X402 a été validé sur l’API publique, le SDK officiel, le Facilitateur et le chemin de règlement en chaîne. Le tableau ci-dessous résume l’état actuel selon les dimensions de capacité les plus couramment utilisées lors de l’intégration par les développeurs. La sortie suivante est uniquement à des fins d’illustration des formes de retour des chemins validés. Lors de l’intégration réelle, veuillez toujours vous référer à l’accepts retourné par l’API actuelle.
Remarques :
  • Les paquets npm et PyPI ont été installés et importés avec succès dans un environnement propre.
  • Les requêtes API non payées renvoient 402, accepts contient les méthodes de paiement disponibles pour Base, SKALE et Solana.
  • accepts[].network est l’identifiant CAIP-2, le client doit correspondre à la chaîne CAIP-2 lors du choix du réseau.
  • Les SDK TypeScript et Python peuvent tous deux gérer automatiquement le 402 et effectuer une nouvelle tentative de paiement.
  • Les adresses explorer pour Base exact, SKALE exact, Base upto et le paiement de commande sont toutes accessibles publiquement.
  • La limite de signature pour Base upto est de 95215 USDC atomiques, le règlement réel est de 3 USDC atomiques, ce qui reflète la caractéristique de règlement basé sur la mesure réelle.
  • Solana exact a validé HTTP 402 -> HTTP 200 et la sortie du modèle. Étant donné que les requêtes RPC publiques peuvent être limitées, il est conseillé d’utiliser un RPC Solana propre ou des enregistrements de règlement côté plateforme pour confirmer la signature de la transaction lors d’un rapprochement strict.

​
Considérations d’intégration

Lors de l’intégration, les développeurs doivent d’abord se concentrer sur les exigences de paiement en temps réel renvoyées par la requête actuelle, plutôt que de copier les montants ou adresses d’exemple dans la documentation :
  • accepts[].maxAmountRequired est le montant maximum pouvant être signé pour la requête actuelle.
  • accepts[].asset est le contrat ou le mint USDC à utiliser pour cette requête.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress et accepts[].extra.verifyingContract participeront à la signature des données typées EVM.
  • upto nécessite que le portefeuille autorise d’abord le USDC de la chaîne cible via Permit2 ; sans autorisation, cela renverra PERMIT2_ALLOWANCE_REQUIRED.
  • Si vous souhaitez clairement utiliser la mesure postérieure, veuillez passer preferScheme: 'upto' dans le SDK TypeScript, sinon le SDK choisira le premier besoin disponible renvoyé par le serveur sous ce réseau.

​
Portée vérifiable publiquement

Avant l’intégration, vous pouvez d’abord vérifier ces points d’entrée publics et le comportement des SDK :
  • Les requêtes API sans Authorization ou PAYMENT-SIGNATURE renverront 402 Payment Required, et accepts dans la réponse est la seule base de signature pour cette requête.
  • Les SDK TypeScript et Python fournissent tous deux un gestionnaire de paiement, la couche de transport du SDK appellera le gestionnaire et réessaiera une fois après avoir reçu 402.
  • https://facilitator.acedata.cloud/.well-known/x402 : renvoie les réseaux, schémas et points de terminaison pris en charge par le Facilitateur ; le prix de l’API reste conforme au 402 renvoyé en temps réel pour la requête cible.
  • https://facilitator.acedata.cloud/supported : renvoie les réseaux et schémas pris en charge par le Facilitateur.
  • Le dépôt X402Client contient des outils de vérification avancés en chaîne, pouvant être utilisés pour confirmer les signatures, les tentatives de réessai et le comportement de règlement ; la sortie des outils ne remplace pas le accepts renvoyé par l’API en ligne.
upto appartient à un règlement basé sur la mesure postérieure, adapté aux API où la mesure réelle n’est connue qu’après la réponse, comme pour les complétions de chat ou les appels de modèle. Actuellement, seul Base propose upto ; si la vérification de la signature échoue, veuillez vérifier si l’identifiant de chaîne, l’adresse du facilitateur, le dépensier, le contrat USDC et l’allocation Permit2 correspondent à la réponse 402.