Zum Hauptinhalt springen
Der Facilitator ist die serverseitige Abrechnungskomponente in der X402-Kette. Der Client ist für die Signatur verantwortlich, während das Gateway oder dein Server die /verify- und /settle-Aufrufe des Facilitators übernimmt. Die Produktions-Facilitator-Adresse von Ace Data Cloud lautet:
Quellcode-Repository: https://github.com/AceDataCloud/FacilitatorX402

v2-Wire-Vereinbarungen

Die X402-Kette von Ace Data Cloud verwendet vollständig das offizielle x402 v2 und akzeptiert keine X-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: 2 enthalten und mit dem accepted-Objekt das für diese Auswahl verwendete scheme und network deklarieren.
  • network verwendet die CAIP-2-Kennung (z. B. eip155:8453) und darf nicht mit Kurzbezeichnungen wie base angegeben werden.
Envelope-Struktur:
Die 402-Antwort enthält neben dem JSON-Body auch einen 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:
Beispielantwort:
Erklärung der Ergebnisse:
  • network verwendet die CAIP-2-Kennung und keine Kurzbezeichnungen wie base oder solana.
  • /supported zeigt an, dass der Facilitator über entsprechende Verifizierungs- und Abrechnungsfunktionen verfügt.
  • Base und Solana unterstützen beide exact; upto wird derzeit nur auf Base angeboten.
  • signers sind die Adressen, die der Facilitator zur Übermittlung von Abrechnungstransaktionen verwendet.
  • Ob eine bestimmte API diese Optionen zulässt, richtet sich weiterhin nach dem accepts der 402-Antwort dieser API.

POST /verify

Überprüft, ob die vom Client übermittelte PAYMENT-SIGNATURE eine bestimmte Zahlungsanforderung erfüllt. Request-Body:
Die Felder von 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:
Der nach dem Dekodieren enthaltene PAYMENT-RESPONSE-Response-Header einer Produktionsbestellzahlung enthält das Settlement-Ergebnis. Das Programmausführungsergebnis einer Base-Bestellzahlung:
Erklärung der Ergebnisse:
  • success=True bedeutet, dass das Facilitator-Settlement erfolgreich war.
  • transaction ist der On-Chain-Transaktions-Hash; die pay_id der Bestellung wird ebenfalls mit demselben Wert geschrieben.
  • Im Explorer ist die Übertragung von 1200000 atomic USDC auf Base sichtbar.
  • errorReason=None bedeutet, dass dieses Settlement keinen Geschäftsfehler zurückgegeben hat.
Bei fehlgeschlagener Verifizierung wird in der Regel ebenfalls HTTP 200 zurückgegeben, aber 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:
Wenn der tatsächliche 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:
  1. Der Client fordert die API zum ersten Mal an, ohne Authorization und PAYMENT-SIGNATURE.
  2. Das Gateway berechnet den geschätzten Preis der Anfrage und gibt 402 und accepts zurück.
  3. Der Client signiert und versucht es erneut mit PAYMENT-SIGNATURE.
  4. Das Gateway dekodiert PAYMENT-SIGNATURE und wählt die passende Zahlungsanforderung aus.
  5. Das Gateway ruft Facilitator /verify auf.
  6. Nach erfolgreichem /verify leitet das Gateway die Anfrage an die Ziel-API weiter.
  7. Nach der Rückgabe der Ziel-API ruft das Gateway in der /record-Phase Facilitator /settle auf.
  8. 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:
  1. Bereiten Sie für jede kostenpflichtige Schnittstelle paymentRequirements vor, einschließlich Netzwerk, Betrag, Empfangsadresse, Asset-Adresse und Signatur-Domain.
  2. Wenn die Anfrage keine PAYMENT-SIGNATURE enthält, geben Sie HTTP 402 und accepts zurück.
  3. Wenn die Anfrage eine PAYMENT-SIGNATURE enthält, führen Sie eine Base64-Dekodierung durch, um paymentPayload zu erhalten.
  4. Rufen Sie Facilitator /verify auf.
  5. Führen Sie nach erfolgreicher Verifizierung die Geschäftslogik aus.
  6. Rufen Sie nach erfolgreicher Geschäftsabwicklung Facilitator /settle auf.
  7. Speichern Sie payer, transaction, amount, network für die Abstimmung.
Der Server muss die selbst generierten 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 /settle die Transaktion bereits übermittelt hat, aber vorübergehend keine Bestätigung vorliegt, kann /settle mit derselben Nonce erneut versucht werden, um eine idempotente Abstimmung durchzuführen;
  • Speichern Sie nicht dieselbe PAYMENT-SIGNATURE zwischen und verwenden Sie sie nicht für mehrere API-Aufrufe.

Häufige Fehler