getTokenAccountBalance

Returns the token balance of an SPL Token account.

Common use cases

Display SPL Token Balance in Wallet UI	Fetch token account balance with decimals for wallet portfolio display. Use uiAmountString field (not deprecated uiAmount) to show human-readable balance. Prefer "confirmed" commitment for real-time updates.
Validate Balance Before SPL Token Transfer	Check token account balance before initiating transfer to prevent insufficient funds errors. Compare balance with transfer amount plus rent-exempt minimum to ensure transaction success.
Query Liquidity Pool Reserve Balances	Fetch reserves from both token accounts in an LP pair to calculate price ratios. Call getTokenAccountBalance on pool's base and quote reserve accounts (not the LP token address itself).
Monitor Token Holdings for Trust Scoring	Validate minimum token holdings for governance voting or access gating. Use "finalized" commitment for authoritative balance checks to prevent gaming with unconfirmed transactions.
Track Balance Changes in Trading Bots	Monitor token account balance before and after swaps to calculate profit/loss. Combine with accountSubscribe WebSocket for real-time balance updates without polling overhead.

Parameters

pubkey (string, required)

Pubkey of Token account to query, as base-58 encoded string

config (object, optional)

Configuration object containing the following fields:

Fields:

• commitment (string): The commitment describes how finalized a block is at that point in time. See Configuring State Commitment.

Request

cURL

curl https://solana-mainnet.api.syndica.io/api-key/YOUR_API_KEY \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenAccountBalance",
  "params": [
    "7fUAJdStEuGbc3sM84cKRL6yYaaSstyLSU4ve5oovLS7",
    {
      "commitment": "finalized"
    }
  ]
}'

JavaScript

// Using fetch
const response = await fetch('https://solana-mainnet.api.syndica.io/api-key/YOUR_API_KEY', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenAccountBalance",
  "params": [
    "7fUAJdStEuGbc3sM84cKRL6yYaaSstyLSU4ve5oovLS7",
    {
      "commitment": "finalized"
    }
  ]
})
});
const data = await response.json();
console.log(data);

Python

import requests
import json

url = 'https://solana-mainnet.api.syndica.io/api-key/YOUR_API_KEY'
headers = {'Content-Type': 'application/json'}
data = {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenAccountBalance",
  "params": [
    "7fUAJdStEuGbc3sM84cKRL6yYaaSstyLSU4ve5oovLS7",
    {
      "commitment": "finalized"
    }
  ]
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())

Network Selection

Replace mainnet with devnet in the URL to query devnet instead.

Response

{
  "jsonrpc": "2.0",
  "result": {
    "context": { "slot": 1114 },
    "value": {
      "amount": "9864",
      "decimals": 2,
      "uiAmount": 98.64,
      "uiAmountString": "98.64"
    }
  },
  "id": 1
}

Response Fields

amount (string)

The raw balance without decimals, a string representation of u64

decimals (u8)

Number of base 10 digits to the right of the decimal place

uiAmount (number | null)

The balance, using mint-prescribed decimals DEPRECATED

uiAmountString (string)

The balance as a string, using mint-prescribed decimals

FAQ and Troubleshooting

Why do I get 'Invalid param: not a Token account' error?

You're passing a mint address, LP token address, or wrong account type. This method requires the SPL token account address (often an Associated Token Account/ATA), not the mint address. Use getAssociatedTokenAddress() to derive the correct ATA from wallet + mint.

Should I use uiAmount or uiAmountString from the response?

Always use uiAmountString. The uiAmount number field is deprecated and may lose precision for tokens with high decimal counts. uiAmountString preserves exact balance as a string.

What's the difference between this and getBalance?

getBalance returns SOL lamports for any account. getTokenAccountBalance returns SPL token amounts with proper decimal handling for token accounts only. Use this for fungible tokens, getBalance for native SOL.

Which commitment level should I use for wallet balance display?

Use "confirmed" for real-time wallet UIs (1-2 second latency, <5% reorg risk) or "finalized" for authoritative balances like withdrawals (8-32 seconds, 0% reorg risk). Avoid "processed" for user-facing balances.

How do I get reserves from a liquidity pool pair?

Don't pass the LP token address to getTokenAccountBalance. Instead, fetch the pool's metadata with getParsedAccountInfo, extract the base/quote reserve account addresses, then call getTokenAccountBalance on each reserve account.

Related Methods

getBalance
Returns SOL lamports for any account. Use for native SOL balance checks; getTokenAccountBalance is specialized for SPL tokens with decimal handling.

getAccountInfo
Returns full account data including balance, owner, and raw data. Use when you need to validate account type or access additional fields beyond just token balance.

getMultipleAccounts
Fetches multiple accounts in one RPC call. More efficient than repeated getTokenAccountBalance when checking 5+ token balances for a portfolio display.

accountSubscribe (WebSocket)
Subscribe to real-time token account balance updates via WebSocket. Use instead of polling getTokenAccountBalance when monitoring for incoming transfers or swap completions.

External Resources

• Solana Official Documentation
• Solana Cookbook: Account Balance - Official code examples showing balance fetching with modern SDK patterns, including lamports-to-SOL conversion and commitment level usage. Covers context for general balance operations.
• Solana RPC: Commitment Levels - Explains processed, confirmed, and finalized commitment levels and their consistency guarantees. Essential for choosing correct commitment parameter based on use case requirements.
• SPL Token Program Documentation - Comprehensive guide to SPL Token Program including token account structure, Associated Token Accounts (ATA), and mint/account relationship. Helps understand why getTokenAccountBalance requires account address not mint address.