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 | bigint, optional): Shared config field; the current runtime does not use it as a default transfer cap
  • transactionMaxFee (number | bigint, optional): Shared config field; native transaction methods remain unsupported, so it has no runtime effect

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'
})

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: bigint, fast: bigint}\> - 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 | bigint): Amount in token base units
• config (object, optional): Per-call transfer configuration
  • transferMaxFee (number | bigint, optional): Reject when the quoted total fee is greater than this token-base-unit cap. A fee equal to the cap is allowed.

Returns: Promise\<{hash: string, fee: bigint, activationFee: bigint}\> - Object containing the GasFree transfer ID, total fee paid in token base units, and the activation-fee portion. activationFee is 0n when no account activation fee applies.

Example:

const result = await account.transfer({
  token: 'T...',      // TRC20 contract address
  recipient: 'T...',  // Recipient's address
  amount: 1000000n    // Amount in token base units
}, {
  transferMaxFee: 5000n
})
console.log('GasFree transfer ID:', result.hash)
console.log('Fee paid:', result.fee, 'token base units')
console.log('Activation fee:', result.activationFee, '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, activationFee: bigint}\> - Estimated total fee in token base units, plus the activation-fee portion. activationFee is 0n when no account activation fee applies.

Example:

const quote = await account.quoteTransfer({
  token: 'T...',
  recipient: 'T...',
  amount: 1000000
})
console.log('Estimated fee:', quote.fee, 'token base units')
console.log('Activation fee:', quote.activationFee, '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)

getTransaction(hash)

Accepts the GasFree transfer ID returned by transfer(), resolves it to the provider's on-chain TRON transaction ID, and returns TRON pending, confirmed, or solidified final status. The normalized receipt keeps the GasFree transfer ID in its top-level hash; the native chain transaction remains available through the raw receipt, including its provider transaction ID.

Each lookup resolves the GasFree account address, queries the GasFree transfer, and then calls the TRON provider. It can therefore fail at either provider boundary.

Throws: NoSuchElementError when a successful GasFree response has no on-chain transaction ID. Non-success HTTP or API responses from the GasFree provider throw their provider error directly.

const result = await account.transfer({
  token: 'T...',
  recipient: 'T...',
  amount: 1000000n
})
const transaction = await account.getTransaction(result.hash)

console.log(transaction.hash)        // GasFree transfer ID
console.log(transaction.receipt?.id) // On-chain TRON transaction ID when included

waitForTransaction(hash, options?)

Polls by GasFree transfer ID until the requested TRON finality is reached. Defaults are target: 'confirmed', interval: 4000, timeout: 120000, and maxPollErrors: 3. A successful provider response without an on-chain hash is retried, but a GasFree HTTP/API error is not converted to not-found and can reject the wait immediately.

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

getTransactionReceipt(hash)

Resolves a GasFree transfer ID and returns its native TRON receipt, or null before an on-chain hash or receipt is available. This method is deprecated; use getTransaction() and its receipt field instead.

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, activationFee: bigint}\> - Estimated total fee in token base units, plus the activation-fee portion. activationFee is 0n when no account activation fee applies.

Example:

const quote = await readOnlyAccount.quoteTransfer({
  token: 'T...',
  recipient: 'T...',
  amount: 1000000
})
console.log('Estimated fee:', quote.fee, 'token base units')
console.log('Activation fee:', quote.activationFee, '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

The read-only account's getTransaction(), waitForTransaction(), and deprecated getTransactionReceipt() use the same GasFree transfer-ID mapping, TRON finality, 120-second default wait, raw receipt, and provider-error semantics documented above.

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 | bigint;
}

Transfer Results

The GasFree package re-exports TransferResult and TronActivationFee from @tetherto/wdk-wallet-tron. GasFree transfer and quote methods return intersections of those types:

import type {
  TransferResult,
  TronActivationFee
} from '@tetherto/wdk-wallet-tron-gasfree'

type TronGasfreeTransferResult = TransferResult & TronActivationFee
type TronGasfreeTransferQuote = Omit<TransferResult, 'hash'> & TronActivationFee

TransferResult supplies hash: string and fee: bigint. TronActivationFee supplies the activation-fee portion separately:

interface TronActivationFee {
  activationFee: bigint;
}

FeeRates

Fee rate information for transactions.

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

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

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;

  /**
   * Shared wallet config field for native transaction methods.
   * The GasFree module does not support quoteSendTransaction(),
   * signTransaction(), or sendTransaction(), so this field has no
   * runtime effect in the current release.
   * @optional
   */
  transactionMaxFee?: number | bigint;
}

The current runtime also does not use constructor-level transferMaxFee as a default. Enforce a GasFree transfer cap with the second argument to account.transfer().

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?