TRON API: pagamenti USDT-TRC20 via REST

Tether aveva emesso circa 190 miliardi di dollari di USDT entro aprile 2026. TRON deteneva circa il 45% di quell'offerta, circa 85 miliardi di dollari, con Ethereum poco dietro con circa il 40%; le due chain si sono scambiate la leadership più di una volta dalla fine del 2025. Su TRON stessa il quadro è inequivocabile: USDT rappresentava il 98,6% del valore in stablecoin della chain nel primo trimestre del 2026. Chi dice TRC-20 intende, in pratica, USDT.

L'offerta è solo metà della storia. Il volume dei trasferimenti dice a cosa serve una chain, e il volume USDT di TRON si è avvicinato ai 2.000 miliardi di dollari nel primo trimestre del 2026. L'USDT di Ethereum tende verso il collaterale DeFi e la liquidazione istituzionale. Quello di TRON è la versione che le persone muovono davvero: depositi su exchange, rimesse, pagamenti a collaboratori in paesi dove un saldo in dollari batte il conto bancario locale.

Per una decisione di integrazione la conseguenza è chiara. Se i tuoi utenti scelgono una rete di deposito da un menu a tendina, TRC-20 sarà la voce più scelta, e i ticket di supporto per rete sbagliata diminuiscono quando la tua opzione predefinita corrisponde a ciò che gli utenti si aspettano. Costruisci prima TRON; lo schema di richiesta condiviso ti permette di aggiungere le altre chain in seguito senza nuovo codice.

TRON misura due risorse. Bandwidth copre i semplici trasferimenti ed è gratuita fino a 600 punti al giorno. Energy non ha alcuna soglia gratuita e si applica ogni volta che gira uno smart contract, motivo per cui un trasferimento USDT, una chiamata a contratto TRC-20, costa sempre di più che inviare TRX semplice.

TRON non ha un unico prezzo del gas. La rete misura due risorse separate, e sapere quale consuma la tua transazione è la differenza tra commissioni prevedibili e ticket di supporto a sorpresa.

Bandwidth viene addebitata su ogni transazione e segue la dimensione in byte. Ogni account riceve 600 punti gratuiti al giorno; un semplice trasferimento TRX pesa 250-300 byte, quindi i trasferimenti TRX occasionali non costano nulla. Superata la quota gratuita, la rete brucia 0,001 TRX per punto, circa 0,35 TRX per un tipico trasferimento TRC-20.

Energy si applica solo quando gira uno smart contract, e non ha alcuna soglia giornaliera gratuita. Un trasferimento USDT è una chiamata a contratto, il contratto TRC-20 aggiorna la propria tabella interna dei saldi, quindi richiede Energy oltre a Bandwidth. Da quando la Proposal #104 di governance è entrata in vigore ad agosto 2025, un'unità di Energy costa 100 Sun, dimezzata rispetto ai 210 precedenti. Un trasferimento verso un indirizzo che possiede già USDT richiede circa 64.000 unità di Energy, pari a 6,4 TRX. Un trasferimento verso un indirizzo che non ha mai posseduto USDT scrive una nuova voce di storage, e il nuovo stato costa circa il doppio dell'Energy di un aggiornamento: circa 134.000 unità, ovvero 13,4 TRX.

Prima di inviare, due strumenti rendono concreti i numeri. La calcolatrice delle commissioni TRON calcola Bandwidth, Energy e il totale in TRX per una transazione specifica, e GET /api/v2/tron/chainparameters restituisce i prezzi unitari in tempo reale così il tuo codice non fissa mai una costante che il prossimo voto di governance cambia. La guida alle commissioni tratta la meccanica in profondità.

Ogni trasferimento TRC-20 richiede Energy, e quell'Energy deve provenire da qualche parte. Per la maggior parte dei mittenti, la fonte è il proprio saldo TRX. Questa assunzione si rompe in due situazioni comuni, ed entrambe generano difficoltà operative finché non le risolvi in modo strutturale.

La tua flotta di wallet di deposito

Ogni wallet che inoltra fondi a un hot wallet ha bisogno di un proprio saldo TRX per il consolidamento, e con qualche migliaio di wallet, tenerli riforniti diventa un lavoro a sé, con i propri costi di commissione per i trasferimenti di ricarica. Le commissioni sponsorizzate eliminano questo lavoro. Il modo consigliato per configurarlo oggi è TronFuel, che noleggia Energy reperita in blocco dagli staker — lo stesso meccanismo che la guida alle commissioni descrive come capace di tagliare i costi di commissione fino al 60% rispetto al bruciare TRX al prezzo di mercato. Gli endpoint Paymaster legacy di Chaingateway fanno lo stesso e restano disponibili per le integrazioni esistenti.

I tuoi clienti finali

Un utente possiede 200 USDT in un wallet self-custody e zero TRX; gli USDT sono arrivati da un exchange o da un'altra persona, e nessuno gli ha detto che serve una seconda valuta per spostarli. Quando prova a pagarti o a prelevare, il trasferimento fallisce. Dal punto di vista dell'utente, il denaro è bloccato. Dal punto di vista della tua coda di supporto, è un ticket ricorrente che nessuna voce di FAQ elimina del tutto, perché la soluzione, "vai a comprare un po' di TRX su un exchange prima", è esattamente l'attrito che il cliente voleva evitare usando le stablecoin. Un trasferimento sponsorizzato pone fine a questo: invii il trasferimento, lo sponsor copre Energy e Bandwidth, il costo ricade sul tuo account, e il cliente non impara mai cos'è TRX. Per i flussi di checkout e prelievo, questa unica modifica elimina la modalità di fallimento più comune dei pagamenti TRC-20.

Stimare il prezzo e creare un trasferimento sponsorizzato

Prima stima il prezzo di una transazione sponsorizzata, poi creala:

# 1. Estimate the fee
curl -X POST https://app.chaingateway.io/api/v2/tron/paymaster/estimate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TDepositWallet", "to": "THotWallet", "amount": "500"}'

# 2. Create the Paymaster request
curl -X POST https://app.chaingateway.io/api/v2/tron/paymaster \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TDepositWallet", "to": "THotWallet", "amount": "500", "password": "YourWalletPassword"}'

GET /api/v2/tron/paymaster elenca ogni richiesta creata e ne riporta lo stato, da pending a completed o failed, e GET /api/v2/tron/paymaster/balance mostra il credito di sponsorizzazione rimasto — insieme coprono la riconciliazione.

Importare una private key è il percorso più veloce verso la produzione, ma alcuni team non possono inviare materiale di key a terzi in alcun modo. Il motivo può essere una policy interna, un regolatore, o un modulo di sicurezza hardware le cui key non possono fisicamente essere esportate. La TRON API ha una seconda modalità costruita esattamente per questo vincolo.

Il flusso prevede tre passaggi. Chiama POST /api/v2/tron/transactions/trc20/build, o /api/v2/tron/transactions/build per TRX semplice, con gli stessi campi che useresti per un invio normale. L'API restituisce la transazione grezza non firmata. Firma quel payload dove risiedono le tue key: un HSM, una macchina air-gapped, un servizio di firma dietro il tuo firewall. Poi invia il risultato firmato tramite POST /api/v2/tron/transactions/broadcast, che lo trasmette alla rete e restituisce l'hash della transazione.

# 1. Build the unsigned transaction
curl -X POST https://app.chaingateway.io/api/v2/tron/transactions/trc20/build \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TColdWallet", "to": "TRecipient", "amount": 1000}'

# 2. Sign locally with your own tooling, then broadcast
curl -X POST https://app.chaingateway.io/api/v2/tron/transactions/broadcast \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signed_transaction": "<the signed transaction as a JSON string>"}'

Due cose da sapere prima di scegliere questa modalità. Una transazione TRON costruita scade dopo una breve finestra, quindi il passaggio di firma e trasmissione deve avvenire tempestivamente invece di restare in coda tutta la notte. E la responsabilità operativa si sposta: dal tuo lato gestisci la libreria di firma e i suoi aggiornamenti. Ciò che guadagni è che Chaingateway non vede mai un segreto. Il monitoraggio dei depositi non è comunque influenzato, dato che osservare un indirizzo non richiede alcuna key. Molte configurazioni di produzione mescolano entrambe le modalità, key importate per wallet operativi a basso valore, self-signing per il percorso di tesoreria.

Fare polling su un explorer per i trasferimenti in entrata spreca richieste e comunque sbaglia i tempi. Chaingateway invia al posto tuo. Registra un webhook e il tuo backend riceve una POST con stato della transazione, conferme e variazioni di saldo. Imposta un secret personale nel tuo account e ogni consegna porta un header X-Signature — un HMAC-SHA256 in base64 del txid del payload — così puoi verificare il mittente. Le consegne fallite finiscono in un elenco di notifiche fallite, e POST /api/v2/tron/webhooks/notifications/{id}/retry le reinvia una a una.

GET /api/v2/tron/webhooks/notifications restituisce le notifiche passate, utile quando devi riprodurre eventi dopo un deploy andato male. La configurazione richiede pochi minuti con la guida ai webhook.

I mittenti ad alto volume non dovrebbero bruciare TRX per sempre. Fai freeze del TRX tramite POST /api/v2/tron/freeze e la rete concede Bandwidth o Energy in cambio; instrada quelle risorse verso il tuo hot wallet con POST /api/v2/tron/delegate. Unfreeze e undelegate invertono entrambi i passaggi quando vuoi riavere il capitale.

I prezzi attuali delle risorse arrivano da GET /api/v2/tron/chainparameters. Dalla Proposal #104 il prezzo unitario dell'Energy è 100 Sun, in calo da 210, il che ha spostato il punto di pareggio tra staking e burning. Controlla il valore in tempo reale prima di dimensionare uno stake.

L'aritmetica favorisce lo staking man mano che il volume cresce, perché il TRX bruciato scompare mentre il TRX in staking è semplicemente parcheggiato. Come cifra approssimativa di metà 2026, uno stake nell'ordine di 5.000 TRX generava circa l'equivalente in Energy di un trasferimento USDT al giorno. Un business che invia 50 trasferimenti al giorno avrebbe bisogno di uno stake nell'ordine delle centinaia di migliaia di TRX per coprire interamente la propria Energy solo tramite staking. Considera queste cifre come ordini di grandezza piuttosto che come quotazioni: il tuo rendimento giornaliero dipende da quanto TRX ha in staking l'intera rete, e quel rapporto si sposta nel tempo. La calcolatrice delle commissioni e l'endpoint dei parametri di chain ti danno i dati odierni per il calcolo.

La delegazione è ciò che rende lo staking operativamente pulito. Mantieni lo stake su un indirizzo di tesoreria che non tocca mai il traffico dei clienti, poi fai delegate della sua Energy verso gli hot wallet che effettuano gli invii veri e propri. Quando un wallet viene ritirato, fai undelegate e punta le risorse verso il suo successore; il TRX in staking stesso non si muove mai. Un'avvertenza per la pianificazione di tesoreria: dopo l'unfreeze, il TRX resta bloccato per un periodo di attesa di circa due settimane prima di poter essere speso di nuovo, quindi uno stake non è una riserva ad accesso istantaneo. Dimensionalo sul volume a regime e copri i picchi con Energy noleggiata.

Chaingateway supporta i tipi di token standard su TRON. USDT, USDC e DAI funzionano immediatamente con gestione automatica dei decimali. Per un token che hai lanciato tu stesso, passa il suo contract address e l'API lo tratta come qualsiasi altro TRC-20. Lo schema di richiesta è condiviso tra le chain, quindi la chiamata ERC-20 su Ethereum, BNB Smart Chain, Polygon o Arbitrum appare esattamente come la tua chiamata TRC-20, con un segmento di percorso diverso.

La rete è progettata per circa 2.000 transazioni al secondo, il che si adatta a carichi di pagamento fatti di molti piccoli trasferimenti. Le commissioni restano abbastanza basse da rendere praticabili i micropagamenti, pochi TRX per trasferimento di token invece di una commissione che divora il pagamento. TRON detiene una quota maggiore dell'USDT in circolazione rispetto a qualsiasi altra chain, quindi le controparti con cui i tuoi utenti hanno a che fare sono già lì, e l'ecosistema di wallet attorno a TRC-20 è abbastanza maturo da far sì che gli strumenti raramente intralcino.

Le integrazioni tipiche assomigliano a questo: un flusso di checkout che accetta USDT e accredita l'ordine dopo la conferma; un backend di exchange che osserva migliaia di indirizzi di deposito ed elabora prelievi da un hot wallet; sistemi di pagamento che eseguono airdrop o piani di vesting; fatturazione di abbonamenti che addebita in stablecoin ogni mese; servizi di rimessa che spostano valore attraverso confini in pochi minuti. La stessa API copre ogni pattern. Ciò che cambia è quali endpoint combini.

Ogni endpoint di questa pagina accetta l'header X-Network: testnet. Con esso, la stessa richiesta gira sulla testnet di TRON: stessi percorsi, stessi payload, stesse forme di risposta. Il TRX di test arriva gratis dai faucet pubblici, quindi una prova completa non costa nulla — crea un indirizzo di deposito, invia un trasferimento TRC-20, ricevi il webhook, verifica la firma HMAC, consolida su un hot wallet.

Prova il percorso del webhook almeno una volta dall'inizio alla fine. Gli errori di integrazione classici, un controllo firma sulla codifica payload sbagliata o un firewall che scarta silenziosamente la consegna, emergono su testnet esattamente come farebbero in produzione, dove costano depositi reali invece di token di prova. Andare in produzione dopo significa eliminare un header; il quickstart mostra l'intero ciclo.

Due classi di fallimento richiedono trattamenti opposti. Una risposta 4xx significa che la richiesta stessa è sbagliata: un Bearer token mancante o scaduto, un indirizzo malformato, un importo che il wallet mittente non può coprire. Registralo e correggi la causa, ma non ripetere invariato, perché un input identico produce un rifiuto identico. Una risposta 5xx o un timeout di rete non dicono nulla sul tuo input; riprova con backoff esponenziale e un limite massimo.

Il caso limite che merita una progettazione dedicata è il timeout dopo un invio. Il tuo client HTTP ha rinunciato, ma la transazione potrebbe comunque essere stata trasmessa. Inviare di nuovo lo stesso trasferimento per riflesso è il modo in cui accadono i pagamenti doppi. Controlla prima cosa è effettivamente uscito: GET /api/v2/tron/transactions elenca i trasferimenti creati tramite il tuo account. Reinvia solo se il primo tentativo è verificabilmente fallito. Per i fallimenti legati alle commissioni esiste un pattern ancora più economico: controlla GET /api/v2/tron/chainparameters e le risorse del wallet prima di inviare, trasformando un errore a runtime in un controllo preventivo.