TRON is a high-throughput EVM-adjacent L1 with a delegated-PoS consensus and a resource model (Bandwidth + Energy) that lets users transact for free if they freeze TRX. It's the dominant chain for USDT volume — TRC-20 USDT is the highest-supply USDT issuance in the world. `tronweb` is the canonical JS/TS SDK for chain reads, transaction building, and contract interaction; TronLink is the standard browser wallet (CIP-equivalent injection).
- 01TRON dapps and TRC-20 / TRC-721 token interactions
- 02USDT-TRC20 stablecoin payment flows
- 03TronLink / Klever / Ledger wallet auth
- 04free-tier transactions via Bandwidth / Energy staking
- 05high-throughput, low-cost consumer payments in emerging markets
- pnpm add tronweb
| Variable | Scope | Description |
|---|---|---|
| NEXT_PUBLIC_TRON_NETWORK | Client | `mainnet`, `shasta` (testnet), or `nile` (testnet) — selects fullnode and explorer. |
| NEXT_PUBLIC_TRON_FULL_HOST | Client | Tron HTTP API endpoint (e.g. https://api.trongrid.io for mainnet, https://api.shasta.trongrid.io for Shasta). |
| TRONGRID_API_KEY | Server | TronGrid API key (https://www.trongrid.io) to lift free-tier rate limits. Server-side only. |
Use `tronweb`. Initialize with `const tronWeb = new TronWeb({ fullHost: process.env.NEXT_PUBLIC_TRON_FULL_HOST!, headers: { 'TRON-PRO-API-KEY': process.env.TRONGRID_API_KEY }, privateKey });`. Send TRX with `await tronWeb.trx.sendTransaction(toAddress, amountSun)` (1 TRX = 1,000,000 SUN). For TRC-20 (e.g. USDT) load the contract: `const usdt = await tronWeb.contract().at('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'); await usdt.transfer(to, amount).send({ feeLimit: 100_000_000 });`. In the browser, detect TronLink via `window.tronLink` then `await window.tronLink.request({ method: 'tron_requestAccounts' })` and use `window.tronWeb` (injected) for signing. Convert addresses with `tronWeb.address.toHex(base58)` / `.fromHex(hex)` — TRON uses base58 (`T…`) but contract ABIs return hex (`41…`).
- ⚑TRON has a resource model — every transaction consumes Bandwidth (free, regenerates daily) and contract calls also consume Energy. Users without enough resources fall back to burning TRX, which can make a `transfer()` cost $1+ instead of being free; always inform users to freeze TRX or use a fee-payer relayer.
- ⚑Addresses use base58 (`T…`, ~34 chars) on the user-facing side but hex (`41…`, 21 bytes) inside contracts. Mixing them silently breaks contract calls — `tronWeb.address.toHex` / `.fromHex` is mandatory at the boundary.
- ⚑TRON is EVM-derived but NOT EVM-compatible at the JSON-RPC level. Smart contracts are Solidity and use the same ABI, but you cannot point ethers/viem at a TRON node — you must use `tronweb`. There is a separate JSON-RPC service (`api.trongrid.io/jsonrpc`) but it covers only a subset and is not a drop-in viem target.
- ⚑Contract call `feeLimit` is the maximum TRX (in SUN) you'll burn for Energy; the default is too low for most token transfers. Always set `feeLimit: 100_000_000` (100 TRX) or higher and let the network refund unused fee.
- ⚑USDT-TRC20 is the most-transferred asset on TRON but is centralized — Tether can blacklist addresses, and the contract has a `pause` switch. Production payment flows must handle `transfer` reverts due to recipient blacklist.
- ⚑Block time is 3s and finality is 19 blocks (~57s) under DPoS — `txID` returned from `sendTransaction` is provisional; poll `tronWeb.trx.getTransactionInfo(txID)` until `receipt.result === 'SUCCESS'` and `confirmed === true`.
- ⚑Multi-sig accounts have weighted permissions (Owner/Active) — `tronWeb.transactionBuilder` builders that sign with a single key on a multi-sig account silently produce a tx that the network rejects with `Permission denied`.