balances

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

Returns

BalancesResponse!

See BalancesResponse

Show Properties

[Balance!]!

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

String

A cursor for use in pagination.

Arguments

BalancesInput!

required

See BalancesInput

Show Properties

String

The wallet address to filter by.

[Int!]

The network IDs to filter by.

[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.

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.

Int

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

String

A cursor for use in pagination.

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.

BalancesSortAttribute

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

RankingDirection

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

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

String

deprecated

The ID of the wallet (walletAddress:networkId).

This field is deprecated. Use walletAddress and networkId instead

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
  }
}

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
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 are native balances not showing?

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.

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 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.

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.

Wallets: Analyze wallet performance, discover top traders, and build portfolio views

API Documentation

Queries

Mutations

Subscriptions

Types

Returns

Arguments

Example

Usage Guidelines

Troubleshooting Tips

​Returns

​Arguments

​Example

​Usage Guidelines

​Troubleshooting Tips

​Related Recipes

Returns

Arguments

Example

Usage Guidelines

Troubleshooting Tips

Related Recipes