Vai al contenuto principale
TypeScript è uno dei modi più consigliati per integrare Ace Data Cloud X402. L’SDK ufficiale è responsabile delle normali chiamate API, del polling delle attività, della gestione degli errori e dei retry automatici; @acedatacloud/x402-client è responsabile della firma dell’header di richiesta PAYMENT-SIGNATURE quando si incontra 402 Payment Required. Indirizzi del codice sorgente e dei pacchetti:

Installare le dipendenze

Se si usa Base, è necessaria la capacità di firma EVM:
Se si usa Solana, è necessario un wallet adapter Solana oppure @solana/web3.js:
Output di controllo dell’installazione e dell’importazione in un progetto npm pulito:
Descrizione dei risultati:
  • Sia @acedatacloud/sdk sia @acedatacloud/x402-client possono essere installati da npm e importati da Node.js.
  • ethers viene usato per la firma dei typed data EVM, @solana/web3.js viene usato per la costruzione delle transaction Solana.

Esempio Base

Nel browser si può usare direttamente window.ethereum. In Node.js si può usare ethers.Wallet per avvolgere un provider in stile EIP-1193.

Esempio di wallet nel browser

Quando si usano MetaMask, Coinbase Wallet o WalletConnect in un’applicazione frontend, solitamente si passa direttamente il provider EIP-1193:
Il wallet nel browser mostrerà una conferma della firma. Ciò che l’utente firma non è un messaggio arbitrario, bensì il requisito di pagamento restituito dall’API: l’indirizzo del destinatario, il contratto USDC, l’importo, la scadenza e il nonce sono tutti inclusi nella firma.

Esempio Solana

Solana usa SPL USDC TransferChecked. Il wallet adapter passato deve esporre publicKey e signAndSendTransaction.
Il percorso Solana al momento supporta solo exact, non supporta upto. Se l’API restituisce più accepts, l’handler sceglierà quella con network = 'solana'. Il percorso Solana ha già verificato sulla stessa API pubblica che il paid retry può restituire HTTP 200 e ADC_SOLANA_E2E_OK. Le query RPC pubbliche potrebbero essere soggette a limitazione della frequenza, quindi questo articolo non riporta l’hash della tx Solana; quando è necessaria la riconciliazione on-chain, usa il tuo RPC Solana o la conferma dei record della console.

Scegliere exact oppure upto

L’attuale handler TypeScript sceglierà il primo payment requirement della rete corrispondente restituito dal server. L’API di Ace Data Cloud solitamente mette exact della stessa rete prima di upto, quindi se vuoi esplicitamente usare la misurazione postpagata, devi passare preferScheme: 'upto'. Esempio:
Se il server non restituisce un requirement upto per quella rete, l’handler effettuerà automaticamente il fallback al primo requirement disponibile per quella rete, solitamente exact. upto richiede un’autorizzazione Permit2 una tantum. upto è attualmente disponibile solo su Base, quindi è necessario effettuare un’autorizzazione una sola volta per Base USDC:
Base upto ha completato la verifica dell’API pubblica: HTTP 402 -> HTTP 200, la settlement tx postpagata è 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036. L’output completo è disponibile nella descrizione dello schema di fatturazione.

Cosa fa l’SDK

Il transport di @acedatacloud/sdk eseguirà una volta il payment handler quando riceve un 402:
L’handler restituito da @acedatacloud/x402-client:
  1. Seleziona il payment requirement della rete target da ctx.accepts.
  2. Costruisce una firma EVM EIP-712 o una transaction di trasferimento Solana in base alla rete.
  3. Serializza l’envelope in Base64.
  4. Restituisce { headers: { 'PAYMENT-SIGNATURE': '<base64>' } }.
  5. L’SDK ritenta automaticamente usando il corpo della richiesta originale.
Ciò significa che il codice business deve solo essere scritto come una normale chiamata SDK, senza dover gestire manualmente il retry 402.