Ethereum API: trasferimenti ERC-20 con una sola chiamata REST

JSON-RPC è il protocollo nativo di ogni nodo Ethereum, e per alcuni compiti (strumenti di consenso, indicizzazione personalizzata) vuoi quel livello di accesso. La nostra guida su interagire con i nodi via JSON-RPC mostra come appare in PHP, Python e JavaScript.

Contare i round trip chiarisce il punto. Un trasferimento di token via JSON-RPC grezzo tocca almeno quattro metodi — eth_gasPrice, eth_estimateGas, eth_getTransactionCount e eth_sendRawTransaction — con codifica ABI e firma della transazione nel mezzo.

Per i pagamenti, l'astrazione ripaga. Nella richiesta di transazione di Chaingateway, gas limit, gas price e nonce sono campi opzionali — omettili e l'API li compila quando costruisce e trasmette la transazione; passali esplicitamente quando vuoi il controllo. La tua parte dello scambio è un'unica richiesta HTTP che puoi scrivere in qualsiasi linguaggio con una libreria standard.

Se oggi mantieni un'integrazione web3.js, ecco il confronto onesto. Un trasferimento ERC-20 tramite la libreria appare più o meno così:

// web3.js against your own RPC endpoint
const { Web3 } = require("web3");
const web3 = new Web3("https://your-rpc-endpoint");

const token = new web3.eth.Contract(ERC20_ABI, "0xdAC17F958D2ee523a2206206994597C13D831ec7");
const data = token.methods.transfer(recipient, amountInBaseUnits).encodeABI();

const tx = {
  from: sender,
  to: token.options.address,
  data,
  gas: await web3.eth.estimateGas({ from: sender, to: token.options.address, data }),
  gasPrice: await web3.eth.getGasPrice(),
  nonce: await web3.eth.getTransactionCount(sender),
};

const signed = await web3.eth.accounts.signTransaction(tx, PRIVATE_KEY);
await web3.eth.sendSignedTransaction(signed.rawTransaction);

Oltre a ciò che sta nell'estratto, questo codice possiede un file ABI, converte a mano gli importi leggibili in unità base (sbagli i decimali e invii un milionesimo della somma prevista, oppure un milione di volte tanto), e mantiene una private key grezza nella memoria dell'applicazione. La versione REST è l'unica POST sopra: importo come stringa decimale, decimali gestiti lato server, key cifrata a riposo dietro una password.

La migrazione non richiede un weekend di riscrittura. Entrambi gli stili sono semplici chiamate, quindi eseguili fianco a fianco: instrada i nuovi flussi di pagamento via REST, lascia le interazioni con contratti personalizzati su web3.js, e ritira la libreria dove non guadagna più la sua complessità. I team che usavano web3.js solo per trasferimenti e controlli di saldo tendono a rimuovere del tutto la dipendenza.

Ogni transazione Ethereum brucia gas, pagato in ETH dall'indirizzo mittente, mai dal destinatario. Un wallet che detiene migliaia di USDT ma zero ETH non può inviare un solo token, perché il contratto ERC-20 non ha modo di coprire il proprio costo di esecuzione. Ricevere token non costa nulla al destinatario.

Questo dettaglio inganna più integrazioni ERC-20 di qualsiasi altro. Se i tuoi trasferimenti guidati dall'API provengono da un wallet di tesoreria, quel wallet ha bisogno di un saldo ETH accanto ai suoi token, e ricaricarlo appartiene alla checklist operativa insieme al rinnovo dei certificati.

Quanto costa il gas

Un semplice trasferimento ETH costa esattamente 21.000 di gas — una costante di protocollo. Un trasferimento ERC-20 esegue codice contrattuale e costa un multiplo di quello, con la cifra esatta che varia per contratto token. Il prezzo per unità fluttua con la domanda: dall'upgrade London del 2021, la commissione si divide in una base fee che la rete brucia e una mancia di priorità al proposer del blocco, ed entrambe salgono sotto congestione. La conseguenza pratica: lo stesso trasferimento USDT costa centesimi in una domenica tranquilla e considerevolmente di più durante un mint popolare.

Cosa gestisce l'API per te

Gas limit, gas price e i tetti EIP-1559 (maxFeePerGas, maxPriorityFeePerGas) sono campi opzionali della richiesta — omettili e l'API li compila quando costruisce la tua transazione, oppure fissali per richiesta quando vuoi il controllo. Due cose restano di tua responsabilità: mantenere ETH sui wallet mittenti, e decidere dove i piccoli trasferimenti abbiano senso economico — quando le commissioni mainnet si avvicinano all'importo del trasferimento, la stessa chiamata su Polygon o Arbitrum è a un cambio di percorso di distanza.

Ricevere è gratis

Un indirizzo di deposito non ha bisogno di ETH per accettare token. Il gas diventa un tuo problema solo quando i fondi escono — incluso quando consolidi i depositi dei clienti in un wallet di tesoreria, che è essa stessa una transazione in uscita da ogni indirizzo di deposito.

Dal passaggio al proof of stake, la cadenza di Ethereum è fissa anziché statistica. I blocchi arrivano in slot da dodici secondi, 32 slot formano un'epoca di 6,4 minuti, e un blocco viene finalizzato dopo circa due epoche — chiamiamola 13 minuti — una volta che due terzi dell'ETH in staking lo ha attestato (parametri di protocollo a metà 2026). Finalizzato significa che la rete non può revertire il blocco senza distruggere una grande quota di tutto l'ETH in staking, il che lo colloca in una categoria diversa dalla liquidazione probabilistica di Bitcoin.

Per la logica di pagamento la timeline si legge così: un trasferimento è tipicamente incluso in un blocco entro secondi o un minuto; ogni slot successivo aggiunge sicurezza; dopo circa 13 minuti è finale in senso stretto. La maggior parte delle applicazioni accredita i depositi ben prima della finalità — l'inclusione più una manciata di blocchi copre gli importi quotidiani — mentre gli exchange generalmente trattengono i grandi prelievi fino alla finalizzazione. Il webhook di deposito ti dà l'evento on-chain; dove fissi la soglia di accredito è una linea di policy nella tua configurazione, non nella nostra.

USDT, USDC, DAI e gli altri token consolidati funzionano immediatamente, con importi in unità di token anziché unità base grezze. Stai lanciando un tuo ERC-20? Fornisci il contract address e lo stesso endpoint lo invia. Nessun processo di listing, nessuna attesa. Il contesto sullo standard stesso è nella nostra guida allo standard ERC-20 token.

• È la piattaforma di smart contract più adottata, testata sul campo dal 2015.
• L'ecosistema DeFi è il più grande di qualsiasi chain, con migliaia di dApp con cui integrarsi.
• Il pricing del gas è dinamico, basato sulla domanda di rete; puoi lasciare i campi commissione all'API oppure limitarli per richiesta con i parametri EIP-1559.
• Il lavoro di scaling continua, e Polygon e Arbitrum sono disponibili tramite la stessa API quando le commissioni mainnet mordono.

Il pattern di rotta ERC-20 si ripete sulle reti EVM: /api/v2/polygon/transactions/erc20, /api/v2/arbitrum/transactions/erc20, e /api/v2/bsc/transactions/bep20 per BNB Smart Chain. Il codice scritto per Ethereum si trasferisce modificando il percorso. Quando il gas mainnet diventa troppo costoso per i piccoli trasferimenti, spostarli su Polygon è una modifica di una riga. L'elenco completo delle chain è nella panoramica della blockchain API.

I blocchi costruttivi sopra coprono la maggior parte dei pattern di produzione che vediamo: flussi di checkout che accettano USDT o USDC, exchange che accreditano depositi ed elaborano prelievi su scala, progetti token che distribuiscono tramite airdrop o piani di vesting, e attività in abbonamento che fatturano in stablecoin ogni mese. Tutti si riducono alle stesse due chiamate: inviare una transazione, ricevere un webhook.

Checkout in stablecoin per un negozio online

Il cliente sceglie "paga con USDT" e il tuo backend assegna un indirizzo di deposito per l'ordine — un indirizzo per fattura, così l'attribuzione non dipende mai dall'abbinare gli importi. Mostra l'indirizzo con l'importo, poi attendi il webhook. Quando arriva la notifica, cambia l'ordine in "pagamento rilevato" così l'acquirente vede una reazione rapida; accreditalo una volta che la transazione ha la profondità richiesta dalla tua policy (la sezione sulla finalità sopra ti dà i numeri). Un caso limite appartiene al codice fin dal primo giorno: i wallet che sottraggono le commissioni dall'importo inserito producono leggeri sottopagamenti, e la tua tolleranza per questi dovrebbe essere un valore di configurazione, non un ticket di supporto.

Prelievi per una piattaforma di trading

Gli utenti richiedono payout; il tuo compito è inviare molti trasferimenti ERC-20 in modo affidabile. Metti in coda ogni prelievo nel tuo database con una colonna di stato, poi lavora la coda con POST /api/v2/ethereum/transactions/erc20 — una richiesta per payout, registrando la risposta prima di passare alla successiva. La regola che tiene contenti gli auditor: una chiamata HTTP andata in timeout non è una transazione fallita. Verifica contro i tuoi record e GET /api/v2/ethereum/transactions, che elenca ogni transazione creata tramite l'API, prima di reinviare qualsiasi cosa, o pagherai qualcuno due volte. Monitora anche il saldo ETH del wallet di tesoreria, dato che ogni trasferimento in uscita brucia gas, e allertati ben prima che si esaurisca invece che quando la coda si blocca.

Qui esistono due livelli di errore: errori HTTP dell'API, e condizioni on-chain che la tua logica deve assorbire.

Il lato HTTP segue la convenzione. Un 401 significa che la key manca o non è valida — un problema di configurazione, non un candidato al retry. Altre risposte 4xx dicono che la richiesta stessa è sbagliata: un indirizzo malformato, un contratto sconosciuto, un campo mancante. Registra il corpo della risposta e correggi il chiamante. I retry con backoff appartengono solo alle risposte 5xx e ai timeout di rete.

Il lato chain è dove il codice dei pagamenti si guadagna lo stipendio. Un trasferimento da un wallet senza abbastanza ETH per il gas fallisce anche se il saldo di token è ampio — monitora i saldi gas in modo proattivo invece di scoprirli vuoti in un messaggio di errore. La congestione può ritardare l'inclusione; quello è un ritardo, non un fallimento, e la tua UI dovrebbe distinguere i due. E la regola dal percorso di prelievo merita di essere ripetuta, perché protegge dall'errore più costoso in questo dominio: non reinviare mai un trasferimento solo perché la risposta HTTP non è mai arrivata. Conferma prima che davvero non sia avvenuto.

Per i depositi, costruisci un'abitudine di riconciliazione. GET /api/v2/ethereum/webhooks/notifications elenca ciò che è stato consegnato; un confronto notturno con il tuo libro contabile individua qualsiasi cosa un bug o un'interruzione abbia inghiottito, mentre il fix è ancora economico.

Aggiungi X-Network: testnet a qualsiasi richiesta e viene eseguita sulla rete di test. Rotte, corpi di richiesta e formati di risposta restano identici a mainnet, il che significa che i tuoi test di integrazione esercitano il vero percorso di codice invece che dei mock. Finanzia un wallet di test da un faucet pubblico, esegui trasferimenti, ricevi webhook — l'intero ciclo non costa nulla.

Strutturalo così che l'header provenga dalla configurazione: staging lo imposta, produzione no, e non esiste alcuna differenza di codice tra i due. Dai anche a staging un callback URL separato, altrimenti i depositi di test finiranno nel tuo handler webhook di produzione. Andare in produzione è quindi la rimozione di un header, deliberatamente anticlimatico.