Passer au contenu principal
X402 implique HTTP, le SDK, les signatures, le Facilitator et les transactions on-chain. Lors du dépannage de problèmes de signature ou de règlement, il est recommandé de confirmer chaque niveau dans l’ordre « entrée publique -> réponse 402 -> payment handler du SDK -> settlement on-chain ». Ce tutoriel explique les méthodes de vérification de chaque niveau et liste les erreurs courantes.

Vérifier l’entrée publique

Déclaration de capacités du Facilitator :
Si 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 :
Si 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 :
Vérifiez si 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)
Si le réseau cible est absent, cela signifie que cette API ou l’environnement actuel n’a pas configuré le mode d’encaissement X402 correspondant.

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
Base :
Solana :
Les outils de validation affichent généralement :
  1. La réponse 402 de la première requête.
  2. La payment requirement sélectionnée.
  3. Le résumé du PAYMENT-SIGNATURE après signature.
  4. Le statut HTTP et le corps de réponse après la nouvelle tentative.
  5. La transaction de settlement on-chain, ou la cause de l’erreur du Facilitator en cas d’échec.
N’envoyez pas de clés privées ni de PAYMENT-SIGNATURE complets vers le système de journaux ou dans les tickets. Exemple de résultats de validation de l’API publique :
Explications :
  • Base exact, Solana exact et Base upto ont tous effectué un paid retry de HTTP 402 à HTTP 200.
  • La transaction on-chain de Base exact est consultable sur BaseScan, et le montant du règlement est de 95215 atomic USDC.
  • La limite signée de Base upto est de 95215 atomic USDC, mais le settlement on-chain réel est de 3 atomic 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 :
Python :
Si le modèle retourne la chaîne fixe comme demandé, cela indique que le SDK, le payment handler, le Gateway, le Facilitator et l’API cible sont reliés. Les deux tests smoke ci-dessus utilisent Base 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 de platform.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.
Explication des résultats :
  • Après la création de la commande, l’état de la commande est Pending, et le prix est 1.26.
  • La première requête pay/ renvoie HTTP 402 ; accepts contient Base exact et Solana exact, avec des montants de 1200000 USDC atomiques.
  • Après une nouvelle tentative avec la PAYMENT-SIGNATURE Base, elle renvoie HTTP 200, l’état de la commande passe à Finished, et pay_way est X402.
  • Après décodage de PAYMENT-RESPONSE, il affiche success=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 de 1200000 USDC atomiques, soit 1.2 USDC.
  • Le prix de création 1.26 a é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 de 1.2 USDC.
Si le paiement de la commande ne comporte pas 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.
Si Base upto renvoie invalid_upto_evm_payload_invalid_signature, vérifiez en priorité :
  1. Le extra.chainId (doit être 8453) dans l’entrée eip155:8453 + upto renvoyée par l’API.
  2. Le extra.facilitatorAddress renvoyé par l’API.
  3. L’adresse du facilitator Base upto renvoyée par https://facilitator.acedata.cloud/supported.
  4. Le domaine Permit2, le spender, le contrat USDC et le compte de signature.
  5. Si le portefeuille a déjà approuvé Permit2 pour l’USDC Base.
Le digest de signature de 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.
N’enregistrez pas les clés privées, la 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 dans extensions.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.