Passer au contenu principal
En plus du paiement direct par requête API, Ace Data Cloud prend également en charge le paiement des commandes via X402. Le protocole principal du paiement de commandes et des appels API est identique : la première requête renvoie 402, le client signe PAYMENT-SIGNATURE, puis réessaie avec la même requête. La différence est que le paiement de commandes appartient à l’API de la plateforme et nécessite un jeton de compte ; tandis que l’appel direct à l’API IA de x402.acedata.cloud peut utiliser uniquement X402, sans nécessiter d’API Token.

Préparer la commande

Accédez à la console Ace Data Cloud, sélectionnez la commande à payer et notez l’ID de la commande. Si vous n’avez pas encore de commande, vous pouvez créer une commande en attente de paiement sur la page des forfaits. Le prix de la commande affiché sur la page fait foi, et le amount dans la réponse X402 402 est la base finale de la signature.

Créer un jeton de compte

Les requêtes de paiement de commandes nécessitent un jeton de compte. Ouvrez la page des Tokens de la plateforme, puis créez un token au format platform-v1-.... Utilisez dans les requêtes suivantes :
Le jeton de compte est différent d’un API Token ordinaire. Un API Token ordinaire est utilisé pour consommer le quota API ; un jeton de compte est utilisé pour représenter votre compte dans les opérations sur les ressources de la plateforme, telles que le paiement de commandes.

Déclencher 402

Envoyez d’abord une requête sans PAYMENT-SIGNATURE :
Le statut renvoyé est 402, et la réponse contient accepts :
Le paiement de commandes utilise x402 v2 officiel : x402Version vaut 2, network utilise l’identifiant CAIP-2 et le champ de montant est amount. Résultat d’exécution du programme créant une commande de 10 Credits et déclenchant 402 :
Les enregistrements de transaction suivants sont des exemples historiques testés sous l’ancienne politique ; les montants et les hachages de transaction sont conservés tels quels. Les nouvelles commandes X402 ne bénéficient plus de remises selon le mode de paiement ; veuillez utiliser le amount de cette réponse 402 comme base pour la signature et le paiement.
Explication des résultats :
  • Après la création réussie de la commande, son état est Pending, et aucun paiement on-chain n’a encore été effectué.
  • La première requête pay/ ne contient pas PAYMENT-SIGNATURE, elle renvoie donc HTTP 402.
  • accepts fournit à la fois Base exact et Solana exact ; ce tutoriel choisit ensuite Base.
  • Le prix lors de la création de la commande était de 1.26 ; pendant l’ancienne période de politique de remise pour les paiements X402, le montant réel signé et réglé était de 1.2 USDC, correspondant à 1200000 atomic USDC.
Notez que resource est un champ renvoyé par le serveur et participant à la signature ; le client ne doit pas modifier lui-même le protocole, le chemin ou l’ID de commande qu’il contient.

Signer et réessayer

Le paiement de commandes peut réutiliser les fonctions de signature bas niveau de @acedatacloud/x402-client ou acedatacloud-x402. Voici un exemple TypeScript :
Résultat d’exécution du programme après signature et nouvelle tentative de la même commande avec Base exact :
Résultat de confirmation on-chain :
Explication du résultat :
  • status 200 indique que l’interface de paiement de commande de la plateforme a accepté cette PAYMENT-SIGNATURE.
  • has_x_payment_response True indique que l’en-tête de réponse contient le reçu PAYMENT-RESPONSE encodé en Base64.
  • settle_header.success=True et network=base indiquent que le Facilitator a terminé le règlement sur Base.
  • Le statut final de la commande est Finished, pay_way est X402, et pay_id contient le hachage de la transaction on-chain.
  • L’événement Transfer sur BaseScan montre que l’adresse de paiement a transféré 1200000 USDC atomic à l’adresse de réception de la plateforme, soit 1.2 USDC.

Réponse de succès et reçu

Une fois le paiement de la commande réussi, le corps de la réponse contient les informations de la commande. La plateforme inclut également dans l’en-tête de réponse PAYMENT-RESPONSE une réponse de règlement encodée en Base64, dont les champs courants après décodage incluent : Si vous avez besoin d’effectuer un rapprochement, il est recommandé de conserver simultanément l’ID de la commande, l’adresse du portefeuille payeur, transaction et le statut final de la commande.

Points à noter

  • Le paiement de commande nécessite un jeton de compte de la plateforme et ne peut pas être effectué uniquement avec une signature de portefeuille X402.
  • amount utilise des USDC atomic units, 1200000 représente 1.2 USDC.
  • Ne composez pas vous-même l’adresse de réception ou l’adresse de l’actif ; référez-vous à accepts dans la réponse 402.
  • Si la même PAYMENT-SIGNATURE est soumise à plusieurs reprises, le Facilitator appliquera une protection contre les relectures basée sur le nonce.

Réponse d’échec du paiement

Le premier HTTP 402 sans PAYMENT-SIGNATURE est un défi de paiement normal et ne représente pas un échec de paiement. Les échecs de vérification ou de règlement après signature conservent toujours la chaîne standard error comme solution de compatibilité, et renvoient une structure d’erreur stable dans extensions.acedatacloud.paymentError :
Le client doit prioritairement localiser selon code, et revenir à un échec de paiement générique pour les codes inconnus. charged est un champ à trois états : false n’est renvoyé que lorsqu’un refus est explicitement effectué avant le règlement ; l’absence du champ indique que l’état du débit est inconnu et ne peut pas être interprétée comme « non débité ». Une fois que la commande est passée à Failed, elle ne peut pas être réessayée avec la commande d’origine ; veuillez créer une nouvelle commande après avoir corrigé le problème du portefeuille. Les champs metadata.x402.last_error et metadata.x402.errors de la liste et des détails des commandes conservent le même ensemble de code, stage, retryable, charged et params ; le texte explicatif public est conservé dans reason, et l’heure de survenue est conservée dans timestamp. Par exemple, insufficient_token_balance indique un solde USDC insuffisant sur le réseau sélectionné, et invalid_signature indique une signature de paiement invalide ; relire la commande ne les transformera pas en payment_failed générique. N’enregistrez pas et ne soumettez pas la PAYMENT-SIGNATURE complète, les signatures de portefeuille, les payloads d’autorisation, les diagnostics bruts du Facilitator ou les réponses RPC. Pour l’assistance client, seuls l’ID de la commande et le code d’erreur public sont nécessaires.

Rachat et destruction d’ACE pour les paiements Base et Solana

Après l’activation de la stratégie de rachat, 3 % des montants nets effectivement reçus en Circle USDC du réseau principal Base et en USDC du réseau principal Solana éligibles sont utilisés pour acheter et détruire des ACE, sans débit supplémentaire du portefeuille payeur. Une provision est comptabilisée une fois lors de la recharge ; l’utilisation ultérieure de ces Credits pour appeler l’API ne donne pas lieu à une provision répétée ; les commandes historiques avec remise et les commandes sous d’anciennes stratégies ne font pas automatiquement l’objet d’une provision rétroactive. Les paiements Base conservent le reçu de paiement sur la chaîne Base, tandis que l’achat et la destruction d’ACE sont exécutés de manière asynchrone sur Solana. Les paiements éligibles font l’objet d’une provision précise de 3 % selon le montant net effectivement reçu, sans plafond fixe par transaction ou quotidien pour le rachat ; les fonds disponibles, les cotations de marché et les confirmations on-chain peuvent toujours affecter le délai d’exécution. L’objet ace_burn dans les détails de la commande fournit settlement_network, settlement_transaction et execution_network, et fournit après achèvement swap_signature et burn_signature. Pending ou Processing ne signifient pas que la destruction a déjà eu lieu ; seul Completed représente que la preuve on-chain finale a été vérifiée. Lorsque le paiement Base n’a pas encore atteint la confirmation finale, le rachat attend la confirmation, mais cela n’affecte pas les Credits déjà reçus.