API Reference

Table of Contents

WalletManagerTron

The main class for managing Tron wallets. Extends WalletManager from @tetherto/wdk-wallet.

Fee Rate Constants

const FEE_RATE_NORMAL_MULTIPLIER = 110n
const FEE_RATE_FAST_MULTIPLIER = 200n

Constructor

new WalletManagerTron(seed, config?)

Parameters:

• seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes
• config (TronWalletConfig, optional): Configuration object
  • provider (string | TronWeb | Array<string | TronWeb>, optional): Tron RPC endpoint URL, TronWeb instance, or ordered failover list
  • retries (number, optional): Additional failover attempts when provider is an array (default: 3)
  • transferMaxFee (number | bigint, optional): Maximum fee amount for TRC20 transfer operations (in sun)
  • transactionMaxFee (number | bigint, optional): Maximum fee amount for sendTransaction() and signTransaction() operations (in sun)

Example:

const wallet = new WalletManagerTron(seedPhrase, {
  provider: 'https://api.trongrid.io', // Tron RPC endpoint
  transferMaxFee: 10000000n, // Maximum TRC20 transfer fee in sun
  transactionMaxFee: 10000000n // Maximum send/sign transaction fee in sun
})

// Or with TronWeb instance
const tronWeb = new TronWeb({ fullHost: 'https://api.trongrid.io' })
const wallet2 = new WalletManagerTron(seedPhrase, {
  provider: tronWeb,
  transferMaxFee: 10000000n,
  transactionMaxFee: 10000000n
})

// Or with ordered provider failover
const wallet3 = new WalletManagerTron(seedPhrase, {
  provider: [
    'https://api.trongrid.io',
    'https://secondary-tron-rpc.example'
  ],
  retries: 3
})

Methods

getAccount(index?)

Returns a wallet account at the specified index using Tron's BIP-44 derivation (m/44'/195').

Parameters:

• index (number, optional): The index of the account to get (default: 0)

Returns: Promise\<WalletAccountTron\> - The wallet account

Example:

// Get first account (m/44'/195'/0'/0/0)
const account = await wallet.getAccount(0)

// Get second account (m/44'/195'/0'/0/1)
const account1 = await wallet.getAccount(1)

getAccountByPath(path)

Returns a wallet account at the specified BIP-44 derivation path.

Parameters:

• path (string): The derivation path (e.g., "0'/0/0")

Returns: Promise\<WalletAccountTron\> - The wallet account

Example:

// Full path: m/44'/195'/0'/0/1
const account = await wallet.getAccountByPath("0'/0/1")

getFeeRates()

Returns current fee rates from Tron network chain parameters.

Returns: Promise\<{normal: bigint, fast: bigint}\> - Fee rates in sun

• normal: Base fee × 1.1
• fast: Base fee × 2.0

Throws: Error if no TronWeb provider is configured

Example:

const feeRates = await wallet.getFeeRates()
console.log('Normal fee rate:', feeRates.normal, 'sun')
console.log('Fast fee rate:', feeRates.fast, 'sun')

dispose()

Disposes all wallet accounts, clearing private keys from memory.

Example:

wallet.dispose()

WalletAccountTron

Represents an individual Tron wallet account. Extends WalletAccountReadOnlyTron and implements IWalletAccount.

Constants

const BIP_44_TRON_DERIVATION_PATH_PREFIX = "m/44'/195'"
const BANDWIDTH_PRICE = 1_000n

Constructor

new WalletAccountTron(seed, path, config?)

Parameters:

• seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes
• path (string): BIP-44 derivation path (e.g., "0'/0/0")
• config (TronWalletConfig, optional): Configuration object

Throws: Error if seed phrase is invalid (BIP-39 validation fails)

Example:

const account = new WalletAccountTron(seedPhrase, "0'/0/0", {
  provider: 'https://api.trongrid.io',
  transferMaxFee: 10000000n, // Maximum TRC20 transfer fee in sun
  transactionMaxFee: 10000000n // Maximum send/sign transaction fee in sun
})

Methods

getAddress()

Returns the account's Tron address (starts with 'T').

Returns: Promise\<string\> - The account's Tron address

Example:

const address = await account.getAddress()
console.log('Account address:', address) // T...

sign(message)

Signs a message using Keccak-256 hash and secp256k1 signature.

Parameters:

• message (string): The message to sign (UTF-8 encoded)

Returns: Promise\<string\> - The message signature (hex string)

Example:

const message = 'Hello, Tron!'
const signature = await account.sign(message)
console.log('Signature:', signature)

verify(message, signature)

Verifies a message signature using secp256k1.

Parameters:

• message (string): The original message
• signature (string): The signature to verify (hex string)

Returns: Promise\<boolean\> - True if signature is valid

Example:

const isValid = await account.verify('Hello, Tron!', signature)
console.log('Signature valid:', isValid)

signTransaction(tx)

Signs a Tron transaction and returns the signed transaction object. This method does not broadcast the transaction.

Parameters:

• tx (TronTransaction): Native TRX transfer, smart-contract call descriptor, or pre-built TronWeb transaction

Returns: Promise\<TronSignedTransaction\> - Signed Tron transaction object with a signature array

Throws:

• Error if no TronWeb provider is configured
• Error if fee exceeds transactionMaxFee when configured
• Error if an unsigned pre-built transaction's txID does not match its serialized raw data
• Error if a pre-built transaction is owned by a different account

Example:

const signedTransaction = await account.signTransaction({
  to: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH',
  value: 1000000
})

console.log('Signed transaction:', signedTransaction)

sendTransaction(tx)

Sends a Tron transaction and returns the result with hash, fee, and activation fee details.

Parameters:

• tx (TronTransaction | TronSignedTransaction): Native TRX transfer, smart-contract call descriptor, pre-built unsigned TronWeb transaction, or signed transaction

When tx has a signature, WDK quotes it again, enforces transactionMaxFee, and forwards the exact object to tronWeb.trx.sendRawTransaction(). It does not rebuild the transaction, refresh its reference block or expiration, re-sign it, or repeat the unsigned pre-built raw-data and owner checks.

Returns: Promise\<{hash: string, fee: bigint, activationFee: bigint}\> - Transaction hash, total fee in sun, and the portion used for account activation

Throws:

• Error if no TronWeb provider is configured
• Error if fee exceeds transactionMaxFee when configured
• Error if an unsigned pre-built transaction's txID does not match its serialized raw data
• Error if an unsigned pre-built transaction is owned by a different account

Example:

const result = await account.sendTransaction({
  to: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH', // Tron address
  value: 1000000 // 1 TRX in sun
})
console.log('Transaction hash:', result.hash)
console.log('Transaction fee:', result.fee, 'sun')
console.log('Activation fee:', result.activationFee, 'sun')

quoteSendTransaction(tx)

Estimates the cost for a Tron transaction. Quotes include bandwidth for every transaction, energy for smart-contract execution, and activation fee for native transfers to inactive recipients.

Parameters:

• tx (TronTransaction | TronSignedTransaction): An unsigned transaction input or signed transaction

Returns: Promise\<{fee: bigint, activationFee: bigint}\> - Fee estimate in sun and the portion used for account activation

Throws: Error if no TronWeb provider is configured

Example:

const quote = await account.quoteSendTransaction({
  to: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH',
  value: 1000000
})
console.log('Estimated fee:', quote.fee, 'sun')
console.log('Activation fee:', quote.activationFee, 'sun')

transfer(options)

Transfers TRC20 tokens using smart contract call.

Parameters:

• options (TransferOptions): Transfer options
  • token (string): TRC20 contract address (e.g., 'T...')
  • recipient (string): Recipient Tron address (e.g., 'T...')
  • amount (number | bigint): Amount in token's base units

Returns: Promise\<{hash: string, fee: bigint}\> - Transaction hash and fee in sun

Throws:

• Error if no TronWeb provider is configured
• Error if fee exceeds transferMaxFee

Example:

const result = await account.transfer({
  token: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', // USDT TRC20
  recipient: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH',
  amount: 1000000 // 1 USDT (6 decimals)
})
console.log('Transfer hash:', result.hash)
console.log('Transfer fee:', result.fee, 'sun')

quoteTransfer(options)

Estimates the TRC20 token transfer cost from current chain parameters, account resources, contract energy use, and bandwidth use.

Parameters:

• options (TransferOptions): Transfer options (same as transfer)

Returns: Promise\<{fee: bigint}\> - Fee estimate in sun (energy + bandwidth costs)

Throws: Error if no TronWeb provider is configured

Example:

const quote = await account.quoteTransfer({
  token: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
  recipient: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH',
  amount: 1000000
})
console.log('Transfer fee estimate:', quote.fee, 'sun')

getBalance()

Returns the native TRX balance.

Returns: Promise\<bigint\> - Balance in sun

Throws: Error if no TronWeb provider is configured

Example:

const balance = await account.getBalance()
console.log('TRX balance:', balance, 'sun')

getTokenBalance(tokenAddress)

Returns the balance of a specific TRC20 token.

Parameters:

• tokenAddress (string): The TRC20 contract address (e.g., 'T...')

Returns: Promise\<bigint\> - Token balance in base units

Throws: Error if no TronWeb provider is configured

Example:

const tokenBalance = await account.getTokenBalance('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t')
console.log('USDT balance:', tokenBalance) // In 6 decimal units

getTransactionReceipt(hash)

Returns a native TRON receipt if it has been processed. This method is deprecated; use getTransaction() for normalized finality and read its receipt field when you need the native object.

Parameters:

• hash (string): The transaction hash

Returns: Promise\<TronTransactionReceipt | null\> - Transaction receipt or null

Throws: Error if no TronWeb provider is configured

Example:

const receipt = await account.getTransactionReceipt('0x...')
console.log('Transaction confirmed:', receipt.success)

getTransaction(hash)

Returns a normalized receipt for a trimmed 64-hex-character TRON transaction ID; an optional 0x prefix is accepted. A provider result without blockNumber is pending. A block-included transaction is confirmed, becoming final when its block is at or below the latest solidified block.

Included receipts expose success, block, fee, confirmations, and the native receipt. If the solidified block cannot be resolved, the transaction remains confirmed and confirmations is null. success is false when the top-level result is FAILED or the contract result is not SUCCESS.

Throws: ValueError for an invalid transaction ID and NoSuchElementError when the provider returns no transaction.

const transaction = await account.getTransaction(result.hash)
console.log(transaction.finality)     // 'pending', 'confirmed', or 'final'
console.log(transaction.confirmations) // number or null

waitForTransaction(hash, options?)

Polls until the requested finality is reached or the wait times out. Defaults are target: 'confirmed', interval: 4000, timeout: 90000, and maxPollErrors: 3. An unknown transaction is retried until timeout; this implementation does not currently emit dropped receipts.

const transaction = await account.waitForTransaction(result.hash, {
  target: 'final',
  timeout: 180000
})

toReadOnlyAccount()

Creates a read-only copy of the account.

Returns: Promise\<WalletAccountReadOnlyTron\> - Read-only account instance

Example:

const readOnlyAccount = await account.toReadOnlyAccount()

// Can check balances but cannot send transactions
const balance = await readOnlyAccount.getBalance()

dispose()

Disposes the wallet account, clearing private keys from memory using sodium_memzero.

Example:

account.dispose()

Properties

Example:

console.log('Account index:', account.index) // 0, 1, 2, etc.
console.log('Account path:', account.path) // m/44'/195'/0'/0/0

const { privateKey, publicKey } = account.keyPair
console.log('Public key length:', publicKey.length) // 33 bytes (compressed)
console.log('Private key length:', privateKey?.length) // 32 bytes before dispose()

WalletAccountReadOnlyTron

Represents a read-only Tron wallet account that can query balances and estimate fees but cannot send transactions.

Constructor

new WalletAccountReadOnlyTron(address, config?)

Parameters:

• address (string): The account's Tron address
• config (Omit<TronWalletConfig, 'transferMaxFee' | 'transactionMaxFee'>, optional): Configuration object without send-only fee caps

Example:

const readOnlyAccount = new WalletAccountReadOnlyTron('TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH', {
  provider: 'https://api.trongrid.io'
})

Methods

getBalance()

Returns the native TRX balance.

Returns: Promise\<bigint\> - Balance in sun

Throws: Error if no TronWeb provider is configured

Example:

const balance = await readOnlyAccount.getBalance()
console.log('TRX balance:', balance, 'sun')

getTokenBalance(tokenAddress)

Returns the balance of a specific TRC20 token.

Parameters:

• tokenAddress (string): The TRC20 contract address

Returns: Promise\<bigint\> - Token balance in base units

Throws: Error if no TronWeb provider is configured

Example:

const tokenBalance = await readOnlyAccount.getTokenBalance('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t')
console.log('USDT balance:', tokenBalance)

quoteSendTransaction(tx)

Estimates the cost for a Tron transaction. Quotes include bandwidth for every transaction, energy for smart-contract execution, and activation fee for native transfers to inactive recipients.

Parameters:

• tx (TronTransaction): The transaction object

Returns: Promise\<{fee: bigint, activationFee: bigint}\> - Fee estimate in sun and the portion used for account activation

Throws: Error if no TronWeb provider is configured

quoteTransfer(options)

Estimates the TRC20 token transfer cost from current chain parameters, account resources, contract energy use, and bandwidth use.

Parameters:

• options (TransferOptions): Transfer options

Returns: Promise\<{fee: bigint}\> - Fee estimate in sun

Throws: Error if no TronWeb provider is configured

verify(message, signature)

Verifies a message signature using secp256k1.

Parameters:

• message (string): The original message
• signature (string): The signature to verify (hex string)

Returns: Promise\<boolean\> - True if signature is valid

Example:

const readOnlyAccount = new WalletAccountReadOnlyTron('T...', { provider: '...' })
const isValid = await readOnlyAccount.verify(message, signature)
console.log('Signature valid:', isValid)

getTransactionReceipt(hash)

Returns a native TRON receipt if it has been processed. This method is deprecated in favor of getTransaction(). The read-only account's getTransaction() and waitForTransaction() use the same ID validation, pending/confirmed/final, 90-second default timeout, confirmation depth, and native receipt semantics documented above.

Parameters:

• hash (string): The transaction hash

Returns: Promise\<TronTransactionReceipt | null\> - Transaction receipt or null

Throws: Error if no TronWeb provider is configured

Types

TronWalletConfig

interface TronWalletConfig {
  provider?: string | TronWeb | Array<string | TronWeb>; // RPC, TronWeb, or failover list
  retries?: number;                   // Additional failover attempts, default 3
  transferMaxFee?: number | bigint;   // Maximum TRC20 transfer fee in sun
  transactionMaxFee?: number | bigint; // Maximum sendTransaction/signTransaction fee in sun
}

TronTransaction

type TronTransaction = TronTrxTransfer | TronSmartContractCall | Transaction;

interface TronTrxTransfer {
  to: string;                         // Recipient Tron address
  value: number | bigint;             // Amount in sun (1 TRX = 1,000,000 sun)
}

interface TronSmartContractCall {
  contractAddress: string;            // Smart contract address to call
  functionSelector: string;           // Function selector, e.g. 'transfer(address,uint256)'
  parameters?: ContractFunctionParameter[];
  options?: TriggerSmartContractOptions;
}

type Transaction = import('tronweb').Types.Transaction;

ContractFunctionParameter and TriggerSmartContractOptions are TronWeb types used by transactionBuilder.triggerSmartContract(). Pre-built Transaction values are the unsigned transaction objects returned by TronWeb transaction-builder methods.

TransferOptions

interface TransferOptions {
  token: string;                      // TRC20 contract address
  recipient: string;                  // Recipient Tron address
  amount: number | bigint;            // Amount in token base units
}

TransactionResult

interface TransactionResult {
  hash: string;                       // Transaction hash
  fee: bigint;                        // Fee paid in sun
}

TronSignedTransaction

type TronSignedTransaction = import('tronweb').Types.SignedTransaction

The WDK package re-exports this TronWeb type under the exact name TronSignedTransaction.

TronActivationFee

interface TronActivationFee {
  activationFee: bigint;              // Portion of the fee used for account activation
}

TransferResult

interface TransferResult {
  hash: string;                       // Transaction hash
  fee: bigint;                        // Fee paid in sun
}

Constants

// Tron-specific constants
const BIP_44_TRON_DERIVATION_PATH_PREFIX: string = "m/44'/195'";
const BANDWIDTH_PRICE: bigint = 1_000n;

// Fee rate multipliers
const FEE_RATE_NORMAL_MULTIPLIER: bigint = 110n;
const FEE_RATE_FAST_MULTIPLIER: bigint = 200n;

Need Help?