Transfer ERC-20 Tokens

This guide explains how to transfer ERC-20 tokens, estimate fees, override gas and fees, and validate inputs before executing.

Transfer Tokens

Use account.transfer() to send ERC-20 tokens to a recipient address.

const USDT_ETHEREUM = '0xdAC17F958D2ee523a2206206994597C13D831ec7'

const transferResult = await account.transfer({
  token: USDT_ETHEREUM,
  recipient: '0x742d35cc6634c0532925a3b8d4c9db96c4b4d8b6',
  amount: 1000000n // 1 USDt on Ethereum (6 decimals)
})
console.log('Transfer hash:', transferResult.hash)
console.log('Transfer fee:', transferResult.fee, 'wei')

Estimate Transfer Fees

Use account.quoteTransfer() to get a fee estimate before executing the transfer.

Quote Token Transfer

const transferQuote = await account.quoteTransfer({
  token: USDT_ETHEREUM,
  recipient: '0x742d35cc6634c0532925a3b8d4c9db96c4b4d8b6',
  amount: 1000000n
})
console.log('Transfer fee estimate:', transferQuote.fee, 'wei')

Override Gas and Fees (optional)

Starting in beta.20, pass gas overrides directly in the options for quoteTransfer() and transfer(). Use EIP-1559 fee fields or legacy gasPrice; do not combine them.

Quote a Transfer with Explicit Fee Rates

const transfer = {
  token: USDT_ETHEREUM,
  recipient,
  amount: 1000000n,
  maxFeePerGas: 30000000000n,
  maxPriorityFeePerGas: 2000000000n
}

const quote = await account.quoteTransfer(transfer)
console.log('Quoted execution-gas fee:', quote.fee, 'wei')

After reviewing the recipient, amount, and fee settings, pass the same options to account.transfer(transfer). The quote does not lock unspecified gas fields; transfer() quotes again and checks configured transferMaxFee and transactionMaxFee. An explicit gasLimit is also accepted, but quoting still simulates the transfer.

approve() accepts the same four gas override fields directly in its options. Approval amounts remain in the token's base units; the execution-gas fee is in wei.

Transfer with Validation

You can use transferTokenWithValidation() to validate addresses and check balances before transferring to catch errors early.

1. Validate Addresses

Address Validation

if (!tokenAddress.startsWith('0x') || tokenAddress.length !== 42) {
  throw new Error('Invalid token address')
}

if (!recipient.startsWith('0x') || recipient.length !== 42) {
  throw new Error('Invalid recipient address')
}

2. Check Balances

Use account.getTokenBalance() and account.getBalance() to verify sufficient funds:

Balance Check

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

const nativeBalance = await account.getBalance()
if (nativeBalance === 0n) {
  throw new Error('Need ETH for gas fees')
}

3. Quote and Execute Transfer

Use account.quoteTransfer() to estimate fees, then account.transfer() to execute:

Quote and Execute

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

const result = await account.transfer({
  token: tokenAddress,
  recipient,
  amount
})
console.log('Transfer completed:', result.hash)
console.log('Quoted execution-gas fee:', result.fee, 'wei')

Next Steps

Learn how to sign and verify messages with your EVM account.

Transfer ERC-20 Tokens

On this page