Zum Hauptinhalt springen
TypeScript ist eine der am meisten empfohlenen Methoden zur Integration von Ace Data Cloud X402. Das offizielle SDK ist für normale API-Aufrufe, Task-Polling, Fehlerbehandlung und automatische Wiederholungsversuche zuständig; @acedatacloud/x402-client ist dafür zuständig, bei 402 Payment Required den Request-Header PAYMENT-SIGNATURE zu signieren. Quellcode- und Paketadressen:

Abhängigkeiten installieren

Bei Verwendung von Base werden EVM-Signaturfähigkeiten benötigt:
Bei Verwendung von Solana wird ein Solana Wallet Adapter oder @solana/web3.js benötigt:
Installations- und Import-Prüfausgabe eines sauberen npm-Projekts:
Erklärung der Ergebnisse:
  • @acedatacloud/sdk und @acedatacloud/x402-client können beide über npm installiert und von Node.js importiert werden.
  • ethers wird für EVM Typed-Data-Signaturen verwendet, @solana/web3.js für die Konstruktion von Solana-Transaktionen.

Base-Beispiel

Im Browser kann window.ethereum direkt verwendet werden. In Node.js kann ethers.Wallet verwendet werden, um einen Provider im EIP-1193-Stil zu umschließen.

Browser-Wallet-Beispiel

Bei Verwendung von MetaMask, Coinbase Wallet oder WalletConnect in Frontend-Anwendungen wird normalerweise der EIP-1193-Provider direkt übergeben:
Das Browser-Wallet zeigt eine Signaturbestätigung an. Der Benutzer signiert keine beliebige Nachricht, sondern die von der API zurückgegebene Zahlungsanforderung: Empfängeradresse, USDC-Vertrag, Betrag, Gültigkeitsdauer und Nonce sind alle in der Signatur enthalten.

Solana-Beispiel

Solana verwendet SPL USDC TransferChecked. Der übergebene Wallet Adapter muss publicKey und signAndSendTransaction bereitstellen.
Der Solana-Pfad unterstützt derzeit nur exact, nicht upto. Wenn die API mehrere accepts zurückgibt, wählt der Handler den Eintrag mit network = 'solana'. Der Solana-Pfad wurde auf derselben öffentlichen API verifiziert, wobei ein Paid Retry HTTP 200 und ADC_SOLANA_E2E_OK zurückgeben kann. Öffentliche RPC-Abfragen können rate-limitiert sein, daher wird in diesem Artikel kein Solana-Tx-Hash angegeben; wenn ein On-Chain-Abgleich erforderlich ist, verwenden Sie bitte Ihre eigene Solana RPC oder bestätigen Sie anhand von Konsolenprotokollen.

exact oder upto auswählen

Der aktuelle TypeScript-Handler wählt die erste Payment Requirement des passenden Netzwerks, die vom Server zurückgegeben wird. Die API von Ace Data Cloud platziert normalerweise exact desselben Netzwerks vor upto; wenn Sie also ausdrücklich die nachgelagerte Abrechnung verwenden möchten, müssen Sie preferScheme: 'upto' übergeben. Beispiel:
Wenn der Server keine upto Requirement für dieses Netzwerk zurückgibt, fällt der Handler automatisch auf die erste verfügbare Requirement dieses Netzwerks zurück, normalerweise exact. upto benötigt eine einmalige Permit2-Genehmigung. upto wird derzeit nur auf Base angeboten, daher muss nur für Base USDC eine einmalige Genehmigung erteilt werden:
Base upto hat die öffentliche API-Verifizierung abgeschlossen: HTTP 402 -> HTTP 200, die nachgelagerte Settlement-Tx lautet 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036. Die vollständige Ausgabe finden Sie in der Erläuterung des Abrechnungsmodells.

Was das SDK macht

Der Transport von @acedatacloud/sdk führt beim Empfang von 402 einmal einen Payment Handler aus:
Der von @acedatacloud/x402-client zurückgegebene Handler wird:
  1. Die Payment Requirement des Zielnetzwerks aus ctx.accepts auswählen.
  2. Je nach Netzwerk eine EVM-EIP-712-Signatur oder eine Solana-Transfer-Transaktion konstruieren.
  3. Das Envelope als Base64 serialisieren.
  4. { headers: { 'PAYMENT-SIGNATURE': '<base64>' } } zurückgeben.
  5. Das SDK führt automatisch einen Wiederholungsversuch mit dem ursprünglichen Request-Body aus.
Das bedeutet, dass der Geschäftscode nur wie bei einem gewöhnlichen SDK-Aufruf geschrieben werden muss und 402-Wiederholungsversuche nicht manuell verarbeitet werden müssen.