Passer au contenu principal
TypeScript est l’une des méthodes les plus recommandées pour intégrer Ace Data Cloud X402. Le SDK officiel est responsable des appels API ordinaires, du polling des tâches, de la gestion des erreurs et des nouvelles tentatives automatiques ; @acedatacloud/x402-client est responsable de la signature de l’en-tête de requête PAYMENT-SIGNATURE lorsqu’un 402 Payment Required est rencontré. Adresses des sources et des packages :

Installer les dépendances

Si vous utilisez Base, des capacités de signature EVM sont nécessaires :
Si vous utilisez Solana, un wallet adapter Solana ou @solana/web3.js est nécessaire :
Sortie de la vérification d’installation et d’importation d’un projet npm propre :
Explication des résultats :
  • @acedatacloud/sdk et @acedatacloud/x402-client peuvent tous deux être installés depuis npm et importés par Node.js.
  • ethers est utilisé pour les signatures de typed data EVM, et @solana/web3.js pour la construction de transactions Solana.

Exemple Base

Dans le navigateur, vous pouvez utiliser directement window.ethereum. Dans Node.js, vous pouvez envelopper ethers.Wallet dans un provider de style EIP-1193.

Exemple de wallet navigateur

Lors de l’utilisation de MetaMask, Coinbase Wallet ou WalletConnect dans une application front-end, vous transmettez généralement directement le provider EIP-1193 :
Le wallet navigateur affichera une confirmation de signature. Ce que l’utilisateur signe n’est pas un message arbitraire, mais l’exigence de paiement renvoyée par l’API : l’adresse du bénéficiaire, le contrat USDC, le montant, la durée de validité et le nonce sont tous inclus dans la signature.

Exemple Solana

Solana utilise SPL USDC TransferChecked. Le wallet adapter transmis doit exposer publicKey et signAndSendTransaction.
Le chemin Solana ne prend actuellement en charge que exact, et ne prend pas en charge upto. Si l’API renvoie plusieurs accepts, le handler sélectionnera celui avec network = 'solana'. Le chemin Solana a déjà vérifié sur la même API publique que la nouvelle tentative payante peut renvoyer HTTP 200 et ADC_SOLANA_E2E_OK. Les requêtes RPC publiques peuvent être limitées en débit, donc cet article n’indique pas le hash de transaction Solana ; lorsque vous avez besoin d’une réconciliation on-chain, veuillez utiliser votre propre RPC Solana ou la confirmation enregistrée dans la console.

Choisir exact ou upto

Le handler TypeScript actuel sélectionne la première payment requirement du réseau correspondant renvoyée par le serveur. L’API d’Ace Data Cloud place généralement exact du même réseau avant upto, donc si vous souhaitez explicitement utiliser la facturation a posteriori, vous devez transmettre preferScheme: 'upto'. Exemple :
Si le serveur ne renvoie pas de requirement upto pour ce réseau, le handler reviendra automatiquement à la première requirement disponible pour ce réseau, généralement exact. upto nécessite une autorisation Permit2 unique. upto n’est actuellement fourni que sur Base, il suffit donc d’effectuer une seule autorisation pour Base USDC :
Base upto a terminé la vérification de l’API publique : HTTP 402 -> HTTP 200, et la transaction de settlement a posteriori est 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036. Consultez la documentation du plan de facturation pour la sortie complète.

Ce que fait le SDK

Le transport de @acedatacloud/sdk exécute une fois le payment handler lors de la réception d’un 402 :
Le handler renvoyé par @acedatacloud/x402-client va :
  1. Sélectionner la payment requirement du réseau cible dans ctx.accepts.
  2. Construire une signature EVM EIP-712 ou une transaction de transfert Solana selon le réseau.
  3. Sérialiser l’envelope en Base64.
  4. Renvoyer { headers: { 'PAYMENT-SIGNATURE': '<base64>' } }.
  5. Le SDK effectue automatiquement une nouvelle tentative avec le corps de requête d’origine.
Cela signifie que le code métier doit seulement être écrit comme un appel SDK ordinaire, sans avoir besoin de gérer manuellement les nouvelles tentatives 402.