/verify et /settle du Facilitator.
L’adresse du Facilitator de production d’Ace Data Cloud est :
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êteX-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’objetaccepteddoit être utilisé pour déclarer leschemeet lenetworksélectionnés cette fois-ci. networkutilise l’identifiant CAIP-2 (tel queeip155:8453) et ne peut pas être écrit avec une abréviation telle quebase.
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 :
networkutilise l’identifiant CAIP-2, et non une abréviation telle quebaseousolana./supportedindique que le Facilitator dispose des capacités correspondantes de vérification et de règlement.- Base et Solana prennent tous deux en charge
exact;upton’est actuellement fourni que sur Base. signerssont 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 à
acceptsde 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 :
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 :
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 :
success=Trueindique que le settlement du Facilitator a réussi.transactionest le hash de transaction on-chain, et lepay_idde la commande reçoit également la même valeur.- L’explorer permet de voir le transfert de
1200000atomic USDC de Base. errorReason=Noneindique qu’aucune erreur métier n’a été retournée par ce settlement.
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 :
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 :- Le client envoie sa première requête API, sans
AuthorizationniPAYMENT-SIGNATURE. - Le Gateway calcule le prix estimé de la requête et retourne 402 et
accepts. - Après signature, le client réessaie avec
PAYMENT-SIGNATURE. - Le Gateway décode
PAYMENT-SIGNATUREet sélectionne la payment requirement correspondante. - Le Gateway appelle
/verifydu Facilitator. - Après le succès de
/verify, le Gateway autorise la requête vers l’API cible. - Après le retour de l’API cible, le Gateway appelle
/settledu Facilitator durant la phase/record. - 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 :- Préparez
paymentRequirementspour 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. - Si la requête ne contient pas
PAYMENT-SIGNATURE, renvoyez HTTP 402 etaccepts. - Si la requête contient
PAYMENT-SIGNATURE, décodez Base64 pour obtenirpaymentPayload. - Appelez Facilitator
/verify. - Exécutez la logique métier après une vérification réussie.
- Appelez Facilitator
/settleaprès le succès métier. - Enregistrez
payer,transaction,amount,networkpour le rapprochement.
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
/settlea déjà soumis la transaction mais n’a temporairement pas de confirmation, vous pouvez réessayer/settleavec le même nonce afin d’effectuer un rapprochement idempotent ; - Ne mettez pas en cache le même
PAYMENT-SIGNATUREpour l’utiliser ensuite lors de plusieurs appels API.

