TronWeb Introduction: JavaScript SDK for TRON Blockchain

TronWeb is the primary JavaScript SDK for TRON development — analogous to ethers.js on Ethereum. It handles address encoding, transaction building, smart contract calls, and wallet integration for dApps, backends, and scripts.

This introduction covers installation, configuration, core concepts, and your first TRX transfer from code.

When to use TronWeb

Use TronWeb when you need to:

• Build a web dApp that connects to TronLink or uses embedded keys
• Run backend services that send USDT or trigger contracts
• Deploy and interact with TRC-20 / Solidity contracts
• Subscribe to events (with polling or extensions)

For pure HTTP access without SDK abstractions, see TronGrid API guide and HTTP API reference.

Installation

npm install tronweb

Browser: bundle via webpack/vite or load from CDN for prototypes (prefer npm for production).

Basic setup

Read-only (no private key)

const TronWeb = require('tronweb');

const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  headers: { 'TRON-PRO-API-KEY': 'your-api-key' },
});

Get API keys from TronGrid.

With signing key (server-side only)

const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  privateKey: process.env.TRON_PRIVATE_KEY,
  headers: { 'TRON-PRO-API-KEY': process.env.TRONGRID_KEY },
});

Shasta testnet

const tronWeb = new TronWeb({
  fullHost: 'https://api.shasta.trongrid.io',
  privateKey: 'your-shasta-test-key',
});

Get free Shasta TRX from faucets for testing TRC-20 deployment.

Core objects

Send TRX example

async function sendTrx(toAddress, amountTrx) {
  const amountSun = tronWeb.toSun(amountTrx);
  const tx = await tronWeb.trx.sendTransaction(toAddress, amountSun);
  return tx;
}

Track confirmation with verify transaction API.

TRC-20 interaction

const USDT = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t';

async function getUsdtBalance(address) {
  const contract = await tronWeb.contract().at(USDT);
  const balance = await contract.balanceOf(address).call();
  return tronWeb.toBigNumber(balance).div(1e6).toString();
}

Deep dive: query TRC-20 balance and send USDT programmatically.

TronLink integration (browser)

async function getTronWeb() {
  if (window.tronLink && window.tronLink.ready) {
    return window.tronLink.tronWeb;
  }
  throw new Error('TronLink not found');
}

User signs transactions in wallet popup — your site never sees private key.

Error handling

Common failures:

• OUT_OF_ENERGY — account needs TRX or frozen Energy
• REVERT — smart contract rejected call
• Invalid address — always tronWeb.isAddress() before send

Map to user-friendly messages in production apps.

Project structure tips

• Separate read-only TronWeb instance for public queries
• Signer module isolated on server with HSM or env secrets
• Rate-limit TronGrid calls; cache block numbers
• Use event listeners for deposit detection

Security

• Smart contract security
• Validate all user-supplied addresses
• Never log private keys
• Simulate contract calls when possible before mainnet sends

TronWeb vs other SDKs

Python developers use tronpy; Go teams use gotron-sdk. TronWeb remains the most documented for browser dApps and Node.js backends. Choose based on your stack — concepts (address encoding, signing, ABI) transfer across libraries.

Environment variables and secrets

Never commit private keys. Use .env files excluded from git, or cloud secret managers in production. TronWeb instances on servers should use dedicated hot wallets with minimal balances — sweep to cold storage. Rotate keys if logs may have captured environment dumps.

Related guides

• TronGrid API guide
• Trigger smart contract
• TRON HTTP API reference
• Deploy TRC-20 TronWeb

FAQ

What is TronWeb?

TronWeb is the official JavaScript library for interacting with the TRON blockchain — accounts, contracts, transactions, and queries from Node.js or browser apps.

Do I need a private key to read blockchain data?

No. Read-only operations like balance queries work with a public full node or TronGrid API key without exposing private keys.

TronWeb vs TronGrid?

TronGrid is the hosted API infrastructure. TronWeb is the client SDK that talks to TronGrid or your own full node.

Does TronWeb support TypeScript?

Use @types community packages or TronWeb's bundled types where available. Wrap contract calls with typed interfaces in app code.

What version should I use?

Pin latest stable from npm and test on Shasta before mainnet deploys.