/verify- und /settle-Aufrufe des Facilitators übernimmt.
Die Produktions-Facilitator-Adresse von Ace Data Cloud lautet:
v2-Wire-Vereinbarungen
Die X402-Kette von Ace Data Cloud verwendet vollständig das offizielle x402 v2 und akzeptiert keineX-Payment-Request-Header von v1 mehr. Bei der Integration müssen drei Punkte beachtet werden:
- Der Request-Header lautet
PAYMENT-SIGNATURE, und sein Wert ist ein base64-kodiertes JSON-Envelope. - Die oberste Ebene des Envelopes muss
x402Version: 2enthalten und mit demaccepted-Objekt das für diese Auswahl verwendeteschemeundnetworkdeklarieren. networkverwendet die CAIP-2-Kennung (z. B.eip155:8453) und darf nicht mit Kurzbezeichnungen wiebaseangegeben werden.
PAYMENT-REQUIRED-Response-Header. Sein Wert ist die base64-Kodierung desselben Challenge-Inhalts, damit Clients die Zahlungsanforderungen lesen können, ohne den Body zu parsen.
Kernschnittstellen
GET /supported
Unterstützte Netzwerke und Schemes anzeigen:
networkverwendet die CAIP-2-Kennung und keine Kurzbezeichnungen wiebaseodersolana./supportedzeigt an, dass der Facilitator über entsprechende Verifizierungs- und Abrechnungsfunktionen verfügt.- Base und Solana unterstützen beide
exact;uptowird derzeit nur auf Base angeboten. signerssind die Adressen, die der Facilitator zur Übermittlung von Abrechnungstransaktionen verwendet.- Ob eine bestimmte API diese Optionen zulässt, richtet sich weiterhin nach dem
acceptsder 402-Antwort dieser API.
POST /verify
Überprüft, ob die vom Client übermittelte PAYMENT-SIGNATURE eine bestimmte Zahlungsanforderung erfüllt.
Request-Body:
paymentRequirements in v2 sind scheme, network, asset, amount, payTo, maxTimeoutSeconds und extra; das Betragsfeld ist amount. In accepts[] der API-402-Antwort wird zusätzlich maxAmountRequired zurückgegeben, damit der Client die Obergrenze auslesen kann, es gehört jedoch nicht zu den Feldern des Facilitator-Request-Bodys.
Erfolgsantwort:
PAYMENT-RESPONSE-Response-Header einer Produktionsbestellzahlung enthält das Settlement-Ergebnis. Das Programmausführungsergebnis einer Base-Bestellzahlung:
success=Truebedeutet, dass das Facilitator-Settlement erfolgreich war.transactionist der On-Chain-Transaktions-Hash; diepay_idder Bestellung wird ebenfalls mit demselben Wert geschrieben.- Im Explorer ist die Übertragung von
1200000atomic USDC auf Base sichtbar. errorReason=Nonebedeutet, dass dieses Settlement keinen Geschäftsfehler zurückgegeben hat.
isValid ist false. Die Geschäftsseite sollte invalidReason auslesen, statt nur den HTTP-Statuscode zu prüfen.
POST /settle
Rechnet die bereits verifizierte Autorisierung On-Chain ab.
Der Request-Body ist grundsätzlich mit /verify identisch. Der Unterschied bei upto besteht darin: paymentRequirements.amount wird beim Settlement auf den tatsächlich abzurechnenden Betrag umgeschrieben; das Signaturlimit wird vom Facilitator in der Verify-Phase gespeichert, und beim Settlement wird überprüft, dass der tatsächliche Betrag dieses Limit nicht überschreitet.
Erfolgsantwort:
upto-Betrag 0 ist, kann transaction ein leerer String sein, was bedeutet, dass keine On-Chain-Transaktion gesendet werden muss.
Wie das Ace Data Cloud Gateway den Facilitator verwendet
Die Kette des Ace Data Cloud API Gateways ist wie folgt:- Der Client fordert die API zum ersten Mal an, ohne
AuthorizationundPAYMENT-SIGNATURE. - Das Gateway berechnet den geschätzten Preis der Anfrage und gibt 402 und
acceptszurück. - Der Client signiert und versucht es erneut mit
PAYMENT-SIGNATURE. - Das Gateway dekodiert
PAYMENT-SIGNATUREund wählt die passende Zahlungsanforderung aus. - Das Gateway ruft Facilitator
/verifyauf. - Nach erfolgreichem
/verifyleitet das Gateway die Anfrage an die Ziel-API weiter. - Nach der Rückgabe der Ziel-API ruft das Gateway in der
/record-Phase Facilitator/settleauf. - Das Gateway schreibt den On-Chain-Transaktions-Hash in die Metadata des Nutzungsdatensatzes.
exact rechnet den signierten Betrag in Schritt 7 ab; upto schreibt in Schritt 7 den amount entsprechend der tatsächlichen Nutzung und rechnet anschließend den tatsächlichen Betrag ab.
Wie eigene APIs integriert werden
Wenn du möchtest, dass deine eigene API X402 unterstützt, kannst du sie nach dieser Struktur implementieren:- Bereiten Sie für jede kostenpflichtige Schnittstelle
paymentRequirementsvor, einschließlich Netzwerk, Betrag, Empfangsadresse, Asset-Adresse und Signatur-Domain. - Wenn die Anfrage keine
PAYMENT-SIGNATUREenthält, geben Sie HTTP 402 undacceptszurück. - Wenn die Anfrage eine
PAYMENT-SIGNATUREenthält, führen Sie eine Base64-Dekodierung durch, umpaymentPayloadzu erhalten. - Rufen Sie Facilitator
/verifyauf. - Führen Sie nach erfolgreicher Verifizierung die Geschäftslogik aus.
- Rufen Sie nach erfolgreicher Geschäftsabwicklung Facilitator
/settleauf. - Speichern Sie
payer,transaction,amount,networkfür die Abstimmung.
paymentRequirements für den Aufruf von /verify und /settle verwenden, vertrauen Sie nicht auf den vom Client zurückgegebenen Betrag, die Empfangsadresse oder die Asset-Adresse.
Schutz vor Wiederholungen
Der Facilitator zeichnet Nonces auf. Autorisierungen mit derselben Nonce können nicht wiederholt verifiziert und abgewickelt werden. Das bedeutet:- Der Client sollte bei jeder Anfrage ein neues Envelope signieren;
- Wenn
/settledie Transaktion bereits übermittelt hat, aber vorübergehend keine Bestätigung vorliegt, kann/settlemit derselben Nonce erneut versucht werden, um eine idempotente Abstimmung durchzuführen; - Speichern Sie nicht dieselbe
PAYMENT-SIGNATUREzwischen und verwenden Sie sie nicht für mehrere API-Aufrufe.

