Handle Errors

Handle errors, manage fees, and clean up derived account keys in gasless TON wallets.

This guide covers how to handle gasless transfer errors and handle unsupported method errors, plus best practices for fee management and derived key cleanup.

Handle Gasless Transfer Errors

Gasless transfers can fail for reasons specific to the paymaster model. Wrap calls to account.transfer() in try/catch blocks:

Gasless Transfer Error Handling

try {
  const result = await account.transfer({
    token: 'EQ...',
    recipient: 'EQ...',
    amount: 1000000000
  })
  console.log('Signed transfer body hash:', result.hash)
} catch (error) {
  if (error.message.includes('insufficient jetton balance')) {
    console.error('Please add more Jetton tokens to your wallet')
  } else if (error.message.includes('insufficient paymaster balance')) {
    console.error('Please add more paymaster tokens for gas fees')
  } else if (error.message.includes('invalid address')) {
    console.error('The recipient address is invalid')
  } else if (error.message === 'The transfer operation exceeds the transfer max fee.') {
    console.error('The transfer fee exceeds your configured maximum')
  } else {
    console.error('Transfer failed:', error.message)
  }
}

Handle Unsupported Method Errors

The gasless module supports only paymaster-funded Jetton transfers. account.sendTransaction(), account.quoteSendTransaction(), and account.signTransaction() reject or throw when called. Use account.transfer() instead, and guard any code path that might reach these methods:

Unsupported Method Handling

try {
  await account.sendTransaction({
    to: 'EQ...',
    value: 1000000000
  })
} catch (error) {
  // "Method 'sendTransaction(tx)' not supported on ton gasless."
  console.error('Use account.transfer() for gasless Jetton transfers:', error.message)
}

Set transferMaxFee when creating the wallet to prevent gasless transfers from exceeding a maximum cost. Fee caps reject estimates greater than the configured limit, so an estimate equal to the cap is allowed. Native sendTransaction(), quoteSendTransaction(), and signTransaction() are unsupported on this module, so transactionMaxFee does not cap gasless transfers. You can retrieve mainnet TON API rates using wallet.getFeeRates(). Through 1.0.0-beta.8, this method does not follow configured testnet clients and returns the same calculated value for normal and fast:

Fee Management

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

Dispose Derived Account Keys

Call dispose() on accounts and wallet managers to clear cached accounts' derived private keys when they are no longer needed:

Memory Cleanup

account.dispose()

wallet.dispose()

Call dispose() in a finally block or cleanup handler so derived account keys are cleared even if an error occurs. In the current beta, wallet.dispose() does not zero or unset wallet.seed; manage the seed lifecycle separately and release all manager references when finished.

Handle Errors

Handle Gasless Transfer Errors

Handle Unsupported Method Errors

Best Practices

Manage Fee Limits

Dispose Derived Account Keys

On this page