Get Token Account Balance

The getTokenAccountBalance function retrieves the balance of tokens in a token account. You can either provide a token account address directly, or provide a wallet address and a mint address to derive the token account address.

Usage

const balance = await connection.getTokenAccountBalance({
  tokenAccount, // Optional: Direct token account address to check
  wallet, // Optional: Wallet address (required if tokenAccount not provided)
  mint, // Optional: Token mint address (required if tokenAccount not provided)
  useTokenExtensions, // Optional: Use Token-2022 program instead of Token program
});

Parameters

• params: Object - Parameters for getting token balance
  • tokenAccount: Address (optional) - Direct token account address to check balance for
  • wallet: Address (optional) - Wallet address (required if tokenAccount not provided)
  • mint: Address (optional) - Token mint address (required if tokenAccount not provided)
  • useTokenExtensions: boolean (optional) - Use Token-2022 program instead of Token program (default: false)

Returns

Returns a Promise resolving to an object containing:

• amount: Raw token amount as a BigInt (in base units)
• decimals: Number of decimal places for the token
• uiAmount: Formatted amount with decimals
• uiAmountString: String representation of the UI amount

Examples

Get a token balance using wallet and mint addresses:

// Get USDC balance
const balance = await connection.getTokenAccountBalance({
  wallet: "GkFTrgp8FcCgkCZeKreKKVHLyzGV6eqBpDHxRzg1brRn", // wallet or PDA address
  mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC mint
});
 
console.log(`Balance: ${balance.uiAmount} ${balance.symbol}`);

Get a token balance using direct token account address:

const balance = await connection.getTokenAccountBalance({
  tokenAccount: "4MD31b2GFAWVDYQT8KG7E5GcZiFyy4MpDUt4BcyEdJRP",
});

Get a Token-2022 token balance:

const balance = await connection.getTokenAccountBalance({
  wallet: "GkFTrgp8FcCgkCZeKreKKVHLyzGV6eqBpDHxRzg1brRn",
  mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  useTokenExtensions: true,
});

Error Handling

The function will throw an error if:

• Neither tokenAccount nor both wallet and mint are provided
• The token account doesn’t exist
• There’s an error retrieving the balance