Skip to main content
Le Facilitateur est le composant de règlement côté serveur dans le lien X402. Le client est responsable de la signature, le Gateway ou votre serveur est responsable d’appeler les /verify et /settle du Facilitateur. L’adresse de production du Facilitateur d’Ace Data Cloud est :
Dépôt de code source : https://github.com/AceDataCloud/FacilitatorX402

​
Conventions v2 wire

Le lien X402 d’Ace Data Cloud utilise entièrement la version officielle x402 v2 et n’accepte plus les en-têtes de requête X-Payment v1. Lors de l’intégration, il y a trois points à noter :
  • L’en-tête de requête est PAYMENT-SIGNATURE, la valeur est un envelope JSON encodé en base64.
  • Le niveau supérieur de l’envelope doit être x402Version: 2, et déclarer le scheme et le network choisis avec l’objet accepted.
  • Le network utilise l’identifiant CAIP-2 (par exemple eip155:8453), il ne peut pas être écrit sous forme d’abréviations comme base.
Structure de l’envelope :
La réponse 402, en plus du corps JSON, contiendra également un en-tête de réponse PAYMENT-REQUIRED, dont la valeur est l’encodage base64 du même contenu de défi, facilitant la lecture des exigences de paiement par le client sans analyser le corps.

​
Interfaces principales

​
GET /supported

Voir les réseaux et schemes supportés :
Exemple de réponse :
Explication des résultats :
  • Le network utilise l’identifiant CAIP-2, pas des abréviations comme base, skale.
  • /supported indique que le Facilitateur possède les capacités de validation et de règlement correspondantes.
  • Base, SKALE et Solana supportent exact ; upto est actuellement proposé uniquement sur Base.
  • signers est l’adresse utilisée par le Facilitateur pour soumettre les transactions de règlement.
  • La possibilité d’utiliser ces options pour une API spécifique dépend toujours des accepts de cette API.

​
POST /verify

Vérifie si le PAYMENT-SIGNATURE transmis par le client satisfait une exigence de paiement donnée. Corps de la requête :
Le champ paymentRequirements de v2 est scheme, network, asset, amount, payTo, maxTimeoutSeconds et extra, le champ de montant est amount. La réponse API 402 renverra également maxAmountRequired pour que le client puisse lire la limite, mais cela ne fait pas partie des champs du corps de la requête du Facilitateur. Réponse de succès :
L’en-tête de réponse PAYMENT-RESPONSE pour le paiement de commande de production contient le résultat du règlement après décodage. Résultat de l’exécution du programme de paiement de commande Base :
Explication des résultats :
  • success=True indique que le règlement du Facilitateur a réussi.
  • transaction est le hash de la transaction sur la chaîne, l’pay_id de la commande est également écrit avec la même valeur.
  • Sur l’explorateur, on peut voir le transfert de 1200000 atomic USDC de Base USDC.
  • errorReason=None indique qu’aucune erreur commerciale n’a été retournée lors de ce règlement.
Les échecs de validation retournent également généralement un HTTP 200, mais isValid est false. Le côté commercial doit lire invalidReason, et ne pas se contenter de vérifier le code d’état HTTP.

​
POST /settle

Règle l’autorisation déjà vérifiée sur la chaîne. Le corps de la requête est essentiellement le même que pour /verify. La différence pour upto est que : paymentRequirements.amount est réécrit avec le montant réel lors du règlement ; la limite de signature est enregistrée par le Facilitateur lors de la phase de vérification, et lors du règlement, le montant réel ne doit pas dépasser cette limite. Réponse de succès :
Si le montant réel pour upto est 0, transaction peut être une chaîne vide, indiquant qu’aucune transaction sur la chaîne n’est nécessaire.

​
Comment Ace Data Cloud Gateway utilise le Facilitateur

Le lien de l’API Gateway d’Ace Data Cloud est le suivant :
  1. Le client fait une première requête API, sans Authorization ni PAYMENT-SIGNATURE.
  2. Le Gateway calcule le prix estimé de la requête, renvoie 402 et accepts.
  3. Le client signe et renvoie avec PAYMENT-SIGNATURE.
  4. Le Gateway décode le PAYMENT-SIGNATURE, choisit l’exigence de paiement correspondante.
  5. Le Gateway appelle le Facilitateur /verify.
  6. Après le succès de /verify, le Gateway laisse passer la requête vers l’API cible.
  7. Après le retour de l’API cible, le Gateway appelle le Facilitateur /settle à l’étape /record.
  8. Le Gateway écrit le hash de la transaction sur la chaîne dans les métadonnées d’utilisation. exact dans l’étape 7 pour le montant de la signature de règlement ; upto dans l’étape 7 pour écrire amount en fonction de l’utilisation réelle, puis régler le montant réel.

​
Comment intégrer votre propre API

Si vous souhaitez que votre API prenne en charge X402, vous pouvez mettre en œuvre cette structure :
  1. Préparez paymentRequirements pour chaque interface de paiement, incluant le réseau, le montant, l’adresse de réception, l’adresse d’actif et le domaine de signature.
  2. Si la requête n’a pas de PAYMENT-SIGNATURE, retournez HTTP 402 et accepts.
  3. Si la requête a un PAYMENT-SIGNATURE, décodez en Base64 pour obtenir paymentPayload.
  4. Appelez le Facilitator /verify.
  5. Après une validation réussie, exécutez la logique métier.
  6. Après le succès de l’opération, appelez le Facilitator /settle.
  7. Enregistrez payer, transaction, amount, network pour la réconciliation.
Le serveur doit utiliser ses propres paymentRequirements pour appeler /verify et /settle, ne faites pas confiance aux montants, adresses de réception ou adresses d’actif renvoyés par le client.

​
Protection contre la répétition

Le Facilitator enregistrera le nonce. Une autorisation avec le même nonce ne peut pas être validée et réglée plusieurs fois. Cela signifie :
  • Le client doit signer une nouvelle enveloppe à chaque requête ;
  • Si /settle a soumis une transaction mais n’est pas encore confirmée, vous pouvez réessayer /settle avec le même nonce pour une réconciliation idempotente ;
  • Ne mettez pas en cache le même PAYMENT-SIGNATURE pour plusieurs appels API.

​
Erreurs courantes