402 Payment Required alle richieste senza token, allegando il campo accepts: [...] che elenca chain / asset / prezzo accettabili; il client firma localmente un’autorizzazione (Permit2 / EIP-712 su EVM, autorizzazione al trasferimento di SPL token su Solana), inserisce l’envelope codificato in base64 nell’header PAYMENT-SIGNATURE e reinvia. Dopo la verifica, il server effettua effettivamente il regolamento on-chain, quindi restituisce il risultato di business.
Il client X402 di Ace Data Cloud chiama direttamente l’API di destinazione e utilizza ilSia402 Payment Requiredeacceptsrestituiti in tempo reale da tale richiesta come base per il prezzo e la firma. La capacità di pagamento del Facilitator può essere verificata su/.well-known/x402.
@acedatacloud/sdk sia acedatacloud espongono un hook paymentHandler: quando una richiesta inviata dallo SDK riceve un 402, richiama l’handler da te iniettato per ottenere l’header PAYMENT-SIGNATURE, quindi reinvia la richiesta originale. Usando @acedatacloud/x402-client / acedatacloud-x402 insieme allo SDK, l’intero processo è completamente trasparente al codice di business——ti basta usare client.openai.chat.completions.create(...), e sembra esattamente uguale alla modalità token, ma sotto il cofano il pagamento è per chiamata e non richiede ricariche preventive.
Questo articolo:
- percorre realmente la catena «senza token + iniezione dell’handler X402» sul lato TS (verifica T12)
- elenca le differenze tra le due catene di firma EVM / Solana
- fornisce tre adattamenti: modalità chiave privata
viem, modalità wallet del browser e modalità PythonEVMAccountSigner - chiarisce il campo
preferScheme/prefer_scheme, in cui è facile imbattersi in problemi
I. Panoramica del protocollo (da leggere assolutamente)
Una chiamata X402 riuscita coinvolge 3 HTTP RTT:PAYMENT-SIGNATURE. Struttura (estratto):
x402Version: 2 e dichiara tramite l’oggetto accepted lo scheme e il network selezionati per questa volta (identificatore CAIP-2).
preferScheme / prefer_scheme serve a scegliere una preferenza quando il server fornisce simultaneamente più scheme. Se il server espone solo exact, questo campo verrà ignorato; se viene impostato upto ma il server non lo espone, verrà usato come fallback il primo elemento corrispondente.
II. TypeScript: due utilizzi, wallet del browser + viem sul server
Installazione
Firma completa di createX402PaymentHandler
(ctx) => Promise<{ headers: Record<string, string> }> che corrisponde esattamente alla firma dell’hook paymentHandler dello SDK.
Utilizzo 1: browser (MetaMask / WalletConnect)
MaxUint256, scritto on-chain); la seconda è la firma EIP-712 dell’envelope X402 (non va on-chain, serve solo alla verifica del facilitator). Le chiamate successive richiedono solo la seconda firma; dal punto di vista dell’esperienza è “fare clic una volta per firmare → ottenere il risultato”.
Utilizzo 2: server Node + chiave privata viem (adatto a backend / CLI)
@acedatacloud/x402-client sul lato TS accetta solo provider EIP-1193——non gestisce direttamente le chiavi private. Negli scenari Node / CLI, l’approccio standard è usare viem per incapsulare la chiave privata in un WalletClient, quindi passare attraverso l’adattamento EIP-1193 di @ethereumjs/util o quello interno di viem.
Se ritieni che l’adattamento EIP-1193 di viem non sia abbastanza stabile, puoi anche usare il più basso livellosignEVMUptoPayment, concatenando autonomamente il percorsoaccepts → signed envelope → PAYMENT-SIGNATURE headere saltando gli hook dell’SDK; tuttavia, è comunque consigliato scegliere primacreateX402PaymentHandler, per evitare di dover gestire autonomamente gli aggiornamenti del protocollo.
Utilizzo 3: Solana
exact, quindi preferScheme non ha effetto su Solana.
III. Python: modalità chiave privata
acedatacloud-x402 per Python segue il percorso di firma diretta con la chiave privata (senza astrazione EIP-1193), ed è più adatto a server / esecutori di attività.
Installazione
EVM (Base)
Solana
Approve una tantum (solo la prima volta su EVM)
Su EVM Base, X402 usa Permit2 e richiede che il wallet esegua una volta un approveMaxUint256 dell’USDC verso il contratto Permit2. acedatacloud-x402 include approve_permit2:
IV. Verifica dell’esecuzione reale
Obiettivo del test: l’SDK TS non riceve un token, viene iniettato un handler X402 e riesce a costruire e avviare normalmente le richieste (una verifica leggera che non consuma vero USDC on-chain).- Non viene passato
apiTokene la costruzione dell’SDK non genera errori, dimostrando che la modalità X402 è effettivamente un’alternativa valida al token. createX402PaymentHandlerrestituisce una funzione (hook), che l’SDK invocherà solo dopo aver ricevuto un 402.- Il test end-to-end del pagamento effettivo on-chain, poiché comporta un reale addebito di USDC, non è incluso in questo tutorial; puoi fare riferimento all’esempio e2e nella guida all’integrazione X402.
Anchecreate_x402_payment_handlerlato Python ha effettuato la stessa verifica: il valore restituito dalla funzione è callable e la costruzione diAceDataCloud(...)non genera errori quando viene iniettatopayment_handler=.... La semantica è allineata su entrambi i lati.
V. Confronto con la «modalità Bearer token»
VI. Insidie comuni
- Le classi chat devono usare
preferScheme=upto: usareexactfarà sì che il facilitator addebiti USDC in base amaxAmountRequired(non al consumo effettivo). - Sul lato Node non passare una chiave privata nuda a
createX402PaymentHandler: il pacchetto TS non accetta{ privateKey }, deve essere incapsulata in un provider EIP-1193 (si raccomanda viemWalletClient). - La prima chiamata richiede una doppia firma: la prima firma l’approve Permit2 (on-chain, con gas), la seconda firma l’envelope X402 (non on-chain). Nelle chiamate successive rimane solo la seconda.
- Solana non ha il concetto di Permit2: firma direttamente l’autorizzazione di trasferimento del token SPL, senza bisogno di approve; ma attualmente sulla chain Solana è supportato solo
exact. - Distinguere gli errori di business dagli errori di pagamento: 402 → il fallimento dell’handler genera
X402SignError(il tipo specifico varia in base alla chain); gli errori dell’interfaccia business dopo il reinvio (401 / 422 / 5xx) vengono comunque classificati come normali eccezioni SDK. - Il modo più stabile per adattare
viem:evmProvider: walletClient as anyperde il controllo dei tipi ma offre la migliore compatibilità; se si desidera mantenere i tipi, usare.transport.requestdi viem per incapsularlo separatamente in un oggetto{ request }e passarlo.

