API Reference

Table of Contents

WalletManagerTronGasfree

The main class for managing gas-free Tron wallets.

Constructor

new WalletManagerTronGasfree(seed, config)

Parameters:

• seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes
• config (object): Configuration object
  • chainId (number): The blockchain's id
  • provider (string | TronWeb): Tron RPC endpoint URL or TronWeb instance
  • gasFreeProvider (string): Gas-free service endpoint
  • serviceProvider (string): Service provider Tron address
  • verifyingContract (string): Gas-free verifying contract address
  • gasFreeApiKey (string, optional): API key for signed GasFree provider requests
  • gasFreeApiSecret (string, optional): API secret for signed GasFree provider requests. Provide together with gasFreeApiKey.
  • transferMaxFee (number, optional): Maximum fee for transfer operations

Example:

const wallet = new WalletManagerTronGasfree(seedPhrase, {
  chainId: 728126428,
  provider: 'https://api.trongrid.io',
  gasFreeProvider: 'https://gasfree.provider.url',
  serviceProvider: 'T...',
  verifyingContract: 'T...',
  gasFreeApiKey: 'your-api-key', // Optional: provide with gasFreeApiSecret
  gasFreeApiSecret: 'your-api-secret',
  transferMaxFee: 10000000 // Optional
})

Methods

getAccount(index)

Returns a gas-free wallet account at the specified index.

Parameters:

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

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

Example:

const account = await wallet.getAccount(0)

getAccountByPath(path)

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

Parameters:

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

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

Example:

const account = await wallet.getAccountByPath("0'/0/1")

getFeeRates()

Returns current fee rates for normal and fast transactions.

Returns: Promise\<{normal: number, fast: number}\> - Object containing fee rates in sun

• normal: Fee rate for normal priority transactions
• fast: Fee rate for high priority transactions

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. This method should be called when you're done using the wallet to ensure sensitive data is removed.

Example:

wallet.dispose()

WalletAccountTronGasfree

Individual gas-free Tron wallet account implementation.

Constructor

new WalletAccountTronGasfree(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 (object): Same configuration object as WalletManagerTronGasfree

Methods

getAddress()

Returns the account's gas-free Tron address.

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

Example:

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

getBalance()

Returns the native TRX balance in sun units.

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

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

Example:

const tokenBalance = await account.getTokenBalance('T...')
console.log('Token balance:', tokenBalance)

transfer(options)

Transfers TRC20 tokens to another address using the gas-free service.

Parameters:

• options (TransferOptions): Transfer options
  • token (string): TRC20 contract address
  • recipient (string): Recipient's Tron address
  • amount (number): Amount in token base units

Returns: Promise\<{hash: string, fee: bigint}\> - Object containing transaction hash and fee paid in token base units. The returned fee includes the estimated transfer fee plus any activation fee returned by the GasFree service.

Example:

const result = await account.transfer({
  token: 'T...',      // TRC20 contract address
  recipient: 'T...',  // Recipient's address
  amount: 1000000     // Amount in token base units
})
console.log('Transaction hash:', result.hash)
console.log('Fee paid:', result.fee, 'token base units')

quoteTransfer(options)

Estimates the fee for a TRC20 token transfer.

Parameters:

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

Returns: Promise\<{fee: bigint}\> - Estimated fee in token base units. The estimate includes the token's transfer fee and, when the GasFree account is inactive, the token activation fee.

Example:

const quote = await account.quoteTransfer({
  token: 'T...',
  recipient: 'T...',
  amount: 1000000
})
console.log('Estimated fee:', quote.fee, 'token base units')

sign(message)

Signs a message using the account's private key.

Parameters:

• message (string): The message to sign

Returns: Promise\<string\> - The message signature

Example:

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

signTransaction(tx)

Transaction signing is not supported by the Tron GasFree module. This method is present for IWalletAccount compatibility and always throws "Method 'signTransaction(tx)' not supported on tron gasfree.".

Parameters:

• tx (TronTransaction): The transaction object

Returns: Promise\<never\> - Never resolves successfully.

sendTransaction(tx)

Native Tron transaction sending is not supported by the Tron GasFree module. Use transfer(options) for gas-free TRC20 transfers, or use the base Tron wallet module when you need native TRX transactions.

Parameters:

• tx (TronTransaction): The transaction object

Returns: Promise\<TransactionResult\> - The method always throws "Method 'sendTransaction(tx)' not supported on tron gasfree.".

quoteSendTransaction(tx)

Native Tron transaction fee quotes are not supported by the Tron GasFree module.

Parameters:

• tx (TronTransaction): The transaction object

Returns: Promise\<Omit\<TransactionResult, 'hash'\>\> - The method always throws "Method 'quoteSendTransaction(tx)' not supported on tron gasfree.".

verify(message, signature)

Verifies a message signature.

Parameters:

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

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

Example:

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

dispose()

Disposes the wallet account, clearing private keys from memory.

Example:

account.dispose()

WalletAccountReadOnlyTronGasfree

Read-only gas-free Tron wallet account.

Constructor

new WalletAccountReadOnlyTronGasfree(address, config)

Parameters:

• address (string): The account's Tron address
• config (object): Configuration object
  • chainId (number): The blockchain's id
  • provider (string | TronWeb): Tron RPC endpoint URL or TronWeb instance
  • gasFreeProvider (string): Gas-free service endpoint
  • serviceProvider (string): Service provider Tron address
  • verifyingContract (string): Gas-free verifying contract address
  • gasFreeApiKey (string, optional): API key for signed GasFree provider requests
  • gasFreeApiSecret (string, optional): API secret for signed GasFree provider requests. Provide together with gasFreeApiKey.

Methods

getAddress()

Returns the account's gas-free Tron address.

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

Example:

const address = await readOnlyAccount.getAddress()
console.log('Account address:', address)

getBalance()

Returns the native TRX balance in sun units.

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

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 (e.g., 'T...')

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

Example:

const tokenBalance = await readOnlyAccount.getTokenBalance('T...')
console.log('Token balance:', tokenBalance)

quoteTransfer(options)

Estimates the fee for a TRC20 token transfer without requiring private keys.

Parameters:

• options (TransferOptions): Transfer options
  • token (string): TRC20 contract address
  • recipient (string): Recipient's Tron address
  • amount (number): Amount in token base units

Returns: Promise\<{fee: bigint}\> - Estimated fee in token base units. The estimate includes the token's transfer fee and, when the GasFree account is inactive, the token activation fee.

Example:

const quote = await readOnlyAccount.quoteTransfer({
  token: 'T...',
  recipient: 'T...',
  amount: 1000000
})
console.log('Estimated fee:', quote.fee, 'token base units')

quoteSendTransaction(tx)

Native Tron transaction fee quotes are not supported by the Tron GasFree module.

Parameters:

• tx (TronTransaction): The transaction object

Returns: Promise\<Omit\<TransactionResult, 'hash'\>\> - The method always throws "Method 'quoteSendTransaction(tx)' not supported on tron gasfree.".

verify(message, signature)

Verifies a message signature.

Parameters:

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

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

Example:

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

Types

TransferOptions

Configuration options for token transfers.

interface TransferOptions {
  /**
   * The TRC20 token contract address
   * @example 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t' // USDT contract
   */
  token: string;

  /**
   * The recipient's Tron address
   * @example 'TJYeasTPa6gpEEfQa7s9CqqqgvYh6JtpAR'
   */
  recipient: string;

  /**
   * Amount to transfer in token base units
   * @example 1000000 // 1 USDT (6 decimals)
   */
  amount: number;
}

TransferResult

Result object returned by transfer operations.

interface TransferResult {
  /**
   * The transaction hash
   * @example '0x123...'
   */
  hash: string;

  /**
   * Fee paid in token base units
   * @example 1000 // Fee in token base units
   */
  fee: bigint;
}

FeeRates

Fee rate information for transactions.

interface FeeRates {
  /**
   * Fee rate for normal priority transactions (in sun)
   * @example 1000
   */
  normal: number;

  /**
   * Fee rate for high priority transactions (in sun)
   * @example 2000
   */
  fast: number;
}

TronGasfreeAssetInfo

Asset metadata returned by the GasFree account service.

interface TronGasfreeAssetInfo {
  /**
   * Token smart contract address
   * @example 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'
   */
  tokenAddress: string;

  /**
   * Token symbol
   * @example 'USDT'
   */
  tokenSymbol: string;

  /**
   * Fee to activate the GasFree account for this token
   */
  activateFee: number;

  /**
   * Fee for transferring this token
   */
  transferFee: number;

  /**
   * Token decimals
   */
  decimal: number;

  /**
   * Whether the token is frozen by the GasFree service
   */
  frozen: number;
}

TronGasfreeAccountInfo

Account metadata returned by the GasFree account service.

interface TronGasfreeAccountInfo {
  /**
   * Owner account address
   */
  accountAddress: string;

  /**
   * GasFree contract address for the account
   */
  gasFreeAddress: string;

  /**
   * Whether the GasFree account is active
   */
  active: boolean;

  /**
   * Account nonce used by GasFree transfers
   */
  nonce: number;

  /**
   * Whether the account can submit GasFree transactions
   */
  allowSubmit: boolean;

  /**
   * Supported assets and their fee metadata
   */
  assets: TronGasfreeAssetInfo[];
}

TronGasfreeWalletConfig

Configuration options for wallet initialization.

interface TronGasfreeWalletConfig {
  /**
   * The blockchain's ID
   * @example 728126428 // Tron Mainnet
   */
  chainId: number;

  /**
   * Tron RPC endpoint URL or TronWeb instance
   * @example 'https://api.trongrid.io'
   */
  provider: string | TronWeb;

  /**
   * Gas-free service endpoint
   * @example 'https://gasfree.trongrid.io'
   */
  gasFreeProvider: string;

  /**
   * API key for signed GasFree provider requests
   * @optional
   */
  gasFreeApiKey?: string;

  /**
   * API secret for signed GasFree provider requests.
   * Provide together with gasFreeApiKey.
   * @optional
   */
  gasFreeApiSecret?: string;

  /**
   * Service provider Tron address
   * @example 'T...'
   */
  serviceProvider: string;

  /**
   * Gas-free verifying contract address
   * @example 'T...'
   */
  verifyingContract: string;

  /**
   * Maximum fee for transfer operations (in token base units)
   * @optional
   * @example 10000000
   */
  transferMaxFee?: number | bigint;
}

KeyPair

Account key pair information.

interface KeyPair {
  /**
   * Public key as buffer
   */
  publicKey: Buffer;

  /**
   * Private key as buffer (sensitive data)
   */
  privateKey: Buffer;
}

The returned byte arrays are a read-only view of the wallet account's internal key material. Do not mutate publicKey or privateKey; external changes can alter the internal representation.

Need Help?