Vai al contenuto principale
X402 è un protocollo di pagamento on-chain “fatturato tramite HTTP 402” proposto da Coinbase: il server restituisce 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 il 402 Payment Required e accepts restituiti 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.
Sia @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à Python EVMAccountSigner
  • 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:
L’envelope X402 è un JSON, codificato in base64 e inserito nell’header PAYMENT-SIGNATURE. Struttura (estratto):
Il livello superiore dell’envelope è 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

Versioni testate:

Firma completa di createX402PaymentHandler

Il valore restituito è un (ctx) => Promise&lt;{ headers: Record<string, string> }> che corrisponde esattamente alla firma dell’hook paymentHandler dello SDK.

Utilizzo 1: browser (MetaMask / WalletConnect)

Alla prima chiamata il browser mostrerà due richieste di firma: la prima è un approve una tantum di Permit2 per USDC (l’importo è 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 livello signEVMUptoPayment, concatenando autonomamente il percorso accepts → signed envelope → PAYMENT-SIGNATURE header e saltando gli hook dell’SDK; tuttavia, è comunque consigliato scegliere prima createX402PaymentHandler, per evitare di dover gestire autonomamente gli aggiornamenti del protocollo.

Utilizzo 3: Solana

Sulla chain Solana al momento viene esposto solo lo scheme 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

Versioni testate:

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 approve MaxUint256 dell’USDC verso il contratto Permit2. acedatacloud-x402 include approve_permit2:
Questa transazione deve essere inviata una sola volta; in seguito, tutti i pagamenti X402 EVM useranno questa autorizzazione. Solana non ne ha bisogno.

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).
Output:
Il risultato indica:
  • Non viene passato apiToken e la costruzione dell’SDK non genera errori, dimostrando che la modalità X402 è effettivamente un’alternativa valida al token.
  • createX402PaymentHandler restituisce 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.
Anche create_x402_payment_handler lato Python ha effettuato la stessa verifica: il valore restituito dalla funzione è callable e la costruzione di AceDataCloud(...) non genera errori quando viene iniettato payment_handler=.... La semantica è allineata su entrambi i lati.

V. Confronto con la «modalità Bearer token»

VI. Insidie comuni

  1. Le classi chat devono usare preferScheme=upto: usare exact farà sì che il facilitator addebiti USDC in base a maxAmountRequired (non al consumo effettivo).
  2. 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 viem WalletClient).
  3. 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.
  4. 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.
  5. 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.
  6. Il modo più stabile per adattare viem: evmProvider: walletClient as any perde il controllo dei tipi ma offre la migliore compatibilità; se si desidera mantenere i tipi, usare .transport.request di viem per incapsularlo separatamente in un oggetto { request } e passarlo.

Scopri di più