Working with SPL Tokens

Tokens on Solana follow the SPL Token model, which keeps the definition of a token and the ownership of it in separate accounts. A mint account defines the token itself — its supply, its number of decimals, and its mint authority — while every holder owns a distinct token account that records how much of that mint they hold. So a wallet does not store balances inline; it points at one token account per mint it touches. Alongside the original SPL Token program there is now Token-2022, a second token program that adds optional features like transfer fees and confidential transfers. Token-2022 mints and accounts live under a different program id, so reads that should cover everything a wallet holds must query both programs.

Core Concepts

• Mint vs token account vs owner. The mint is the token's definition (supply, decimals). A token account holds a balance of one mint and is owned by a wallet (the owner pubkey). One wallet has many token accounts — one per mint it holds.
• One filter, exactly. getTokenAccountsByOwner requires exactly one filter: either a single mint (to find that wallet's account for one token) or a programId (to list every account under a token program). Passing both, or neither, is an error.
• Use jsonParsed. Requesting jsonParsed encoding returns human-readable fields like tokenAmount.uiAmountString instead of a raw byte blob you have to decode yourself.
• Raw amount is an integer. The on-chain amount is an integer in the mint's smallest unit. To get a human figure you must scale it by the mint's decimals — e.g. an amount of 1500000 on a 6-decimal mint is 1.5 tokens.
• Token-2022 is separate. Token-2022 accounts are owned by a different program id than the original SPL Token program, so you must run a second getTokenAccountsByOwner against the Token-2022 program id to see those holdings.

Reading Token Data

1import { Connection, PublicKey } from '@solana/web3.js';
2 
3const connection = new Connection('https://solana.therpc.io/YOUR_API_KEY', 'confirmed');
4 
5const owner = new PublicKey('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM');
6const TOKEN_PROGRAM = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
7 
8// All SPL token accounts of a wallet, with readable amounts
9const { value } = await connection.getParsedTokenAccountsByOwner(owner, {
10  programId: TOKEN_PROGRAM,
11});
12 
13for (const { pubkey, account } of value) {
14  const info = account.data.parsed.info;
15  console.log(pubkey.toBase58(), info.mint, info.tokenAmount.uiAmountString);
16}
17 
18// Total supply of a mint (USDC)
19const supply = await connection.getTokenSupply(
20  new PublicKey('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'),
21);
22console.log('Supply:', supply.value.uiAmountString);

Best Practices

• Filter with exactly one key. Always pass either a mint or a programId to getTokenAccountsByOwner — never both and never neither, or the call fails.
• Cover both programs. To list everything a wallet holds, query the original SPL Token program id and the Token-2022 program id; a single-program query silently misses any Token-2022 holdings.
• Prefer uiAmountString. Read tokenAmount.uiAmountString rather than the floating-point uiAmount. The string keeps full precision, while the float can round large balances.
• Balance reads target the token account. Pass the token account address to getTokenAccountBalance — not the owner wallet and not the mint. Those other addresses will not return the balance you expect.
• Cache mint decimals. A mint's decimals rarely change, so fetch them once and cache them instead of re-reading the mint on every balance you scale.

See also

• getTokenAccountsByOwner - List a wallet token accounts
• getTokenAccountBalance - Read one token account balance
• getTokenSupply - Total supply of a mint
• getTokenLargestAccounts - Largest holders of a mint