Glossary: Token Balances

What are Token Balances?

Token balances report the quantity of a specified token associated with an address or supported protocol position at a given block or time. Identify tokens by chain and contract address, and account for decimals, pricing time, and whether deposited positions are included.

Token Balances Explained

A token balance is simply the answer to "how much of this token does this wallet currently hold." It sounds basic, but balances change with every transfer, swap, deposit, or withdrawal, so getting an accurate, real time balance for a wallet means continuously tracking every relevant onchain event, not just checking a snapshot once.

For DeFi protocols, balances are foundational to almost everything else: TVL is just the sum of token balances locked in contracts, eligibility checks for an airdrop or gated feature often require a minimum balance, and a wallet's portfolio composition is built entirely from its balances across different tokens.

What Token Balances Means For

Examples

• A DeFi protocol checks a wallet's token balance to confirm it holds enough governance tokens to vote on a proposal.

• A growth team segments an airdrop into tiers based on wallets' historical balance of the DeFi protocol's token.

• A DeFi portfolio app displays a user's real time token balances across five different chains in one view.

• A token gated form verifies a wallet's NFT balance before allowing it to submit a response.

Interpreting token balance data

A balance is a snapshot tied to an address and a block or timestamp. Identify an asset by chain and contract address rather than ticker alone, since symbols can repeat; account for token decimals when converting raw units, and record the price source and timestamp when reporting a fiat value. For NFTs, token ID may also be needed. A wallet-held balance does not necessarily include assets deposited into a lending market or liquidity pool, so portfolio views must state whether they include protocol positions, staked assets, or receipt tokens.

Related terms

See Tokens, Wallet Profiles, Transaction History, and TVL (Total Value Locked).

FAQs

How is a token balance different from transaction history? Transaction history is the full log of transfers in and out of a wallet. Token balance is the current result of that history, what's left after every transfer is accounted for.

Why do token balances need to be tracked continuously rather than checked once? Because balances change with every transaction. A snapshot taken once becomes stale the moment a wallet sends or receives tokens.

How is TVL related to token balances? TVL is the sum of token balances held within a DeFi protocol's smart contracts, across all assets and pools.

Can token balances be used to verify eligibility? Yes, many gated features, governance votes, allowlists, airdrops, check a wallet's balance of a specific token or NFT before granting access.

Do token balances include staked or locked tokens? It depends on how balances are tracked. Some views show only liquid, wallet held balances, while a complete portfolio view also accounts for staked, locked, or deposited positions in DeFi protocols.