> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codex.io/llms.txt
> Use this file to discover all available pages before exploring further.
# balances
> Returns list of token balances that a wallet has.
## GraphQL
```
type Query {
# Requires a Growth or Enterprise plan.
balances(
input: BalancesInput!
): BalancesResponse!
}
type SocialLinks {
bitcointalk: String
blog: String
coingecko: String
coinmarketcap: String
discord: String
email: String
facebook: String
github: String
instagram: String
linkedin: String
reddit: String
slack: String
telegram: String
twitch: String
twitter: String
website: String
wechat: String
whitepaper: String
youtube: String
}
type TokenInfo {
id: String!
address: String!
circulatingSupply: String
cmcId: Int
gridAssetId: String
bluechipRating: String
isScam: Boolean
name: String
networkId: Int!
symbol: String!
totalSupply: String
imageThumbHash: String
imageThumbUrl: String
imageSmallUrl: String
imageLargeUrl: String
imageBannerUrl: String
videoExternalUrl: String
description: String
}
type OrganizationUrl {
url: String!
type: String
}
type OrganizationSocial {
url: String!
type: String
}
type AssetDeployment {
id: String!
networkId: Int!
address: String!
standard: String
assetId: String!
rootId: String!
token: EnhancedToken
}
type Asset {
id: String!
name: String
description: String
ticker: String
type: String
status: String
icon: String
rootId: String!
assetDeployments: [AssetDeployment!]!
}
type Organization {
name: String!
foundingDate: String
descriptionShort: String
descriptionLong: String
tagLine: String
type: String
sector: String
urls: [OrganizationUrl!]!
socials: [OrganizationSocial!]!
logo: String
icon: String
header: String
rootId: String!
assets: [Asset!]!
}
type ExplorerTokenData {
id: String!
blueCheckmark: Boolean
description: String
divisor: String
tokenPriceUSD: String
tokenType: String
}
type Exchange {
id: String!
address: String!
color: String
name: String
exchangeVersion: String
iconUrl: String
networkId: Int!
tradeUrl: String
}
enum WalletCategory {
NORMIE
TOKEN_CREATOR
EXCHANGE
DEFI_EXCHANGE
PAIR
PAIR_TOKEN_HOLDER
POOL_AUTHORITY
STAKING_VAULT
NOTORIOUS
}
type WalletFunding {
fundedByAddress: String!
fundedByLabel: String
fundedAt: Int!
tokenAddress: String!
networkId: Int!
amount: String!
transactionHash: String!
}
type WalletPolymarketProfile {
proxyWallet: String!
xUsername: String
displayName: String
pseudonym: String
profileImageUrl: String
verifiedBadge: Boolean
displayUsernamePublic: Boolean
fetchedAt: Int!
}
type Wallet {
address: String!
category: WalletCategory
firstSeenTimestamp: Int
firstFunding: WalletFunding
identityLabels: [String!]
avatarUrl: String
displayName: String
twitterId: String
twitterUsername: String
telegramId: String
telegramUsername: String
website: String
discordId: String
discordUsername: String
githubId: String
githubUsername: String
farcasterId: String
farcasterUsername: String
description: String
ethosScore: Int
ethosLevel: String
ethosVerified: Boolean
identitySource: String
identityUpdatedAt: Int
polymarket: WalletPolymarketProfile
tokensCreatedCount: Int
tokensMigratedCount: Int
}
type LaunchpadData {
launchpadName: String
graduationPercent: Float
poolAddress: String
completedAt: Int
completed: Boolean
completedSlot: Int
migratedSlot: Int
migratedAt: Int
migrated: Boolean
migratedPoolAddress: String
launchpadProtocol: String
launchpadIconUrl: String
isCashbackEnabled: Boolean
category: String
}
type TokenExtrema {
id: String!
address: String!
networkId: Int!
athPrice: String!
athPriceTimestamp: Int!
atlPrice: String!
atlPriceTimestamp: Int!
athFdv: String!
athFdvTimestamp: Int!
atlFdv: String!
atlFdvTimestamp: Int!
athCircMc: String!
athCircMcTimestamp: Int!
atlCircMc: String!
atlCircMcTimestamp: Int!
}
type CoinCommunity {
id: String!
createdAt: Int!
postCount: Int!
memberCount: Int!
likeCount: Int!
lastPostAt: Int
}
type Token2022ScaledUiAmountConfig {
authority: String
multiplier: Float!
newMultiplierEffectiveTimestamp: String
newMultiplier: Float
}
type Token2022Extensions {
scaledUiAmountConfig: Token2022ScaledUiAmountConfig
}
type B20Extensions {
multiplier: String
multiplierObservedAt: String
pausedTransfer: Boolean
pausedMint: Boolean
pausedBurn: Boolean
supplyCap: String
}
type TokenExtensions {
token2022: Token2022Extensions
b20: B20Extensions
}
type Erc7572CustomInfo {
type: String!
featuredImage: String
collaborators: [String!]
}
enum CategoryType {
CANONICAL
NARRATIVE
}
enum CategoryStatus {
DRAFT
ACTIVE
ARCHIVED
}
type Category {
id: String!
name: String!
shortName: String
slug: String!
description: String
type: CategoryType!
status: CategoryStatus!
parentId: String
memberCount: Int
}
type EnhancedToken {
id: String!
address: String!
cmcId: Int
decimals: Int!
isScam: Boolean
name: String
networkId: Int!
symbol: String
socialLinks: SocialLinks
info: TokenInfo
gridAssetId: String
bluechipRating: String
organization: Organization
asset: Asset
exchanges: [Exchange!]
creatorAddress: String
creator: Wallet
createBlockNumber: Int
createTransactionHash: String
createdAt: Int
mintable: String
freezable: String
isFreezableValid: Boolean
isMintableValid: Boolean
launchpad: LaunchpadData
top10HoldersPercent: Float
profanity: Boolean
extrema: TokenExtrema
coinCommunity: CoinCommunity
extensions: TokenExtensions
tokenStandardCustomData: Erc7572CustomInfo
categories: [Category!]
}
type Balance {
walletId: String!
tokenId: String!
address: String!
networkId: Int!
tokenAddress: String!
balance: String!
shiftedBalance: Float!
uiBalance: Float
balanceUsd: String
tokenPriceUsd: String
firstHeldTimestamp: Int
updatedAtBlock: Int
token: EnhancedToken
liquidityUsd: String
tokenLastTradedTimestamp: Int
wallet: Wallet
}
type BalancesResponse {
items: [Balance!]!
cursor: String
}
enum BalancesSortAttribute {
BALANCE
USD_VALUE
}
enum RankingDirection {
ASC
DESC
}
enum UiAmountMode {
RAW
SCALED
}
input BalancesInput {
walletAddress: String
networks: [Int!]
tokens: [String!]
includeNative: Boolean
limit: Int
cursor: String
removeScams: Boolean
sortBy: BalancesSortAttribute
sortDirection: RankingDirection
uiAmountMode: UiAmountMode
}
```
### Example
Test this query in the Explorer →
```graphql theme={null}
{
balances(
input: {walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", networks: [1], removeScams: true, limit: 10}
) {
items {
tokenId
shiftedBalance
balanceUsd
tokenPriceUsd
token {
name
symbol
info {
imageSmallUrl
}
}
}
cursor
}
}
```
For EVM wallets, native balances are only available on networks with traces enabled. \
\
EVM networks with traces enabled:
*Ethereum*\
*BNB Chain (BSC)*\
*Unichain*\
*Polygon*\
*Base*\
*Story*\
*Meld*\
*Yominet*\
*Ham*\
*Berachain*\
*Avalanche*\
*Sanko*\
*Arbitrum*\
*Superposition*\
*Optimism*\
*Abstract*\
*Monad*\
\
*Balances are also unavailable on Sui (Network 101).*
### Usage Guidelines
* Use `walletAddress` with the wallet address (ENS names are not supported)
* Specify `networks` array to filter balances to specific chains (e.g., `[1]` for Ethereum)
* Use `tokens` array to request specific token balances (max 200 tokens)
* Use `removeScams: true` to filter out likely scam and dust tokens. This removes tokens we've manually flagged (`isScam: true`), and for unlabeled tokens it applies a lightweight heuristic that drops ones with no recent trading activity and negligible liquidity. See the troubleshooting note below for the details and caveats.
* Read `liquidityUsd` for the token's route-backed liquidity in USD — the real liquidity supporting its price, summed across the token's pairs with valid routing liquidity (null when not yet computed). This replaces the older reserves-times-price measure, so it reflects liquidity a holder could actually trade against. Combine it with `tokenLastTradedTimestamp` to value a portfolio accurately: discount or exclude holdings with negligible liquidity or no recent trades so illiquid or dead tokens don't inflate a wallet's total.
* Use `updatedAtBlock` to see the block at which a balance was last updated (null for native balances or when the block is unknown), for balance-freshness provenance.
* Use the `cursor` parameter for pagination through large token holdings
### Troubleshooting Tips
Native balances (ETH, BNB, etc.) are only available on EVM networks with traces enabled. Check the list above to see if your network is supported. For Solana, native SOL balances are available.
`balanceUsd` may be null if we don't have price data for that token. This can happen with very new or low-liquidity tokens. The raw `balance` and `shiftedBalance` fields will still be available.
`balanceUsd` values each holding at the current token price, but a price alone can make illiquid or dead tokens look valuable. Use `liquidityUsd` — the token's route-backed liquidity in USD, i.e. the real liquidity supporting its price across pairs with valid routing — together with `tokenLastTradedTimestamp` to filter or discount holdings that couldn't actually be sold at their quoted price. A common approach is to drop or down-weight tokens below a liquidity threshold, or with no trades in the last day, before summing `balanceUsd` into a portfolio total, so a handful of worthless tokens don't make a wallet look far richer than it is.
Use the `tokens` parameter with an array of token IDs (`address:networkId`) or addresses. When using addresses only, you must also provide the `networks` parameter. Max 200 tokens per request.
No, `balances` queries a single wallet. To get balances for multiple wallets, make separate requests for each wallet address.
Wallets accumulate scam and junk tokens over time, often as unsolicited airdrops. Setting `removeScams: true` may filter some of these out, but it will not catch everything. It does two things. First, it removes tokens we've manually flagged as a scam (`isScam: true`), which we do sparingly. Second, for tokens we haven't labeled, it applies a lightweight heuristic that drops ones with no trading activity in the last 24 hours and negligible liquidity. If those activity and liquidity metrics aren't readily available for a token at query time, we keep it rather than risk hiding a real holding, so plenty of low-quality tokens may still need client-side filtering.
We intentionally keep this filtering conservative. Many tokens may look like scams, or may become scams, but can still be sellable by a user. If we hid them too aggressively, a user could lose the ability to see and sell a token that was flagged in error. For stricter filtering we recommend filtering client-side on metrics such as liquidity.
Under normal conditions, balances typically reflect a new transaction within a second or two after it finalizes. This is a general expectation rather than a guaranteed number, and we don't currently publish a formal standard or SLA for it.
Timing varies by network. Solana is the most common network for this query, where updates generally land within about 2 seconds of confirmation. Other networks may take longer. Response times can also be slower during periods of heavy balances indexing.
Our team is alerted to balance delays and addresses them promptly. If you consistently see delays beyond a few seconds (for example, more than 5 seconds on Solana), reach out to support.
### Related Recipes
* [Wallets](/recipes/wallets): Analyze wallet performance, discover top traders, and build portfolio views