Passer au contenu principal
X402 est un protocole de paiement on-chain basé sur HTTP 402 Payment Required. Grâce à la capacité X402 d’Ace Data Cloud, les appelants peuvent ne pas créer d’API Token, ne pas prérecharger le solde de leur compte, et effectuer directement un paiement on-chain en USDC dans chaque requête API. Cet ensemble de documents est organisé selon l’ordre réel d’intégration : exécutez d’abord une requête minimale, puis intégrez le SDK, et comprenez ensuite les réseaux, les modèles de facturation, le paiement des commandes et le Facilitator. Il est recommandé de les lire de haut en bas selon le tableau ci-dessous.

Parcours d’intégration recommandé

Si vous souhaitez seulement appeler l’API Ace Data Cloud, privilégiez le SDK officiel :
  • TypeScript : @acedatacloud/sdk + @acedatacloud/x402-client
  • Python : acedatacloud + acedatacloud-x402
Code source public et adresses des packages : Le SDK effectuera automatiquement ces étapes : première requête non authentifiée, analyse de 402 Payment Required, appel du payment handler et nouvelle tentative avec PAYMENT-SIGNATURE. Vous devez seulement préparer un portefeuille contenant des USDC et choisir le réseau que vous souhaitez utiliser. Si vous souhaitez également permettre à votre propre API d’accepter des paiements X402, vous devez lire la documentation du Facilitator afin de comprendre la relation entre paymentRequirements, paymentPayload, /verify et /settle.

État de prise en charge

Ace Data Cloud X402 a été validé sur les API publiques, les SDK officiels, le Facilitator et le flux de règlement on-chain. Le tableau ci-dessous récapitule 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 utilisée pour illustrer le format de retour des parcours validés. Lors de l’intégration réelle, veuillez toujours vous référer aux accepts renvoyés par l’API actuelle.
Remarques :
  • Les paquets npm et PyPI ont tous été installés et importés avec succès dans un environnement propre.
  • Les requêtes API non payées renvoient 402, et accepts contient les méthodes de paiement disponibles pour Base et Solana.
  • accepts[].network est un identifiant CAIP-2 ; le client doit effectuer la sélection du réseau en faisant correspondre la chaîne CAIP-2.
  • Le SDK TypeScript et le SDK Python peuvent tous deux gérer automatiquement 402 et effectuer une nouvelle tentative payée.
  • Base exact, Base upto et le paiement de commande disposent tous d’adresses explorer accessibles publiquement.
  • La limite signée de Base upto est de 95215 USDC atomiques, tandis que le settlement réel est de 3 USDC atomiques, ce qui reflète la caractéristique de règlement selon l’utilisation réelle de la facturation a posteriori.
  • 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 en débit, il est recommandé d’utiliser votre propre RPC Solana ou les enregistrements de règlement côté plateforme pour confirmer la signature de transaction lors d’un rapprochement strict.

Points d’attention pour l’intégration

Lors de l’intégration, les développeurs doivent prioritairement prêter attention aux 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 de la documentation :
  • accepts[].maxAmountRequired est le montant maximal pouvant être signé pour la requête actuelle.
  • accepts[].asset est le contrat USDC ou le mint à utiliser pour cette requête.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress et accepts[].extra.verifyingContract participent à la signature des données typées EVM.
  • upto nécessite que le portefeuille autorise d’abord Permit2 pour l’USDC de la chaîne cible ; en l’absence d’autorisation, PERMIT2_ALLOWANCE_REQUIRED sera renvoyé.
  • Si vous souhaitez explicitement utiliser la facturation a posteriori, transmettez preferScheme: 'upto' dans le SDK TypeScript ; sinon, le SDK sélectionnera la première requirement disponible renvoyée par le serveur sur ce réseau.

Portée pouvant être vérifiée publiquement

Avant l’intégration, vous pouvez d’abord vérifier ces points d’entrée publics et comportements des SDK :
  • Les requêtes API sans Authorization ou PAYMENT-SIGNATURE renvoient 402 Payment Required ; les accepts dans la réponse constituent l’unique base de signature pour cette requête.
  • Le SDK TypeScript et le SDK Python fournissent tous deux un payment handler ; après réception d’un 402, la couche de transport du SDK appellera le handler et effectuera une nouvelle tentative.
  • https://facilitator.acedata.cloud/.well-known/x402 : renvoie les réseaux, schemes et points de terminaison de protocole pris en charge par le Facilitator ; le prix de l’API reste basé sur le 402 renvoyé en temps réel par la requête cible.
  • https://facilitator.acedata.cloud/supported : renvoie les réseaux et schemes pris en charge par le Facilitator.
  • Le dépôt X402Client contient des outils avancés de vérification on-chain, qui peuvent être utilisés pour confirmer les comportements de signature, de nouvelle tentative et de settlement ; la sortie des outils ne remplace pas les accepts renvoyés par l’API en ligne.
upto relève du règlement par facturation a posteriori, adapté aux API telles que les complétions de chat et les appels de modèles, dont l’utilisation réelle n’est connue qu’après la réponse. Actuellement, seule Base fournit upto ; si la vérification de signature échoue, vérifiez que le chain id, l’adresse du facilitator, le spender, le contrat USDC et l’allocation Permit2 correspondent à la réponse 402.