Skip to main content
Neben der direkten Bezahlung pro API-Anfrage unterstützt Ace Data Cloud auch die Bezahlung von Bestellungen über die X402-Zahlungskonsole. Bestellzahlungen und API-Aufrufe verwenden dasselbe Kernprotokoll: Die erste Anfrage gibt 402 zurück, der Client stellt PAYMENT-SIGNATURE aus und wiederholt die Anfrage dann mit derselben Anfrage. Der Unterschied besteht darin, dass Bestellzahlungen Plattform-APIs sind und ein Kontotoken benötigen; die direkte Nutzung der AI-API von x402.acedata.cloud kann nur X402 verwenden und benötigt kein API-Token.

Bestellung vorbereiten

Rufe die Ace Data Cloud-Konsole auf, wähle die zu bezahlende Bestellung aus und notiere die Bestell-ID. Wenn du noch keine Bestellung hast, kannst du auf der Paket-Seite eine noch zu bezahlende Bestellung erstellen. Der Bestellpreis richtet sich nach der Anzeige auf der Seite; das amount in der X402-402-Antwort ist die endgültige Grundlage für die Signatur.

Kontotoken erstellen

Anfragen zur Bestellzahlung benötigen ein Kontotoken. Öffne die Plattform-Token-Seite und erstelle ein Token im Format platform-v1-.... Verwende für nachfolgende Anfragen:
Das Kontotoken unterscheidet sich von einem normalen API-Token. Normale API-Token werden zum Verbrauch von API-Guthaben verwendet; Kontotoken werden verwendet, um Plattformressourcen im Namen deines Kontos zu bedienen, beispielsweise Bestellzahlungen.

402 auslösen

Sende zunächst eine Anfrage ohne PAYMENT-SIGNATURE:
Der zurückgegebene Status ist 402, und die Antwort enthält accepts:
Die Bestellzahlung verwendet das offizielle x402 v2: x402Version ist 2, network verwendet die CAIP-2-Kennung, und das Betragsfeld ist amount. Programmausgabe beim Erstellen einer Bestellung über 10 Credits und beim Auslösen von 402:
Die folgenden Transaktionsaufzeichnungen sind historische, praktisch getestete Beispiele unter der alten Richtlinie; Beträge und Transaktions-Hashes bleiben unverändert. Neue X402-Bestellungen erhalten keinen Zahlungsartenrabatt mehr; verwende für Signatur und Zahlung bitte das amount aus der aktuellen 402-Antwort.
Erläuterung der Ergebnisse:
  • Nach erfolgreicher Erstellung der Bestellung lautet der Status Pending; zu diesem Zeitpunkt gibt es noch keine On-Chain-Zahlung.
  • Die erste pay/-Anfrage enthält keine PAYMENT-SIGNATURE, daher wird HTTP 402 zurückgegeben.
  • accepts enthält gleichzeitig Base exact und Solana exact; in dieser Anleitung wird anschließend Base ausgewählt.
  • Der Preis bei der Bestellungserstellung beträgt 1.26; bei Zahlung während der alten X402-Zahlungsrabattrichtlinie betrugen der tatsächlich signierte und abgerechnete Betrag 1.2 USDC, entsprechend 1200000 Atomic USDC.
Beachte, dass resource hier ein vom Server zurückgegebenes und an der Signatur beteiligtes Feld ist; der Client darf das darin enthaltene Protokoll, den Pfad oder die Bestell-ID nicht selbst umschreiben.

Signieren und erneut versuchen

Für Bestellzahlungen können die Low-Level-Signaturfunktionen von @acedatacloud/x402-client oder acedatacloud-x402 wiederverwendet werden. Nachfolgend ein TypeScript-Beispiel:
Programmausgabe nach Signierung und erneutem Versuch derselben Bestellung mit Base exact:
Ergebnis der On-Chain-Bestätigung:
Erklärung der Ergebnisse:
  • status 200 bedeutet, dass die Plattform-Bestellzahlungsschnittstelle diese PAYMENT-SIGNATURE akzeptiert hat.
  • has_x_payment_response True bedeutet, dass der Response-Header einen Base64-kodierten PAYMENT-RESPONSE-Beleg enthält.
  • settle_header.success=True und network=base bedeuten, dass der Facilitator das Base-Settlement abgeschlossen hat.
  • Der endgültige Bestellstatus ist Finished, pay_way ist X402, und pay_id enthält den On-Chain-Transaktionshash.
  • Das Transfer-Ereignis auf BaseScan zeigt, dass die Zahlungsadresse 1200000 atomic USDC, also 1.2 USDC, an die Plattform-Empfangsadresse überwiesen hat.

Erfolgreiche Antwort und Beleg

Nach erfolgreicher Bestellzahlung enthält der Response-Body die Bestellinformationen. Die Plattform übermittelt außerdem im Response-Header PAYMENT-RESPONSE eine Base64-kodierte Settlement-Response, deren dekodierte häufige Felder Folgendes umfassen: Wenn du einen Abgleich benötigst, wird empfohlen, gleichzeitig die Bestell-ID, die Zahlungs-Wallet-Adresse, transaction und den endgültigen Bestellstatus zu speichern.

Hinweise

  • Für die Bestellzahlung ist ein Plattformkonto-Token erforderlich; sie kann nicht allein mit einer X402-Wallet-Signatur abgeschlossen werden.
  • amount verwendet USDC atomic units, 1200000 bedeutet 1.2 USDC.
  • Setze Empfangs- oder Asset-Adressen nicht selbst zusammen; maßgeblich ist accepts in der 402-Response.
  • Wenn dieselbe PAYMENT-SIGNATURE wiederholt übermittelt wird, führt der Facilitator anhand der Nonce einen Replay-Schutz durch.

Antwort bei fehlgeschlagener Zahlung

Das erste HTTP 402 ohne PAYMENT-SIGNATURE ist eine normale Zahlungs-Challenge und bedeutet nicht, dass die Zahlung fehlgeschlagen ist. Bei einem Fehler der signierten Verifizierung oder des Settlements bleibt das standardmäßige String-error als kompatibler Fallback erhalten, und unter extensions.acedatacloud.paymentError wird eine stabile Fehlerstruktur zurückgegeben:
Der Client sollte vorrangig anhand von code lokalisieren; bei unbekanntem Code sollte auf einen allgemeinen Zahlungsfehler zurückgefallen werden. charged ist ein dreistufiges Feld: Nur wenn vor dem Settlement eindeutig abgelehnt wird, wird false zurückgegeben; ein fehlendes Feld bedeutet, dass der Belastungsstatus unbekannt ist, und darf nicht als „nicht belastet“ interpretiert werden. Nachdem die aktuelle Bestellung in Failed übergeht, kann sie nicht mit derselben Bestellung erneut versucht werden; erstelle nach Behebung des Wallet-Problems eine neue Bestellung. Protokolliere oder übermittle nicht die vollständige PAYMENT-SIGNATURE, Wallet-Signaturen, autorisierte Payloads, ursprüngliche Facilitator-Diagnosen oder RPC-Responses. Für die Untersuchung durch den Kundendienst werden nur die Bestell-ID und der öffentliche Fehler-code benötigt.