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
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.
- 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
acceptscontient les méthodes de paiement disponibles pour Base et Solana. accepts[].networkest 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, Baseuptoet le paiement de commande disposent tous d’adresses explorer accessibles publiquement. - La limite signée de Base
uptoest de95215USDC atomiques, tandis que le settlement réel est de3USDC atomiques, ce qui reflète la caractéristique de règlement selon l’utilisation réelle de la facturation a posteriori. - Solana
exacta 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[].maxAmountRequiredest le montant maximal pouvant être signé pour la requête actuelle.accepts[].assetest le contrat USDC ou le mint à utiliser pour cette requête.accepts[].extra.chainId,accepts[].extra.facilitatorAddressetaccepts[].extra.verifyingContractparticipent à la signature des données typées EVM.uptonécessite que le portefeuille autorise d’abord Permit2 pour l’USDC de la chaîne cible ; en l’absence d’autorisation,PERMIT2_ALLOWANCE_REQUIREDsera 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
AuthorizationouPAYMENT-SIGNATURErenvoient402 Payment Required; lesacceptsdans 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
acceptsrenvoyé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.
