Przejdź do głównej treści
TypeScript jest jednym z najbardziej zalecanych sposobów integracji z Ace Data Cloud X402. Oficjalny SDK odpowiada za zwykłe wywołania API, odpytywanie zadań, obsługę błędów i automatyczne ponawianie prób; @acedatacloud/x402-client odpowiada za podpisywanie nagłówka żądania PAYMENT-SIGNATURE po napotkaniu 402 Payment Required. Adresy kodu źródłowego i pakietów:

Instalacja zależności

Jeśli używasz Base, potrzebujesz możliwości podpisywania EVM:
Jeśli używasz Solana, potrzebujesz adaptera portfela Solana lub @solana/web3.js:
Wynik instalacji i sprawdzenia importów w czystym projekcie npm:
Objaśnienie wyników:
  • @acedatacloud/sdk i @acedatacloud/x402-client można instalować z npm i importować przez Node.js.
  • ethers służy do podpisywania typed data EVM, a @solana/web3.js do konstruowania transakcji Solana.

Przykład Base

W przeglądarce można bezpośrednio użyć window.ethereum. W Node.js można użyć ethers.Wallet, aby opakować provider w stylu EIP-1193.

Przykład portfela w przeglądarce

Podczas używania MetaMask, Coinbase Wallet lub WalletConnect w aplikacji frontendowej zazwyczaj bezpośrednio przekazuje się provider EIP-1193:
Portfel przeglądarkowy wyświetli prośbę o potwierdzenie podpisu. Użytkownik nie podpisuje dowolnej wiadomości, lecz wymaganie płatności zwrócone przez API: adres odbiorcy, kontrakt USDC, kwota, okres ważności i nonce są wszystkie zawarte w podpisie.

Przykład Solana

Solana używa SPL USDC TransferChecked. Przekazany adapter portfela musi udostępniać publicKey i signAndSendTransaction.
Ścieżka Solana obecnie obsługuje tylko exact, a nie obsługuje upto. Jeśli API zwróci wiele accepts, handler wybierze pozycję z network = 'solana'. Ścieżka Solana została zweryfikowana na tym samym publicznym API: płatna ponowna próba może zwrócić HTTP 200 i ADC_SOLANA_E2E_OK. Publiczne zapytania RPC mogą podlegać ograniczeniom szybkości, dlatego ten artykuł nie podaje hash transakcji Solana; gdy wymagane jest uzgodnienie on-chain, użyj własnego Solana RPC lub potwierdź je w zapisach konsoli.

Wybór exact lub upto

Obecny handler TypeScript wybiera pierwsze wymaganie płatności dla pasującej sieci zwrócone przez serwer. API Ace Data Cloud zazwyczaj umieszcza exact dla tej samej sieci przed upto, dlatego jeśli wyraźnie chcesz użyć rozliczania późniejszego, musisz przekazać preferScheme: 'upto'. Przykład:
Jeśli serwer nie zwróci requirement upto dla tej sieci, handler automatycznie powróci do pierwszego dostępnego requirement dla tej sieci, zazwyczaj exact. upto wymaga jednorazowej autoryzacji Permit2. upto jest obecnie dostępne tylko na Base, dlatego wystarczy wykonać jedną autoryzację dla Base USDC:
Base upto zakończyło publiczną weryfikację API: HTTP 402 -> HTTP 200, a transakcja późniejszego settlement to 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036. Pełne dane wyjściowe znajdują się w opisie schematu rozliczeń.

Co robi SDK

Transport @acedatacloud/sdk wykona handler płatności raz po otrzymaniu 402:
Handler zwrócony przez @acedatacloud/x402-client wykona:
  1. Wybierze wymaganie płatności docelowej sieci z ctx.accepts.
  2. Skonstruuje podpis EVM EIP-712 lub transakcję transferu Solana zgodnie z siecią.
  3. Zserializuje envelope do Base64.
  4. Zwróci { headers: { 'PAYMENT-SIGNATURE': '<base64>' } }.
  5. SDK automatycznie ponowi próbę z oryginalnym body żądania.
Oznacza to, że kod biznesowy wystarczy pisać tak jak zwykłe wywołania SDK, bez konieczności ręcznej obsługi ponownych prób 402.