Zum Hauptinhalt springen
Neben der direkten Zahlung pro API-Anfrage unterstützt Ace Data Cloud auch die Zahlung von Bestellungen über die X402-Zahlungskonsole. Die Bestellzahlung und API-Aufrufe verwenden dasselbe Kernprotokoll: Die erste Anfrage gibt 402 zurück, der Client erstellt die Signatur PAYMENT-SIGNATURE und versucht die Anfrage dann erneut. Der Unterschied besteht darin, dass die Bestellzahlung eine Plattform-API ist und ein Kontotoken benötigt; während die direkte Nutzung der AI-API von x402.acedata.cloud nur X402 verwenden kann und kein API-Token benötigt.

Bestellung vorbereiten

Gehe zur Ace Data Cloud-Konsole, wähle die zu zahlende Bestellung aus und notiere die Bestell-ID. Falls du noch keine Bestellung hast, kannst du auf der Tarifseite eine ausstehende Bestellung erstellen. Der Bestellpreis richtet sich nach der Anzeige auf der Seite; 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 gewöhnlichen API-Token. Gewöhnliche API-Tokens werden zum Verbrauch von API-Guthaben verwendet; Kontotokens 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 Zahlungsart-Rabatt mehr; verwende bitte amount aus der aktuellen 402-Antwort als Grundlage für Signatur und Zahlung.
Erläuterung der Ergebnisse:
  • Nach erfolgreicher Erstellung der Bestellung ist ihr Status Pending; zu diesem Zeitpunkt gibt es noch keine On-Chain-Zahlung.
  • Die erste pay/-Anfrage enthält keine PAYMENT-SIGNATURE und gibt daher HTTP 402 zurück.
  • accepts gibt gleichzeitig Base exact und Solana exact an; dieses Tutorial wählt im Folgenden Base.
  • Der Preis bei der Bestellungserstellung beträgt 1.26; bei Zahlung während der alten X402-Zahlungsrabattrichtlinie betrug 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 ändern.

Signieren und erneut versuchen

Für die Bestellzahlung können die Low-Level-Signaturfunktionen von @acedatacloud/x402-client oder acedatacloud-x402 wiederverwendet werden. Nachfolgend ein TypeScript-Beispiel:
Programmausgabe nach der Signatur und dem erneuten Versuch derselben Bestellung mit Base exact:
Ergebnis der On-Chain-Bestätigung:
Ergebnisbeschreibung:
  • status 200 zeigt an, dass die Zahlungs-API der Plattform diese PAYMENT-SIGNATURE akzeptiert hat.
  • has_x_payment_response True zeigt an, dass der Antwort-Header den Base64-kodierten PAYMENT-RESPONSE-Beleg enthält.
  • settle_header.success=True und network=base zeigen an, 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-Transaktions-Hash.
  • Das Transfer-Ereignis auf BaseScan zeigt, dass die Zahlungsadresse 1200000 atomic USDC, also 1.2 USDC, an die Empfangsadresse der Plattform überwiesen hat.

Erfolgreiche Antwort und Beleg

Nach erfolgreicher Bestellzahlung enthält der Antworttext die Bestellinformationen. Die Plattform führt außerdem im Antwort-Header PAYMENT-RESPONSE die Base64-kodierte Settlement-Antwort mit, deren häufige Felder nach der Dekodierung Folgendes umfassen: Wenn Sie eine Abstimmung benötigen, wird empfohlen, gleichzeitig die Bestell-ID, die Wallet-Adresse des Zahlers, transaction und den endgültigen Bestellstatus zu speichern.

Hinweise

  • Die Bestellzahlung benötigt ein Plattformkonto-Token und kann nicht allein mit einer X402-Wallet-Signatur abgeschlossen werden.
  • amount verwendet USDC atomic units, 1200000 steht für 1.2 USDC.
  • Setzen Sie Empfangs- oder Asset-Adressen nicht selbst zusammen; maßgeblich sind die accepts in der 402-Antwort.
  • Wenn dieselbe PAYMENT-SIGNATURE wiederholt übermittelt wird, führt der Facilitator anhand des Nonce einen Replay-Schutz durch.

Antwort bei Zahlungsfehler

Die erste HTTP 402 ohne PAYMENT-SIGNATURE ist eine normale Zahlungsaufforderung und bedeutet keinen Zahlungsfehler. Bei einem Fehler bei der signierten Verifizierung oder beim Settlement bleibt der standardmäßige String error als kompatibler Fallback erhalten, und unter extensions.acedatacloud.paymentError wird eine stabile Fehlerstruktur zurückgegeben:
Der Client sollte bevorzugt anhand von code lokalisieren; unbekannte Codes fallen auf einen allgemeinen Zahlungsfehler zurück. charged ist ein dreistufiges Feld: Nur bei einer eindeutigen Ablehnung vor dem Settlement wird false zurückgegeben; ein fehlendes Feld bedeutet, dass der Abbuchungsstatus unbekannt ist, und darf nicht als „nicht abgebucht“ interpretiert werden. Nachdem die aktuelle Bestellung in Failed übergegangen ist, kann sie nicht als dieselbe Bestellung erneut versucht werden; erstellen Sie nach der Behebung des Wallet-Problems eine neue Bestellung. metadata.x402.last_error und metadata.x402.errors in der Bestellliste und den Bestelldetails behalten dieselbe Gruppe aus code, stage, retryable, charged und params; der öffentliche Beschreibungstext wird in reason gespeichert, und der Zeitpunkt des Auftretens wird in timestamp gespeichert. Beispielsweise bedeutet insufficient_token_balance, dass das USDC-Guthaben im ausgewählten Netzwerk nicht ausreicht, und invalid_signature bedeutet, dass die Zahlungssignatur ungültig ist; ein erneutes Abrufen der Bestellung ändert sie nicht in das allgemeine payment_failed. Protokollieren oder übermitteln Sie nicht die vollständige PAYMENT-SIGNATURE, Wallet-Signaturen, Autorisierungs-Payloads, ursprüngliche Facilitator-Diagnosen oder RPC-Antworten. Für die Support-Fehlersuche werden nur die Bestell-ID und der öffentliche Fehler-code benötigt.

ACE-Rückkauf und -Verbrennung für Base- und Solana-Zahlungen

Nach Aktivierung der Rückkaufstrategie werden 3 % der tatsächlich eingegangenen Beträge von qualifiziertem Circle USDC im Base-Mainnet und USDC im Solana-Mainnet zum Kauf und zur Verbrennung von ACE verwendet, ohne der Wallet des Zahlers zusätzlich etwas zu berechnen. Die Rückstellung erfolgt einmal bei der Aufladung; bei der späteren Nutzung dieser Credits zum Aufrufen der API erfolgt keine wiederholte Rückstellung; historische rabattierte Bestellungen und Bestellungen mit alten Strategien werden nicht automatisch rückwirkend berücksichtigt. Base-Zahlungen behalten den Zahlungsbeleg auf der Base-Chain, während der Kauf und die Verbrennung von ACE asynchron auf Solana ausgeführt werden. Für qualifizierte Zahlungen werden exakt 3 % des tatsächlich eingegangenen Betrags zurückgestellt, ohne feste Obergrenze für Rückkäufe pro Einzeltransaktion oder pro Tag; verfügbare Mittel, Marktpreise und On-Chain-Bestätigungen können dennoch die Abschlusszeit beeinflussen. Das Objekt ace_burn in den Bestelldetails stellt settlement_network, settlement_transaction und execution_network bereit und stellt nach Abschluss swap_signature und burn_signature bereit. Pending oder Processing bedeutet nicht, dass bereits verbrannt wurde; nur Completed steht dafür, dass der endgültige On-Chain-Nachweis überprüft wurde. Wenn eine Base-Zahlung noch keine endgültige Bestätigung erreicht hat, wartet der Rückkauf auf die Bestätigung, ohne die bereits eingegangenen Credits zu beeinträchtigen.