402 Payment Required. Mit den X402-Funktionen von Ace Data Cloud können Aufrufer API Token nicht erstellen und kein Kontoguthaben im Voraus aufladen, sondern die On-Chain-Zahlung direkt mit USDC in jeder API-Anfrage abschließen.
Diese Dokumentationsreihe ist nach der tatsächlichen Integrationsreihenfolge organisiert: Führe zunächst eine minimale Anfrage aus, integriere dann das SDK und verstehe anschließend Netzwerke, Abrechnungsmodelle, Bestellzahlungen und den Facilitator. Es wird empfohlen, die folgende Tabelle von oben nach unten zu lesen.
Empfohlener Integrationspfad
Wenn du nur die Ace Data Cloud API aufrufen möchtest, verwende bevorzugt die offiziellen SDKs:- TypeScript:
@acedatacloud/sdk+@acedatacloud/x402-client - Python:
acedatacloud+acedatacloud-x402
Das SDK führt automatisch die Schritte der ersten nicht authentifizierten Anfrage, der Analyse von
402 Payment Required, des Aufrufs des Payment Handlers und des erneuten Versuchs mit PAYMENT-SIGNATURE aus. Du musst nur eine Wallet mit USDC vorbereiten und das gewünschte Netzwerk auswählen.
Wenn du möchtest, dass deine eigene API ebenfalls X402-Zahlungen unterstützt, musst du die Facilitator-Dokumentation lesen und die Beziehung zwischen paymentRequirements, paymentPayload, /verify und /settle verstehen.
Unterstützungsstatus
Ace Data Cloud X402 wurde für öffentliche APIs, offizielle SDKs, den Facilitator und On-Chain-Abrechnungswege validiert. Die folgende Tabelle fasst den aktuellen Status nach den Funktionsdimensionen zusammen, die bei der Entwicklerintegration am häufigsten verwendet werden.
Die folgende Ausgabe dient nur zur Veranschaulichung der Rückgabeform der validierten Pfade. Bei der tatsächlichen Integration sollte immer das von der aktuellen API zurückgegebene
accepts maßgeblich sein.
- Sowohl npm- als auch PyPI-Pakete wurden in einer sauberen Umgebung installiert und erfolgreich importiert.
- Unbezahlte API-Anfragen geben 402 zurück, und
acceptsenthält verfügbare Zahlungsmethoden für Base und Solana. accepts[].networkist eine CAIP-2-Kennung; Clients müssen beim Auswählen eines Netzwerks anhand der CAIP-2-Zeichenfolge übereinstimmen.- Sowohl das TypeScript SDK als auch das Python SDK können 402 automatisch verarbeiten und den bezahlten Retry abschließen.
- Für Base
exact, Baseuptound Bestellzahlungen gibt es öffentlich aufrufbare Explorer-Adressen. - Das signierte Limit von Base
uptobeträgt95215Atomic USDC, während das tatsächliche Settlement bei3Atomic USDC liegt, was die Eigenschaft der nachgelagerten verbrauchsbasierten Abrechnung nach tatsächlicher Nutzung widerspiegelt. - Für Solana
exactwurden HTTP 402 -> HTTP 200 und die Modellausgabe verifiziert. Da öffentliche RPC-Abfragen rate-limitiert sein können, wird für einen strikten Abgleich empfohlen, einen eigenen Solana RPC oder plattformseitige Settlement-Aufzeichnungen zur Bestätigung der Transaktionssignatur zu verwenden.
Hinweise zur Integration
Bei der Entwickler-Integration sollten Sie vorrangig die Echtzeit-Zahlungsanforderungen der aktuellen Anfrage beachten, statt Beispielbeträge oder Adressen aus der Dokumentation zu kopieren:accepts[].maxAmountRequiredist der maximal signierbare Betrag für die aktuelle Anfrage.accepts[].assetist der USDC-Vertrag oder Mint, der für diese Anfrage verwendet werden soll.accepts[].extra.chainId,accepts[].extra.facilitatorAddressundaccepts[].extra.verifyingContractwerden an der EVM-Typed-Data-Signatur beteiligt.uptoerfordert, dass die Wallet zunächst Permit2 für USDC auf der Ziel-Chain autorisiert; ohne Autorisierung wirdPERMIT2_ALLOWANCE_REQUIREDzurückgegeben.- Wenn Sie ausdrücklich nachgelagerte Verbrauchsabrechnung verwenden möchten, übergeben Sie im TypeScript SDK
preferScheme: 'upto'; andernfalls wählt das SDK die erste verfügbare Requirement, die der Server für dieses Netzwerk zurückgibt.
Öffentlich überprüfbarer Umfang
Vor der Integration können zunächst diese öffentlichen Endpunkte und SDK-Verhalten überprüft werden:- API-Anfragen ohne
AuthorizationoderPAYMENT-SIGNATUREgeben402 Payment Requiredzurück; dasacceptsin der Antwort ist die einzige Signaturgrundlage für diese Anfrage. - Sowohl das TypeScript SDK als auch das Python SDK stellen einen Payment Handler bereit; die SDK-Transportschicht ruft den Handler nach Erhalt von 402 auf und versucht es einmal erneut.
https://facilitator.acedata.cloud/.well-known/x402: Gibt die vom Facilitator unterstützten Netzwerke, Schemes und Protokollendpunkte zurück; die API-Preise richten sich weiterhin nach dem in Echtzeit zurückgegebenen 402 der Zielanfrage.https://facilitator.acedata.cloud/supported: Gibt die vom Facilitator unterstützten Netzwerke und Schemes zurück.- Das X402Client-Repository enthält fortgeschrittene On-Chain-Verifizierungstools, die zur Bestätigung von Signaturen, Retries und Settlement-Verhalten verwendet werden können; die Tool-Ausgabe ersetzt nicht das von der Online-API zurückgegebene
accepts.
upto gehört zur nachgelagerten verbrauchsbasierten Abrechnung und eignet sich für APIs wie Chat-Completions und Modellaufrufe, bei denen der tatsächliche Verbrauch erst nach der Antwort bekannt ist. Derzeit bietet nur Base upto an; wenn die Signaturvalidierung fehlschlägt, prüfen Sie bitte, ob Chain ID, Facilitator-Adresse, Spender, USDC-Vertrag und Permit2-Allowance mit der 402-Antwort übereinstimmen.
