Vérifier l’entrée publique
Déclaration de capacités du Facilitator :facilitator, supportedKinds et les points de terminaison du protocole sont retournés, les métadonnées de capacités sont normales. La découverte des ressources API a été retirée ; veuillez appeler directement l’API cible et vous baser sur la réponse 402 en temps réel.
Capacités prises en charge par le Facilitator :
kinds est retourné, l’entrée du Facilitator fonctionne normalement.
Vérifier accepts dans la réponse 402
Envoyez une requête non authentifiée qui ne sera pas facturée :
accepts dans la réponse contient le réseau que vous souhaitez utiliser. network est un identifiant CAIP-2 :
eip155:8453+exact(Base)eip155:8453+upto(Base, comptage post-utilisation)solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp+exact(Solana)
Exécuter les outils de validation avancée X402Client
Le dépôt X402Client fournit des outils de validation avancée, qui peuvent être utilisés pour confirmer la sélection de la réponse 402, la génération de signatures, le paid retry et le settlement on-chain. Ils nécessitent un wallet approvisionné, un RPC, une clé privée et des dépendances de développement. Pour une intégration métier classique, il est recommandé de privilégier les SDK TypeScript ou Python ; n’exécutez ces outils que lorsque vous devez localiser des problèmes de signature ou de règlement on-chain. Adresse du dépôt : https://github.com/AceDataCloud/X402Client- La réponse 402 de la première requête.
- La payment requirement sélectionnée.
- Le résumé du
PAYMENT-SIGNATUREaprès signature. - Le statut HTTP et le corps de réponse après la nouvelle tentative.
- La transaction de settlement on-chain, ou la cause de l’erreur du Facilitator en cas d’échec.
PAYMENT-SIGNATURE complets vers le système de journaux ou dans les tickets.
Exemple de résultats de validation de l’API publique :
- Base
exact, Solanaexactet Baseuptoont tous effectué un paid retry de HTTP 402 à HTTP 200. - La transaction on-chain de Base
exactest consultable sur BaseScan, et le montant du règlement est de95215atomic USDC. - La limite signée de Base
uptoest de95215atomic USDC, mais le settlement on-chain réel est de3atomic USDC, ce qui indique que le comptage post-utilisation facture selon l’usage réel. - Le chemin Solana a confirmé le paid retry et la sortie du modèle. Les RPC publics peuvent être limités en débit ; lorsqu’un rapprochement on-chain strict est nécessaire, veuillez utiliser votre propre RPC Solana ou les enregistrements de règlement côté plateforme pour confirmer la signature de transaction.
Test smoke du SDK
Les outils de validation avancée sont utilisés pour vérifier les signatures et le règlement on-chain. Le côté métier doit également exécuter un test smoke du SDK pour confirmer que le code d’application peut traiter automatiquement les 402 via le payment handler. Seuls les extraits principaux sont présentés ci-dessous ; le code complet doit compléter le wallet, le provider et les imports. TypeScript :exact et règlent le montant fixe coté dans la réponse 402. Les complétions de chat sont un scénario mesuré en tokens ; pour l’intégration en production, il est recommandé de transmettre preferScheme: 'upto' (en Python : prefer_scheme="upto"), afin de régler selon l’usage réel.
L’objet retourné par le SDK Python est un dict ; vous pouvez utiliser res["choices"][0]["message"]["content"] pour lire le contenu.
E2E de paiement de commande
Le paiement de commande utilise l’API de plateforme deplatform.acedata.cloud et nécessite un jeton de compte de plateforme. La chaîne complète est la suivante : créer une commande Pending, déclencher une 402 avec POST /api/v1/orders/{order_id}/pay/, puis réessayer avec PAYMENT-SIGNATURE.
Exemple de résultats de validation de paiement de petite commande :
Les enregistrements de transactions suivants sont des exemples historiques testés sous l’ancienne politique ; les montants et les hachages de transactions sont conservés tels quels. Les nouvelles commandes X402 ne bénéficient plus de remises liées au mode de paiement ; veuillez utiliser le champ amount de la réponse 402 actuelle comme base pour la signature et le paiement.
- Après la création de la commande, l’état de la commande est
Pending, et le prix est1.26. - La première requête
pay/renvoie HTTP 402 ;acceptscontient Baseexactet Solanaexact, avec des montants de1200000USDC atomiques. - Après une nouvelle tentative avec la
PAYMENT-SIGNATUREBase, elle renvoie HTTP 200, l’état de la commande passe àFinished, etpay_wayestX402. - Après décodage de
PAYMENT-RESPONSE, il affichesuccess=True,network=base, et fournit le même hachage de transaction. - Sur BaseScan, le statut de la transaction est
1, le montant du transfert est de1200000USDC atomiques, soit1.2USDC. - Le prix de création
1.26a été payé pendant la période de l’ancienne politique de réduction de paiement X402 ; le montant final de la signature et du règlement est de1.2USDC.
Authorization: Bearer {platform_token}, ou si la commande n’appartient pas au compte actuel, il échouera au niveau des autorisations de la plateforme ; cela diffère de l’API X402 sans compte de x402.acedata.cloud appelée directement.
Erreurs courantes
Liste de contrôle Base upto
upto est actuellement fourni uniquement sur Base (eip155:8453). Comme la signature upto lie davantage de paramètres de données typées EVM, il convient de vérifier particulièrement que les champs en temps réel de la réponse 402 correspondent exactement à la signature du client lors de l’intégration.
upto renvoie invalid_upto_evm_payload_invalid_signature, vérifiez en priorité :
- Le
extra.chainId(doit être8453) dans l’entréeeip155:8453+uptorenvoyée par l’API. - Le
extra.facilitatorAddressrenvoyé par l’API. - L’adresse du facilitator Base
uptorenvoyée parhttps://facilitator.acedata.cloud/supported. - Le domaine Permit2, le spender, le contrat USDC et le compte de signature.
- Si le portefeuille a déjà approuvé Permit2 pour l’USDC Base.
upto lie simultanément le domaine Permit2, l’ID de chaîne, le spender, l’adresse de réception, l’adresse du facilitator et validAfter. Si l’un de ces éléments ne correspond pas, le Facilitator récupérera un signer incorrect et renverra donc une signature invalide. Si tous ces éléments correspondent mais qu’il renvoie encore 402, vérifiez ensuite l’allocation Permit2 ; en l’absence d’autorisation, il renvoie PERMIT2_ALLOWANCE_REQUIRED.
Enregistrer les informations de vérification
Une vérification complète doit au minimum enregistrer :- le chemin de l’API et le résumé du corps de requête ;
- le network et le scheme sélectionnés ;
maxAmountRequired;- l’adresse du portefeuille payer ;
- le statut final HTTP ;
- la sortie du modèle ou l’ID de tâche dans la réponse ;
- le lien de la transaction de settlement ;
- l’ID de trace Gateway ou l’ID d’enregistrement d’utilisation de la plateforme.
PAYMENT-SIGNATURE complète, la signature EIP-712 complète ou la phrase mnémonique.
Erreurs de paiement structurées
Les échecs X402 après signature renvoient dansextensions.acedatacloud.paymentError un code stable, des paramètres d’interpolation sûrs, une étape et un indicateur de possibilité de nouvelle tentative. Utilisez prioritairement cette structure pour le diagnostic ; n’analysez pas l’anglais error de premier niveau, et ne demandez pas aux utilisateurs de fournir des signatures de portefeuille ou le texte original des simulations on-chain.
charged: false: la vérification a explicitement refusé avant le règlement ; aucun débit n’a été initié cette fois-ci.- Sans
charged: le résultat est inconnu ou est déjà entré dans la phase de règlement ; vérifiez d’abord la commande et le statut on-chain, il est interdit de répéter directement le paiement. settlement_pending: ne répétez pas le paiement pour l’instant ; actualisez d’abord la commande ou contactez le support.- Code non reconnu : traitez-le comme
payment_failed, et conservez le code technique public afin que le service client puisse le rechercher.

