Zum Hauptinhalt springen
Dieses Tutorial erläutert den vollständigen Ablauf von Ace Data Cloud X402 anhand einer minimalen API-Anfrage. Das Ziel ist nicht, zuerst komplexen Code zu schreiben, sondern zunächst zu verstehen: Warum die erste Anfrage 402 zurückgibt, was sich in accepts befindet und wie PAYMENT-SIGNATURE dieselbe API-Anfrage in eine bezahlte Anfrage verwandelt.

Vorbereitung

Du musst Folgendes vorbereiten: Bei X402-Aufrufen der Ace Data Cloud API ist kein API-Token erforderlich. Die erste SDK-Anfrage enthält kein Authorization, das Gateway gibt 402 Payment Required und die Zahlungsanforderungen zurück; nach der SDK-Signatur wird automatisch erneut versucht.

SDK installieren

Quellcode und Paketadressen: TypeScript:
Python:
Für die Verwendung von Solana müssen außerdem die entsprechenden Abhängigkeiten installiert werden:
Die Solana-Signer-Abhängigkeiten der Python-Version sind bereits in acedatacloud-x402 enthalten. Installations- und Importprüfungs-Ausgabe in einer sauberen temporären Umgebung:
Ergebnisbeschreibung:
  • Sowohl npm-Pakete als auch PyPI-Pakete sind tatsächlich veröffentlichte Pakete und keine Platzhalternamen in der Dokumentation.
  • acedatacloud-x402[cli] installiert die CLI; der Unterbefehl approve-permit2 kann für Permit2-Autorisierungen im upto-Szenario verwendet werden.

Die erste Anfrage gibt 402 zurück

Du kannst zunächst mit curl prüfen, was eine unbezahlte Anfrage zurückgibt. Das folgende Beispiel verursacht keine Belastung, da es keine PAYMENT-SIGNATURE enthält:
Der Antworttext enthält ein accepts-Array, dessen übliche Struktur wie folgt aussieht:
Derselbe Challenge-Inhalt wird auch in Base64-Form im Antwort-Header PAYMENT-REQUIRED abgelegt, damit der Client die Zahlungsanforderungen lesen kann, ohne den Body zu parsen. Die folgende Programmausgabe-Zusammenfassung stammt von einer unbezahlten Anfrage an die Produktions-API:
Ergebnisbeschreibung:
  • Die erste Anfrage enthält weder Authorization noch PAYMENT-SIGNATURE, daher wird HTTP 402 zurückgegeben und keine Belastung verursacht.
  • accepts ist die einzige vertrauenswürdige Signaturgrundlage für diese Anfrage und enthält optionale Netzwerke, Schemes, Betragsobergrenzen, Empfangsadressen und Asset-Adressen.
  • network ist eine CAIP-2-Kennung; der Client muss bei der Netzwerkauswahl anhand der CAIP-2-Zeichenfolge übereinstimmen.
  • Die Betragsobergrenze für diese minimale Chat-Anfrage mit gpt-4o-mini beträgt 95215 atomic USDC, also 0.095215 USDC.
  • Für jede Anfrage sollte die jeweilige 402-Antwort gelesen werden; Beispielbeträge dürfen nicht fest im Geschäftscode codiert werden.
Feldbedeutungen:

Zahlungswiederholung mit dem SDK abschließen

Im Folgenden steht ein minimales TypeScript-Beispiel. Es gibt network: 'base' an, und der Handler wählt aus der jeweiligen 402-Antwort die Zahlungsanforderung für Base aus; der tatsächliche Betrag und die Empfangsadresse richten sich weiterhin nach accepts:
Hinter diesem Code passieren vier Schritte:
  1. Das SDK sendet eine gewöhnliche API-Anfrage ohne Authorization.
  2. Das Gateway gibt 402 Payment Required und accepts zurück.
  3. createX402PaymentHandler wählt die payment requirement von network = 'base' aus und signiert PAYMENT-SIGNATURE.
  4. Das SDK wiederholt die Anfrage mit demselben Anfragekörper, und das Gateway ruft den Facilitator zur Verifizierung und Abwicklung auf, bevor es die Anfrage an die Ziel-API weiterleitet.

Unterstützte Fähigkeiten des Facilitators anzeigen

Die X402 API ist nicht von einem Ressourcenverzeichnis abhängig. Der Client ruft die bekannte API direkt auf und verwendet das von dieser Anfrage in Echtzeit zurückgegebene 402 Payment Required und accepts als einzige Grundlage für Preis und Signatur. Die Fähigkeitserklärung des Facilitators befindet sich unter:
Sie beschreibt nur /supported, /verify, /settle und die aktuell aktivierten Zahlungsnetzwerke, und listet keine API-Ressourcen auf. Die Produktions-Facilitator-Adresse von Ace Data Cloud lautet:
Sie können prüfen, welche Netzwerke und Schemes es unterstützt:
Die zurückgegebenen kinds listen die vom Facilitator unterstützten Netzwerke und Schemes auf. Bei tatsächlichen Aufrufen gelten weiterhin die von der API zurückgegebenen accepts. Facilitator-/supported-Ausgabe:
Die Ergebnisse zeigen:
  • /supported zeigt, dass der Facilitator über Verifizierungs- und Abwicklungsfähigkeiten für diese Netzwerke und Schemes verfügt.
  • Base und Solana unterstützen beide exact; upto wird derzeit nur auf Base angeboten.
  • Ob eine konkrete API ein bestimmtes Netzwerk zulässt, richtet sich weiterhin nach den 402-accepts dieser API.