getTokenAccountBalance

The getTokenAccountBalance method returns the token balance for a specific SPL Token account. This method is essential for displaying token holdings, validating balances before transactions, and tracking token amounts in wallets and applications.

SPL Tokens are Solana's standard for fungible and non-fungible tokens, similar to ERC-20 on Ethereum. Each token type requires separate accounts to hold balances, and this method queries the balance of a specific token account. Unlike native SOL balances (queried with getBalance), token balances are stored in specialized accounts managed by the SPL Token program. The method returns both the raw amount (in smallest units) and human-readable amounts with proper decimal formatting.

This method is crucial for wallets showing token portfolios, DEXes checking trading balances, NFT platforms verifying ownership (balance = 1 for NFTs), and any DeFi application managing token transfers. The returned data includes decimal information for proper display formatting, making it easy to show user-friendly amounts while maintaining precision for calculations.

Parameters

parameter	type	description
tokenAccountPubkey	string	Base-58 encoded public key of the token account to query
config	object	Optional configuration object
config.commitment	string	Level of commitment: 'processed', 'confirmed', or 'finalized' (default: 'finalized')

Return Object

field	type	description
context	object	RPC response context with slot information
context.slot	number	The slot at which this balance was retrieved
value	object	Token balance information object
value.amount	string	Raw token balance as a string (no decimals applied), representing the smallest unit
value.decimals	number	Number of decimal places for this token
value.uiAmount	number\|null	Token balance as a float with decimals applied (deprecated, may be null for large amounts)
value.uiAmountString	string	Token balance as a string with decimals applied, safe for all amounts

Request Example

Request

Response Example

Response

Tip: Always use uiAmountString for display rather than uiAmount, as it's safe for very large numbers that exceed JavaScript's number precision. The amount field is the raw balance before decimal adjustment. For a token with 6 decimals, amount "1500000000" = 1500 tokens.