Passer au contenu principal
Le Facilitator est le composant de règlement côté serveur dans le flux X402. Le client est responsable de la signature, et le Gateway ou votre serveur est responsable d’appeler /verify et /settle du Facilitator. L’adresse du Facilitator de production d’Ace Data Cloud est :
Dépôt source : https://github.com/AceDataCloud/FacilitatorX402

Convention wire v2

Le flux X402 d’Ace Data Cloud utilise intégralement x402 v2 officiel et n’accepte plus l’en-tête de requête X-Payment de v1. Trois points doivent être pris en compte lors de l’intégration :
  • L’en-tête de requête est PAYMENT-SIGNATURE, et sa valeur est une enveloppe JSON encodée en base64.
  • Le niveau supérieur de l’enveloppe doit être x402Version: 2, et l’objet accepted doit être utilisé pour déclarer le scheme et le network sélectionnés cette fois-ci.
  • network utilise l’identifiant CAIP-2 (tel que eip155:8453) et ne peut pas être écrit avec une abréviation telle que base.
Structure de l’enveloppe :
En plus du body JSON, la réponse 402 inclut également un en-tête de réponse PAYMENT-REQUIRED, dont la valeur est le contenu du même challenge encodé en base64, ce qui permet au client de lire les exigences de paiement sans analyser le body.

Interfaces principales

GET /supported

Consulter les réseaux et schemes pris en charge :
Exemple de retour :
Explication des résultats :
  • network utilise l’identifiant CAIP-2, et non une abréviation telle que base ou solana.
  • /supported indique que le Facilitator dispose des capacités correspondantes de vérification et de règlement.
  • Base et Solana prennent tous deux en charge exact ; upto n’est actuellement fourni que sur Base.
  • signers sont les adresses utilisées par le Facilitator pour soumettre les transactions de règlement.
  • Pour savoir si une API spécifique autorise ces options, il faut toujours se référer à accepts de la réponse 402 de cette API.

POST /verify

Vérifier si le PAYMENT-SIGNATURE envoyé par le client satisfait à une certaine payment requirement. Corps de la requête :
Les champs paymentRequirements de v2 sont scheme, network, asset, amount, payTo, maxTimeoutSeconds et extra, et le champ du montant est amount. Le accepts[] de la réponse 402 de l’API retourne également maxAmountRequired afin que le client puisse lire la limite supérieure, mais il ne fait pas partie des champs du corps de requête du Facilitator. Réponse en cas de succès :
Après décodage, l’en-tête de réponse PAYMENT-RESPONSE des paiements de commandes de production contient le résultat du settlement. Le résultat d’exécution du programme pour le paiement d’une commande Base :
Explication des résultats :
  • success=True indique que le settlement du Facilitator a réussi.
  • transaction est le hash de transaction on-chain, et le pay_id de la commande reçoit également la même valeur.
  • L’explorer permet de voir le transfert de 1200000 atomic USDC de Base.
  • errorReason=None indique qu’aucune erreur métier n’a été retournée par ce settlement.
Un échec de vérification retourne également généralement HTTP 200, mais isValid vaut false. Le côté métier doit lire invalidReason, au lieu de ne regarder que le code de statut HTTP.

POST /settle

Régler on-chain une autorisation déjà vérifiée. Le corps de la requête est essentiellement identique à celui de /verify. La différence pour upto est que : paymentRequirements.amount est réécrit avec le montant de règlement réel lors du settle ; la limite de signature est enregistrée par le Facilitator durant la phase verify, et le montant réel ne doit pas dépasser cette limite lors du settle. Réponse en cas de succès :
Si le montant réel de upto est 0, transaction peut être une chaîne vide, indiquant qu’il n’est pas nécessaire d’émettre une transaction on-chain.

Comment l’Ace Data Cloud Gateway utilise le Facilitator

Le flux de l’API Gateway d’Ace Data Cloud est le suivant :
  1. Le client envoie sa première requête API, sans Authorization ni PAYMENT-SIGNATURE.
  2. Le Gateway calcule le prix estimé de la requête et retourne 402 et accepts.
  3. Après signature, le client réessaie avec PAYMENT-SIGNATURE.
  4. Le Gateway décode PAYMENT-SIGNATURE et sélectionne la payment requirement correspondante.
  5. Le Gateway appelle /verify du Facilitator.
  6. Après le succès de /verify, le Gateway autorise la requête vers l’API cible.
  7. Après le retour de l’API cible, le Gateway appelle /settle du Facilitator durant la phase /record.
  8. Le Gateway écrit le hash de transaction on-chain dans les metadata de l’enregistrement d’utilisation.
exact règle le montant signé à l’étape 7 ; upto écrit amount selon l’utilisation réelle à l’étape 7, puis règle le montant réel.

Comment intégrer votre propre API

Si vous souhaitez que votre propre API prenne en charge X402, vous pouvez l’implémenter selon cette structure :
  1. Préparez paymentRequirements pour chaque interface payante, y compris le réseau, le montant, l’adresse du bénéficiaire, l’adresse de l’actif et le domaine de signature.
  2. Si la requête ne contient pas PAYMENT-SIGNATURE, renvoyez HTTP 402 et accepts.
  3. Si la requête contient PAYMENT-SIGNATURE, décodez Base64 pour obtenir paymentPayload.
  4. Appelez Facilitator /verify.
  5. Exécutez la logique métier après une vérification réussie.
  6. Appelez Facilitator /settle après le succès métier.
  7. Enregistrez payer, transaction, amount, network pour le rapprochement.
Le serveur doit utiliser ses propres paymentRequirements générés pour appeler /verify et /settle, ne faites pas confiance au montant, à l’adresse du bénéficiaire ou à l’adresse de l’actif renvoyés par le client.

Protection contre la relecture

Facilitator enregistre le nonce. Une autorisation avec le même nonce ne peut pas être vérifiée ni réglée à nouveau. Cela signifie :
  • Le client doit signer une nouvelle enveloppe à chaque requête ;
  • Si /settle a déjà soumis la transaction mais n’a temporairement pas de confirmation, vous pouvez réessayer /settle avec le même nonce afin d’effectuer un rapprochement idempotent ;
  • Ne mettez pas en cache le même PAYMENT-SIGNATURE pour l’utiliser ensuite lors de plusieurs appels API.

Erreurs fréquentes