API per indirizzi TRC20: genera indirizzi e controlla i depositi
Un indirizzo TRC20 è un normale indirizzo di account TRON: 34 caratteri in forma Base58Check, che inizia con T. Contiene TRX e ogni token TRC-20 come USDT. Lo stesso indirizzo ha una forma esadecimale di 42 caratteri che inizia con 41. Inviare da esso costa Energy e Bandwidth, mentre ricevere è gratis.
Per generare un indirizzo TRC20 via API si chiama POST /api/v2/tron/addresses. La risposta è un indirizzo Base58Check che inizia con T. Un webhook registrato con POST /api/v2/tron/webhooks segnala poi ogni deposito USDT-TRC20 su quell'indirizzo. La pagina spiega prima il formato, poi creazione, monitoraggio e invio, con endpoint e corpi delle richieste.
Tutto gira su https://app.chaingateway.io, con un Bearer token nell'header Authorization. Aggiungendo X-Network: testnet a una chiamata la si sposta sulla testnet di TRON, così l'intero flusso si prova con TRX di test gratuiti. Per una spiegazione più lunga del formato vedi Che cos'è un indirizzo TRC20? sul blog.
Che aspetto ha un indirizzo TRC20?
Un indirizzo TRC20 è l'indirizzo di un account TRON nella forma Base58Check, per esempio TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL. Ha 34 caratteri e inizia con T. La documentazione sugli account di TRON definisce il valore sottostante come 21 byte: un byte di prefisso 0x41, poi 20 byte uguali all'indirizzo Ethereum derivato dalla stessa chiave pubblica.
Lo stesso indirizzo ha quindi una forma esadecimale di 42 caratteri che inizia con 41. Le API dei nodi restituiscono spesso quella forma, mentre wallet ed explorer mostrano la Base58Check. TronWeb converte tra le due con tronWeb.address.toHex() e fromHex().
«TRC20» indica lo standard del token, non l'indirizzo. TRC-20 è lo standard TRON per i token fungibili ed è compatibile con l'ERC-20 di Ethereum a livello di interfaccia. Un indirizzo TRON contiene TRX e ogni token TRC-20.
- La forma Base58Check mostrata in wallet ed explorer: 34 caratteri, inizia con T.
- Il byte di prefisso 41 indica che il valore è un indirizzo TRON.
- I restanti 20 byte sono identici all'indirizzo Ethereum derivato dalla stessa chiave pubblica.
- La forma esadecimale: 42 caratteri in totale, come la restituiscono molte API dei nodi.
Un indirizzo TRC20 è uguale all'indirizzo di un contratto TRC20?
No. L'indirizzo di un wallet è un account controllato da una chiave privata. L'indirizzo di un contratto appartiene a codice distribuito e nessuno ne possiede la chiave. La documentazione di TRON elenca entrambi come tipi di account ed entrambi si scrivono come stringhe T, quindi nulla nella stringa li distingue.
L'indirizzo del contratto identifica quale token si muove e non è mai la destinazione di un trasferimento. Il contratto TRC-20 di USDT è TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t, e i token inviati a un indirizzo di contratto sono quasi sempre irrecuperabili. La guida sul blog spiega la differenza in dettaglio.
Perché un nuovo indirizzo TRC20 non compare su Tronscan?
Perché TRON riconosce un account solo dopo l'attivazione. Secondo la documentazione degli account di TRON, una coppia di chiavi appena generata esiste in locale, ma l'indirizzo non si può cercare tramite API o block explorer finché non è attivato.
L'attivazione avviene quando un account esistente invia al nuovo indirizzo un importo qualsiasi di TRX o di un token TRC-10 e il mittente paga una commissione di creazione dell'account. La documentazione indica quella commissione in 1 TRX su mainnet al momento della redazione, quindi controlla il valore attuale prima di impostare su di essa un flusso di pagamento. Un indirizzo generato va bene per depositi e webhook, ma non aspettarti che un explorer lo mostri prima della prima attivazione.
Endpoint per indirizzi TRC20: crea, leggi, monitora, invia
Quattro compiti e le route che li svolgono. La creazione dell'indirizzo e la registrazione del webhook non richiedono alcuna chiave privata, serve solo per inviare.
| Endpoint | Cosa fa |
|---|---|
POST /api/v2/tron/addresses | Genera un nuovo indirizzo TRON |
POST /api/v2/tron/addresses/import | Importa una chiave privata esistente, così l'API può firmare per quell'indirizzo |
POST /api/v2/tron/addresses/{address} | Cambia la password che cifra una chiave salvata |
DELETE /api/v2/tron/addresses/{address} | Rimuove un indirizzo dal tuo account |
GET /api/v2/tron/balances/{address} | Saldo TRX dell'indirizzo |
GET /api/v2/tron/balances/{address}/trc20/{contract_address} | Saldo di un singolo token TRC-20, USDT incluso |
GET /api/v2/tron/balances/{address}/trc10/{token_id} | Saldo di un token TRC-10 |
POST /api/v2/tron/webhooks | Sottoscrive i trasferimenti TRX, TRC-10, TRC-20 o TRC-721 dell'indirizzo |
GET /api/v2/tron/webhooks/notifications | Elenca le notifiche già consegnate, per la riconciliazione |
POST /api/v2/tron/transactions/trc20 | Invia dall'indirizzo un token TRC-20 come USDT |
Questa è tutta la superficie che un sistema di depositi tocca. Il riferimento completo di TRON, con tutte le 40 operazioni inclusi staking e auto-firma, è nella pagina TRON API. Il campo type del webhook e la route separata /transactions/trc10 esistono perché TRON ha due standard di token. Il confronto TRC10 e TRC20 spiega su quale emettere se lanci un token invece di accettarne uno esistente.
Come genero un indirizzo TRC20 via REST?
POST /api/v2/tron/addresses ne crea uno. Il corpo accetta un solo campo opzionale, password, che decide il modello di custodia. Se invii una password, la chiave privata viene salvata cifrata con essa e i trasferimenti successivi si autenticano con la password invece che con la chiave. Se la ometti, la risposta ti consegna direttamente la chiave privata, da conservare nel tuo vault. Il riferimento è esplicito: le password non vengono salvate. Se la perdi, il wallet non si può ripristinare, e vale anche al contrario: nessun altro può sbloccarlo.
curl -X POST https://app.chaingateway.io/api/v2/tron/addresses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"password": "a-strong-password-per-wallet"}'
Se la tua piattaforma genera già le chiavi da sé, conviene la seconda route: POST /api/v2/tron/addresses/import registra un indirizzo derivato altrove, insieme alla sua chiave privata e a una password di cifratura, e da quel momento l'API può firmare per esso. Gli indirizzi che vuoi solo osservare non richiedono nessuna delle due chiamate, perché una sottoscrizione webhook fa riferimento all'indirizzo tramite la stringa.
Due route di gestione appartengono allo stesso gruppo. POST /api/v2/tron/addresses/{address} cambia la password di cifratura di una chiave salvata. DELETE /api/v2/tron/addresses/{address} rimuove l'indirizzo dal tuo account e, come nota il riferimento, riduce anche il conteggio degli indirizzi usati. Vale la pena inserirla nel job che ritira gli indirizzi di deposito scaduti, se sei vicino al limite del piano.
Come controllo un indirizzo TRC20 per gli USDT in arrivo?
Fare polling su Tronscan per i depositi è la versione che si rompe in silenzio. POST /api/v2/tron/webhooks è la versione che scala. url è l'unico campo che il riferimento indica come obbligatorio. to restringe la sottoscrizione ai depositi sul tuo indirizzo, from ai trasferimenti in uscita e contractaddress a un singolo token. type seleziona la classe di asset e accetta TRX, TRC10, TRC20 o TRC721. reference contiene fino a 255 caratteri di testo tuo: è il posto per l'ID dell'ordine o del cliente, così la notifica arriva con la tua chiave di ricerca già allegata.
curl -X POST https://app.chaingateway.io/api/v2/tron/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-backend.example/hooks/tron",
"to": "TYourDepositAddress",
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"reference": "customer-4711"
}'
Imposta un secret personale nel tuo account e ogni consegna porta un header X-Signature, un HMAC-SHA256 codificato in base64 calcolato sul txid del payload. Verificalo prima di analizzare qualsiasi altra cosa.
Nulla rinvia da solo una consegna fallita. GET /api/v2/tron/webhooks/notifications/failed elenca ciò che non è arrivato e POST /api/v2/tron/webhooks/notifications/{id}/retry è la chiamata che ne invia di nuovo una. Una voce esce dall'elenco dei fallimenti quando parte il suo retry e ci ritorna solo se anche quel retry fallisce. Poiché un retry consegna lo stesso evento una seconda volta, salva l'hash di transazione di ogni deposito accreditato con un vincolo di unicità e lascia che sia il database a rifiutare il duplicato. Codice per la firma e forme dei payload sono nella guida ai webhook.
Come invio USDT-TRC20 dall'indirizzo?
POST /api/v2/tron/transactions/trc20 richiede quattro campi: from, to, contractaddress e amount. L'importo è un numero semplice in unità del token, quindi 25 USDT sono 25 e non un valore scalato per i sei decimali del contratto. Insieme a essi invii password, per una chiave che l'API tiene cifrata, oppure privatekey, se hai conservato la chiave tu.
Nel campo contractaddress la distinzione tra indirizzo di wallet e indirizzo di contratto diventa una regola concreta di integrazione: l'indirizzo del contratto identifica quale token si muove e non è mai la destinazione. Quello di USDT è TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t e va in contractaddress, mai in to. I token inviati a un indirizzo di contratto sono quasi sempre irrecuperabili. La guida sul blog spiega perché i due sembrano identici: sono entrambi stringhe T e nulla nella stringa li distingue.
Inviare costa Energy e Bandwidth, mentre ricevere è gratis, quindi un sistema di depositi paga al momento del sweep e non al deposito. Il calcolatore delle commissioni TRON stima il costo di un trasferimento specifico, e GET /api/v2/tron/chainparameters restituisce i prezzi correnti delle risorse, così il tuo codice non fissa una costante che un voto di governance può invalidare.
Come valido un indirizzo TRC20 prima dell'invio?
Controlla la destinazione nel momento in cui l'utente la invia, non dopo la trasmissione. Un indirizzo TRC-20 ha 34 caratteri, inizia con T e contiene un checksum Base58Check che un solo carattere errato invalida, quindi una stringa ben formata si distingue da un errore di battitura senza interrogare la rete. Il validatore di indirizzi esegue nel browser questo controllo per TRC-20, ERC-20 e BEP-20, se vuoi verificare un indirizzo a mano.
C'è una cosa che il controllo non può fare: scambiare per errore un indirizzo TRON con uno EVM, perché i formati differiscono in modo visibile. Una stringa T non supera la validazione di Ethereum e una stringa 0x non supera quella di TRON. La TVM di TRON esegue gran parte del Solidity scritto per la EVM, ma è un runtime separato, con un proprio conteggio delle risorse (Energy e Bandwidth invece del gas) e una propria codifica degli indirizzi. Prendere «TRON EVM» alla lettera è il punto da cui nascono i bug di indirizzo tra chain diverse.
Fonti
Stai costruendo un checkout o un backend di exchange che richiede indirizzi TRC20 su larga scala? Crea un account gratuito e genera un gruppo di indirizzi su testnet. Prova di 7 giorni, senza carta, senza KYC.
FAQ: l'API per indirizzi TRC20
Pronto a creare il tuo primo indirizzo TRC20?
Crea un account e genera oggi un indirizzo TRC20 su testnet. Prova di 7 giorni, senza carta, senza KYC. Il riferimento completo degli endpoint è nella pagina TRON API, la domanda sul formato ha risposta in Che cos'è un indirizzo TRC20? e tutte e sette le chain passano dallo stesso schema nella blockchain API multichain.
Verificato da Maurice Sobiera Come scriviamo queste pagine