balances

Returns list of token balances that a wallet has. Reference for the balances query in the Codex API: arguments, response fields, and usage.

This endpoint requires a Growth or Enterprise plan. Learn more.

​

Returns

BalancesResponse · BalancesResponse!

See BalancesResponse

Show Properties

items · [Balance!]!

The list of token balances that a wallet has. See Balance

cursor · String

A cursor for use in pagination.

​

Arguments

input · BalancesInput! · required

See BalancesInput

Show Properties

walletAddress · String

The wallet address to filter by.

networks · [Int!]

The network IDs to filter by.

tokens · [String!]

The token IDs (address:networkId) or addresses to request the balance for. Requires a list of networks if only passing addresses. Include native network balances using native as the token address. Only applied when using walletAddress (not walletId). Max 200 tokens.

includeNative · Boolean

Whether to include native network balances in the response (ID will be native:<networkId>). Requires a list of networks. Does not apply when using tokens. On networks where the native asset is also readable through an ERC-20 alias contract, the response counts that holding once: the native view is returned and the alias projection row is suppressed on every page; request the alias contract explicitly in tokens, or set includeNative: false, for the contract view.

limit · Int

The maximum number of holdings to return. Does not apply when using tokens.

cursor · String

A cursor for use in pagination.

removeScams · Boolean

Whether to remove scam tokens from the response. Removes only tokens explicitly labelled as scams; unlabelled tokens are always kept. Clients wanting aggressive spam removal (e.g. by token symbol or liquidity) should filter client-side.

sortBy · BalancesSortAttribute

The attribute to sort the list on. Defaults to BALANCE (raw token amount). See BalancesSortAttribute

sortDirection · RankingDirection

The direction to sort the list. Defaults to DESC (highest value first). See RankingDirection

uiAmountMode · UiAmountMode

Controls how uiBalance is expressed. SCALED returns the Token-2022 stored RPC UI amount, and multiplies B20 balances by their active multiplier. RAW removes the active Token-2022 UI amount multiplier and returns B20 balances unchanged. Defaults to SCALED. See UiAmountMode

filters · BalanceFilters

Keeps only holdings that match every filter set. A filtered page reads at most 600 of the wallet’s holdings, so it can return fewer than limit results, or none, while cursor is still set; keep paging until cursor is null. Reuse a cursor only with the same filters. With tokens, name at most 200 token IDs across networks. See BalanceFilters

walletId · String · deprecated

The ID of the wallet (walletAddress:networkId).

This field is deprecated. Use walletAddress and networkId instead

filterToken · String · deprecated

Optional token specifically request the balance for. Only works with walletId.

This field is deprecated. Use tokens list instead

​

Example

Test this query in the Explorer →

{
  balances(
    input: {walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", networks: [1], removeScams: true, limit: 10}
  ) {
    items {
      tokenId
      shiftedBalance
      balanceUsd
      tokenPriceUsd
      token {
        name
        symbol
        info {
          imageSmallUrl
        }
      }
    }
    cursor
  }
}

Native balances (ETH, BNB, and so on) are returned on EVM networks alongside token balances. Codex reads a wallet’s native balance from the chain each time the wallet appears in a transaction. Native tokens a wallet receives from a contract, with no transaction of its own (for example a refund or an unwrap), can show up only after the wallet’s next transaction. Check updatedAtBlock to see when a balance was last read.

Balances are 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 remove tokens we’ve manually labelled as scams (isScam: true). Unlabelled tokens are always kept, so it won’t remove most junk airdrops. See the troubleshooting note below.
• Use filters (BalanceFilters) to keep only holdings in a balanceUsd or liquidityUsd range, or with or without a price (hasPrice). For example, filters: { liquidityUsd: { gt: 1000 } } drops tokens with almost no liquidity.
  • balanceUsd requires sortBy: USD_VALUE unless you pass tokens.
  • A filtered page reads at most 600 of the wallet’s holdings, so it can return fewer than limit results, or none, while cursor is still set. Keep paging until cursor is null, and reuse a cursor only with the same filters.
  • Unpriced tokens often have balanceUsd of "0" rather than null, so balanceUsd: { gte: 0 } keeps them. Use gt: 0 or hasPrice: true to drop them.
  • Native balances always match a liquidityUsd range.
  • Filters are not a scam filter: junk tokens with real-looking liquidity still pass.
• 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 when the block is unknown), for balance-freshness provenance.
• Rebasing tokens change holder balances without a Transfer event, so their balances here can drift from the token’s own balanceOf.
• limit defaults to 200 and cannot exceed 200. Use the cursor parameter to page through larger token holdings.
• Balances are current-state only — Codex does not store historical balances, so there is no way to query a wallet’s holdings as of a past block or timestamp. See the FAQ for the recommended approach to reconstructing historical portfolio value

​

Troubleshooting Tips

Why is a native balance out of date?

Codex reads the native balance from the chain each time the wallet appears in a transaction. Native tokens received from a contract without a transaction by the wallet (for example a refund or an unwrap) are picked up on the wallet’s next transaction. Check updatedAtBlock, and use the network’s RPC (eth_getBalance) if you need the balance at the latest block.

Why is balanceUsd returning null?

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.

How do I get an accurate portfolio value?

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.

How do I get balances for specific tokens only?

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.

Can I query multiple wallets at once?

No, balances queries a single wallet. To get balances for multiple wallets, make separate requests for each wallet address.

Why am I seeing scam or unrecognized tokens?

Wallets accumulate scam and junk tokens over time, often as unsolicited airdrops. Setting removeScams: true removes only tokens we’ve manually labelled as a scam (isScam: true), which we do sparingly. Unlabelled tokens are always kept, so most junk will still come through. To drop more, add filters, such as a liquidityUsd minimum or hasPrice: true, or filter client-side.

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, use filters or filter client-side on metrics such as liquidity.

How quickly are balances updated after a transaction?

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: Analyze wallet performance, discover top traders, and build portfolio views