Come inviare token ERC-20: metodi tramite wallet, codice e API

È possibile inviare token ERC-20 in tre modi: da un’app wallet, dal proprio codice con una libreria come ethers.js, oppure tramite un’API REST che firma e trasmette per conto dell’utente. Tutti e tre i metodi fanno la stessa cosa a livello sottostante: chiamano la funzione transfer sullo smart contract del token, e il mittente paga la commissione di rete in ETH, non nel token. Questa guida illustra ciascun metodo, gli errori che causano la perdita di fondi e cosa cambia quando si passa da un trasferimento manuale a migliaia di trasferimenti automatizzati.

TL;DR

• Un trasferimento ERC-20 è una chiamata al contratto del token, non un semplice trasferimento di valore come ETH. L’indirizzo del destinatario e l’importo vanno nei dati della chiamata.
• Il wallet mittente ha bisogno di ETH per il gas anche se detiene molti token. Con zero ETH la transazione fallisce.
• Non transfer mai i token direttamente in un contratto che non ha codice per gestirli. Usare approve e transferFrom per le interazioni con i contratti.
• Nel codice, gestire i decimali del token e i token che non restituiscono un booleano standard. Avvolgere le chiamate con una libreria sicura.
• Se si crea un’app che invia token per gli utenti, un’API REST elimina il lavoro su nodo, nonce e gas. Ne parliamo di seguito.

Indice

• Cosa succede effettivamente quando si invia un token ERC-20
• Prima di inviare: una breve checklist
• Metodo 1: Inviare da un wallet
• Metodo 2: Inviare con codice (ethers.js)
• Metodo 3: Inviare tramite un’API REST
• Errori comuni nei trasferimenti ERC-20
• Trasferimenti senza gas e meta-transazioni
• La nostra prospettiva: trattare un trasferimento come un flusso di lavoro, non una chiamata
• Automatizzare i trasferimenti con Chaingateway
• Confermare che il trasferimento ha funzionato
• FAQ
• Fonti

Cosa succede effettivamente quando si invia un token ERC-20

L’invio di ETH sposta valore nativo tra due account. L’invio di un token ERC-20 modifica un registro dei saldi memorizzato all’interno del contratto del token. Il wallet crea una transazione indirizzata al contratto del token, e quel contratto aggiorna i saldi di mittente e destinatario.

Lo standard ERC-20 definisce i metodi che ogni token conforme espone: totalSupply, balanceOf, transfer, transferFrom, approve e allowance. Quell’interfaccia condivisa è il motivo per cui un wallet o un pezzo di codice può gestire migliaia di token diversi. La specifica originale è EIP-20, pubblicata nel novembre 2015.

Da questo design derivano alcune conseguenze:

• Il campo to della transazione è il contratto del token, non la persona che sta pagando. Il vero destinatario è codificato nei dati della chiamata.
• I dati della chiamata iniziano con il selettore di funzione 0xa9059cbb (la firma di transfer), seguiti dall’indirizzo del destinatario e dall’importo, secondo la documentazione ERC-20 di ethereum.org.
• ERC-20 è uno standard per token, non la stessa cosa di Ethereum. ETH è la valuta nativa della rete. Token come USDT sono contratti in esecuzione su di essa. Se desidera una panoramica più ampia su gas ed ETH, consulti la nostra panoramica su Ethereum.

Lo stesso formato esiste anche su altre catene EVM. Il nostro post sullo standard token ERC20 approfondisce il suo funzionamento, e la guida agli indirizzi ERC20 spiega il formato degli indirizzi e la consultazione dei saldi.

Prima di inviare: una breve lista di controllo

La maggior parte dei trasferimenti persi deriva da una preparazione omessa, non da guasti tecnici. Verifichi prima questi punti.

1. Possiede il token e l’importo corretto. Confermi il saldo con balanceOf o nel suo wallet.
2. Possiede ETH per il gas. La commissione è pagata nella valuta nativa della rete, non detratta dai token che invia. Su Polygon o BNB Chain si applica la stessa logica con la moneta nativa di quella catena. Un wallet con token ma senza ETH non può inviare nulla.
3. Possiede l’indirizzo esatto del destinatario. Lo copi e incolli piuttosto che digitarlo. Il centro assistenza di MetaMask avverte sull’avvelenamento degli indirizzi, dove un aggressore insinua nella sua cronologia un indirizzo simile.
4. Conosce la rete. Lo stesso formato di indirizzo funziona su diverse catene EVM. Un token inviato sulla rete sbagliata non arriva dove il destinatario se lo aspetta.
5. Il destinatario può accettarlo. Inviare a un indirizzo di deposito di un exchange sulla rete sbagliata, o a un contratto che non gestisce token, può significare perdita permanente.
6. Esegue prima un test con un piccolo importo. Per un nuovo destinatario o una nuova integrazione, invii un piccolo importo e confermi che sia arrivato prima di inviare l’intera somma.

Metodo 1: Invio da un wallet

Per trasferimenti occasionali, un wallet è la via più semplice. La guida di Etherscan all’invio di ETH o token descrive lo stesso flusso seguito dalla maggior parte dei wallet:

1. Apra il wallet e scelga l’opzione di invio.
2. Selezioni il token che desidera inviare. Se il wallet non lo elenca, lo aggiunga incollando l’indirizzo del contratto del token.
3. Incolli l’indirizzo del destinatario.
4. Inserisca l’importo.
5. Controlli la commissione di rete. Il wallet la stima per lei.
6. Confermi, quindi tracci l’hash della transazione su un block explorer finché non viene confermata.

Due dettagli creano spesso problemi. Primo, l’indirizzo del contratto del token che incolla quando aggiunge un token personalizzato deve essere quello reale, perché token falsi usano lo stesso nome e simbolo. Lo verifichi dal sito ufficiale del progetto. Secondo, la commissione mostrata è in ETH, quindi il saldo ETH del wallet deve coprirla oltre a qualsiasi ETH intenda inviare.

Metodo 2: Invio con codice (ethers.js)

Gli sviluppatori che devono automatizzare i trasferimenti possono chiamare il contratto direttamente. Il tutorial di ethereum.org sull’invio di token con ethers.js mostra lo schema di base. Una guida separata su ethers.js spiega la differenza fondamentale rispetto a ETH: la transazione non invia valore, ma chiama la funzione transfer del token con una destinazione e un importo.

I passaggi sono i seguenti:

1. Creare un provider connesso a un nodo Ethereum (proprio o un endpoint ospitato).
2. Creare un signer da una chiave privata o da un wallet che si controlla.
3. Istanziare il contratto del token con il suo indirizzo e un ABI minimo contenente transfer, balanceOf e decimals.
4. Convertire l’importo umano in unità base utilizzando i decimali del token.
5. Chiamare transfer(destinatario, importo) e attendere la ricevuta.

Quel tutorial su ethers.js nota che la libreria può inviare una transazione EIP-1559 senza impostazioni manuali del gas, scegliendo un limite di gas e una commissione di priorità predefinita. Può anche gestire il nonce quando si usa un signer.

Gestire correttamente i decimali

I token memorizzano gli importi come interi. Un token con 18 decimali rappresenta 1,0 token come 1000000000000000000 unità base. Il campo decimals fa parte dello standard ma token diversi impostano valori diversi, e il testo dell’EIP-20 lo tratta come metadato opzionale. Leggere sempre decimals dal contratto invece di assumere 18. Codificare rigidamente il valore sbagliato invia un importo errato di ordini di grandezza.

Non fidarsi ciecamente del valore di ritorno

Lo standard dice che transfer restituisce un booleano. Non tutti i token in circolazione si comportano in quel modo. Alcuni non restituiscono nulla, e alcuni falliscono in modi inaspettati. L’interfaccia IERC20 di OpenZeppelin è il riferimento per lo standard, e la libreria SafeERC20 di OpenZeppelin esiste per avvolgere le chiamate in modo che token anomali non interrompano la logica. Se il Suo smart contract sposta token, la utilizzi. Se il Suo backend invia token, controlli lo stato della ricevuta della transazione e l’evento Transfer emesso invece di assumere il successo.

Limiti di gas

Un trasferimento semplice di ETH usa un limite di gas di 21.000, secondo la guida di MetaMask. Un trasferimento di token è una chiamata a contratto, quindi ne serve di più. Stimare il gas con la chiamata di stima della Sua libreria prima di ogni invio invece di codificare rigidamente un numero, perché il costo dipende dal codice del contratto del token e dallo stato dei saldi coinvolti.

Metodo 3: Inviare tramite API REST

Eseguire il percorso di codice sopra descritto va bene per uno script. In un prodotto diventa una lista di incombenze: gestire o noleggiare l’accesso ai nodi, gestire le chiavi, tracciare i nonce in modo che invii simultanei non collidano, stimare il gas, ritentare transazioni bloccate, decodificare i log per scoprire se un pagamento è arrivato, e ripetere tutto per ogni catena.

Un’API unificata toglie quel livello al Suo team. Con Chaingateway Lei crea wallet, invia token e legge dati di transazione decodificati tramite semplici chiamate REST. Non ha bisogno di web3.js o ethers.js nel Suo stack, e non gestisce nodi. La nostra pagina API Ethereum mostra come funziona l’invio di ERC-20 tramite REST. Le richieste sono firmate con HMAC, e il gas è stimato automaticamente.

Lo stesso approccio si estende a Bitcoin, Tron, Solana, Polyggon, BNB Chain e Arbitrum, quindi una seconda catena non significa una seconda integrazione. Se in seguito aggiunge USDT su Tron, legga la nostra spiegazione su TRC10 vs TRC20. Per gli indirizzi BNB Chain, consulti la guida agli indirizzi BEP20.

Quando ogni metodo è adatto

Situazione	Portafoglio	Codice proprio	REST API
Trasferimento personale occasionale	Migliore	Eccessivo	Eccessivo
Script occasionale su una catena	Lento	Buono	Buono
Pagamenti o prelievi all’interno di un’app	Non pratico	Possibile, lo mantiene lei	Migliore soluzione
Diverse catene e standard di token	Manuale per catena	Un client per catena	Un’interfaccia
Rilevamento pagamenti in entrata	Manuale	Costruisce listener di log	Webhook

Modi comuni in cui i trasferimenti ERC-20 vanno male

Invio di token a un contratto

La funzione transfer non è stata progettata per depositare in smart contract. Se un contratto non ha logica per reagire ai token in arrivo, questi rimangono nel suo saldo senza possibilità di uscita. La pagina ERC-20 di ethereum.org descrive questo rischio, inclusi i token inviati allo stesso contratto del token, e riporta milioni di dollari persi in questo modo a giugno 2024. Se scrive contratti, aggiunga una funzione che le permetta di recuperare i token inviati per errore. Se ha bisogno che un contratto riceva token da un utente, lo schema standard è: l’utente chiama approve per il contratto, poi il contratto chiama transferFrom.

Zero ETH per il gas

La transazione fallisce se il mittente non ha valuta nativa, per quanti token ci siano nel portafoglio. I team di prodotto spesso scoprono questo tardi: un utente riceve token, prova a spostarli e non ci riesce. Le opzioni sono ricaricare il portafoglio con una piccola quantità di ETH, o progettare attorno al problema con autorizzazioni firmate.

Rete sbagliata o indirizzo sbagliato

Le blockchain non annullano le transazioni. Verifichi la rete e l’indirizzo prima di confermare, e usi un piccolo trasferimento di prova per qualsiasi novità.

Confondere il token con la rete

USDT, per esempio, esiste su diverse catene. Quando qualcuno dice di avere USDT, chieda su quale rete. L’indirizzo può sembrare identico su ognuna, ma i fondi vivono su una sola catena.

Trasferimenti senza gas e meta-transazioni

Un’opzione in crescita per l’onboarding è far firmare un messaggio all’utente e far inviare la transazione e pagare il gas a qualcun altro. EIP-3009, Transfer With Authorization, definisce funzioni che permettono a un detentore di delegare il pagamento del gas e far eseguire i trasferimenti tramite firme EIP-712. Solo i token i cui contratti lo implementano supportano questo, quindi controlli prima di progettare un flusso attorno a esso. Per una startup, può rimuovere l’ostacolo del primo trasferimento legato all’acquisizione di ETH.

La nostra prospettiva: tratti un trasferimento come un flusso di lavoro, non come una chiamata

Osserviamo lo stesso schema nei team che integrano l’invio di token per la prima volta. La chiamata transfer in sé richiede un pomeriggio. Le settimane vanno in tutto ciò che sta intorno: sapere quando un pagamento è arrivato davvero, gestire una transazione fallita o bloccata, stimare le commissioni e mantenere le chiavi al sicuro.

La nostra visione è che invio e ricezione appartengano insieme. Un flusso di payout senza eventi di conferma la costringe a fare polling, e un flusso di deposito senza dati decodificati la costringe a parsare log grezzi. È per questo che abbiamo creato la creazione di wallet, i trasferimenti di token, la stima del gas, i dati di transazione decodificati e le notifiche webhook dietro un’unica API, firmata con HMAC. Lei ottiene un solo contratto con la sua infrastruttura invece di uno per catena, e non deve eseguire nodi.

Il nostro consiglio pratico: inizi con un piccolo trasferimento su una configurazione di test, verifichi decimali e ricevute, si iscriva agli eventi per la conferma, e solo allora aumenti i volumi.

— Bitblade

Automazione dei trasferimenti con Chaingateway

Se sta costruendo payout, prelievi o depositi in un’app, può provare la nostra Blockchain API e abbinarla ai Chaingateway Webhooks per essere notificato quando arrivano i pagamenti. I piani nella nostra pagina prezzi partono da 49 EUR al mese per Plus, con Pro a 99 EUR al mese, Premium a 249 EUR al mese ed Enterprise a 499 EUR al mese. La fatturazione annuale è 490 EUR per Plus, 990 EUR per Pro, 2490 EUR per Premium e 4990 EUR per Enterprise. L’accesso a pagamento segue una prova gratuita.

Confermare che il trasferimento ha funzionato

Inviare una transazione non è la stessa cosa che completare un pagamento. Dopo aver inviato:

1. Memorizzi immediatamente l’hash della transazione.
2. Controlli lo stato della ricevuta. Una transazione minata può comunque essere fallita.
3. Cerchi l’evento Transfer dal contratto del token con mittente, destinatario e importo attesi. L’evento fa parte dell’interfaccia ERC-20.
4. Aspetti tante conferme quante la sua policy di rischio richiede prima di rilasciare beni o accreditare un saldo.
5. Riconcili periodicamente con balanceOf per intercettare qualsiasi cosa il suo listener abbia perso.

Il polling funziona per uno script piccolo. Per la produzione, iscriversi alle notifiche significa che il suo sistema reagisce agli eventi invece di chiedere ripetutamente.

Fonti

• Standard Token ERC-20, ethereum.org
• EIP-20: Standard Token ERC-20
• Come inviare token dal wallet MetaMask, Centro Assistenza MetaMask
• Come inviare ETH o token, Centro Informazioni Etherscan
• Invio token con ethers.js, ethereum.org
• Ethers.js: Come inviare token ERC-20, Centro Assistenza MetaMask
• IERC20.sol, Contratti OpenZeppelin
• ERC-3009: Trasferimento con Autorizzazione

Consigliati

• API Ethereum – Invia token ERC-20 via REST, Senza web3.js
• Lo Standard Token ERC20