Transfer TRC20 Tokens

This guide explains how to transfer TRC20 tokens gas-free, override the fee limit, estimate transfer fees, and validate inputs before executing.

Transfer Tokens (Gas-Free)

You can send TRC20 tokens gas-free using account.transfer(). The gas-free service handles the fee payment:

Gas-Free TRC20 Transfer

const transferResult = await account.transfer({
  token: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', // USDT
  recipient: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH',
  amount: 1000000 // Amount in TRC20's base units
})
console.log('Transfer hash:', transferResult.hash)
console.log('Transfer fee:', transferResult.fee, 'token units')

The returned fee includes the GasFree transfer fee and, when the GasFree account is not active yet, the token activation fee returned by the provider.

Override Fee Limit

You can set a maximum fee for a specific transfer by passing a second configuration object specifying a transferMaxFee to account.transfer():

Transfer with Fee Limit

const result = await account.transfer({
  token: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', // USDT
  recipient: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH',
  amount: 1000000
}, {
  transferMaxFee: 1000 // Maximum fee allowed in token units
})
console.log('Transfer hash:', result.hash)
console.log('Transfer fee:', result.fee, 'token units')

Estimate Transfer Fees

You can get a fee estimate before executing the transfer using account.quoteTransfer():

Quote Gas-Free Transfer

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

If the GasFree account is inactive, the quote includes the token's activation fee in addition to the transfer fee.

Transfer with Validation

Validate addresses and check balances before transferring:

Use account.getTokenBalance() to verify sufficient funds.
Use account.quoteTransfer() to confirm fees.
Execute the transfer with account.transfer():

Validated Gas-Free Transfer

async function transferWithValidation(account, tokenAddress, recipient, amount) {
  if (!tokenAddress.startsWith('T') || tokenAddress.length !== 34) {
    throw new Error('Invalid TRC20 contract address')
  }

  if (!recipient.startsWith('T') || recipient.length !== 34) {
    throw new Error('Invalid recipient address')
  }

  const balance = await account.getTokenBalance(tokenAddress)
  if (balance < amount) {
    throw new Error('Insufficient TRC20 token balance')
  }

  const quote = await account.quoteTransfer({
    token: tokenAddress,
    recipient,
    amount
  })
  console.log('Transfer fee estimate:', quote.fee, 'token units')

  const result = await account.transfer({
    token: tokenAddress,
    recipient,
    amount
  })
  console.log('Transfer completed:', result.hash)
  console.log('Fee paid:', result.fee, 'token units')

  return result
}

Next Steps

Learn how to sign and verify messages with your gas-free Tron account.