Skip to main content
X402 ist ein on-chain Zahlungsprotokoll, das auf HTTP 402 Payment Required basiert. Durch die X402-Funktionalität von Ace Data Cloud kann der Aufrufer ohne Erstellung eines API-Tokens und ohne Vorauszahlung des Kontoguthabens bei jeder API-Anfrage direkt mit USDC on-chain bezahlen. Diese Dokumentation ist in der Reihenfolge des tatsächlichen Zugriffs organisiert: Zuerst einen minimalen Request erfolgreich durchführen, dann das SDK integrieren, und anschließend Netzwerke, Abrechnungsmodelle, Bestellzahlungen und Facilitator verstehen. Es wird empfohlen, die folgende Tabelle von oben nach unten zu lesen.

​
Empfohlener Integrationspfad

Wenn Sie nur die Ace Data Cloud API aufrufen möchten, verwenden Sie bevorzugt das offizielle SDK:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
Öffentliche Quellcodes und Paketadressen: Das SDK erledigt automatisch die erste nicht authentifizierte Anfrage, analysiert 402 Payment Required, ruft den Zahlungs-Handler auf und wiederholt diese Schritte mit PAYMENT-SIGNATURE. Sie müssen nur eine Wallet mit USDC vorbereiten und das gewünschte Netzwerk auswählen. Wenn Sie möchten, dass Ihre API auch X402-Zahlungen unterstützt, müssen Sie die Facilitator-Dokumentation lesen und die Beziehung zwischen paymentRequirements, paymentPayload, /verify und /settle verstehen.

​
Unterstützungsstatus

Ace Data Cloud X402 wurde in öffentlichen APIs, offiziellen SDKs, Facilitator und on-chain Abrechnungswegen validiert. Die folgende Tabelle fasst den aktuellen Status nach den am häufigsten verwendeten Funktionalitäten für Entwickler zusammen. Die folgende Ausgabe dient nur zur Veranschaulichung der Rückgabeformate des validierten Pfades. Bei der tatsächlichen Integration sollten Sie immer die aktuellen von der API zurückgegebenen accepts berücksichtigen.
Hinweis:
  • npm und PyPI-Pakete wurden erfolgreich in einer sauberen Umgebung installiert und importiert.
  • Unbezahlte API-Anfragen geben 402 zurück, accepts enthält verfügbare Zahlungsmethoden für Base, SKALE und Solana.
  • accepts[].network ist die CAIP-2 Kennung, die beim Auswählen des Netzwerks durch den Client nach CAIP-2 Zeichenfolgenübereinstimmung erfolgen muss.
  • Sowohl TypeScript SDK als auch Python SDK können 402 automatisch verarbeiten und einen bezahlten Retry durchführen.
  • Für Base exact, SKALE exact, Base upto und Bestellzahlungen gibt es öffentlich zugängliche Explorer-Adressen.
  • Die Signaturobergrenze für Base upto beträgt 95215 atomare USDC, die tatsächliche Abrechnung beträgt 3 atomare USDC, was die Eigenschaft der nachgelagerten Abrechnung nach tatsächlichem Verbrauch widerspiegelt.
  • Solana exact hat HTTP 402 -> HTTP 200 und Modellausgabe validiert. Da öffentliche RPC-Abfragen möglicherweise throttled werden, wird empfohlen, bei strengen Abgleichen eigene Solana RPC oder Plattform-seitige Abrechnungsaufzeichnungen zur Bestätigung der Transaktionsunterschrift zu verwenden.

​
Integrationshinweise

Entwickler sollten bei der Integration zunächst auf die aktuellen Zahlungsanforderungen der Anfrage achten, anstatt die Beispielbeträge oder -adressen aus der Dokumentation zu kopieren:
  • accepts[].maxAmountRequired ist der maximal signierbare Betrag für die aktuelle Anfrage.
  • accepts[].asset ist der USDC-Vertrag oder Mint, der für diese Anfrage verwendet werden soll.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress und accepts[].extra.verifyingContract werden an der EVM-typisierten Datensignatur beteiligt.
  • upto erfordert, dass die Brieftasche zuvor USDC für die Zielkette mit Permit2 autorisiert; bei fehlender Autorisierung wird PERMIT2_ALLOWANCE_REQUIRED zurückgegeben.
  • Wenn ausdrücklich nach nachgelagerter Abrechnung gewünscht wird, geben Sie im TypeScript SDK preferScheme: 'upto' an, andernfalls wählt das SDK die erste verfügbare Anforderung, die vom Server in diesem Netzwerk zurückgegeben wird.

​
Öffentlich überprüfbare Bereiche

Vor der Integration können diese öffentlichen Eingänge und SDK-Verhalten überprüft werden:
  • API-Anfragen ohne Authorization oder PAYMENT-SIGNATURE geben 402 Payment Required zurück, die accepts in der Antwort ist die einzige Signaturgrundlage für diese Anfrage.
  • Sowohl TypeScript SDK als auch Python SDK bieten einen Zahlungs-Handler, die SDK-Transportebene ruft den Handler nach Erhalt von 402 auf und versucht es erneut.
  • https://facilitator.acedata.cloud/.well-known/x402: Gibt die unterstützten Netzwerke, Schemes und Protokollendpunkte des Facilitators zurück; die API-Preise basieren weiterhin auf dem in der Zielanfrage in Echtzeit zurückgegebenen 402.
  • https://facilitator.acedata.cloud/supported: Gibt die unterstützten Netzwerke und Schemes des Facilitators zurück.
  • Das X402Client-Repository enthält fortschrittliche On-Chain-Validierungstools, die zur Bestätigung von Unterschriften, Wiederholungen und Abrechnungsverhalten verwendet werden können; die Toolausgabe ersetzt nicht die von der Online-API zurückgegebene accepts.
upto gehört zur nachgelagerten Abrechnung und eignet sich für API-Anfragen, bei denen der tatsächliche Verbrauch erst nach der Antwort bekannt ist, wie z.B. bei Chat-Vervollständigungen oder Modellaufrufen. Derzeit bietet nur Base upto an; wenn die Signaturüberprüfung fehlschlägt, überprüfen Sie, ob die Chain-ID, die Facilitator-Adresse, der Spender, der USDC-Vertrag und die Permit2-Zulassung mit der 402-Antwort übereinstimmen.