> ## 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. Reference for the balances query in the Codex API: arguments, response fields, and usage. ## 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 tiktok: 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 BURN LOCKER } 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 tradeSourceIds: [String!] identitySource: String identityUpdatedAt: Int polymarket: WalletPolymarketProfile tokensCreatedCount: Int tokensMigratedCount: Int } enum FeeMode { CREATOR_FEE CASHBACK HOLDER_REWARDS } 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 feeModes: [FeeMode!] holderRewardFeeBps: Int holderRewardQuoteMint: String 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 Token2022TransferFee { epoch: String! transferFeeBasisPoints: Int! maximumFee: String! } type Token2022TransferFeeConfig { transferFeeConfigAuthority: String olderTransferFee: Token2022TransferFee! newerTransferFee: Token2022TransferFee! } type Token2022Extensions { scaledUiAmountConfig: Token2022ScaledUiAmountConfig transferFeeConfig: Token2022TransferFeeConfig } type B20Extensions { multiplier: String multiplierObservedAt: String pausedTransfer: Boolean pausedMint: Boolean pausedBurn: Boolean supplyCap: String } type RobinhoodStockTokenExtensions { uid: String! multiplier: String multiplierObservedAt: String newMultiplier: String newMultiplierEffectiveAt: String oraclePaused: Boolean } type XStockTokenExtensions { multiplier: String multiplierObservedAt: String newMultiplier: String newMultiplierEffectiveAt: String } type TokenExtensions { token2022: Token2022Extensions b20: B20Extensions robinhoodStockToken: RobinhoodStockTokenExtensions xStock: XStockTokenExtensions } 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 } enum RiskVerdict { SCAM HIGH_RISK CAUTION NEUTRAL VERIFIED VERIFIED_CONTESTED } enum RiskAnalysisCoverage { NOT_ANALYZED INCONCLUSIVE ANALYZED STALE } enum RiskReasonCode { PROOF_HONEYPOT_SIM PROOF_NON_TRANSFERABLE PROOF_TRANSFER_FEE_100 PROOF_DEFAULT_FROZEN PROOF_POOL_TRAP_SIM AUTH_MINT AUTH_FREEZE AUTH_PERMANENT_DELEGATE AUTH_TRANSFER_HOOK AUTH_PAUSABLE AUTH_OWNER_NOT_RENOUNCED AUTH_CAN_TRANSFER_OWNERSHIP TAX_BUY_HIGH TAX_SELL_HIGH TAX_HONEYPOT_UNCONFIRMED TAX_PAUSED TAX_POOL_TRAP TAX_POOL_TRAP_HOOK_SHARED LIQ_MINIMAL LIQ_UNKNOWN LIQ_RUG_CLIFF LIQ_UNLOCKED LIQ_DRAINING HOLD_TOP10_CONCENTRATED HOLD_DEV_HEAVY HOLD_SNIPER_HEAVY HOLD_BUNDLER_HEAVY HOLD_INSIDER_HEAVY HOLD_INSIDER_DUMPED FLOW_ONE_WAY FLOW_WALLET_FARM FLOW_WASH_DOMINATED FLOW_BUNDLED_LAUNCH FLOW_MECHANICAL_TRADING FLOW_RING_DOMINATED REP_SERIAL_RUGGER REP_RISKY_CREATOR REP_SCAMMER_FUNDED REP_IMITATOR_SYMBOL REP_IMITATOR_NAME REP_IMITATOR_IMAGE LABEL_MANUAL_SCAM LABEL_VERIFIED } type TokenRisk { verdict: RiskVerdict score: Float flaggedAt: Int analyzedAt: Int coverage: RiskAnalysisCoverage reasons: [RiskReasonCode!] buyTax: Float sellTax: Float } type TokenIssuer { id: String! displayName: String } 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 creatorBalanceNBT: String 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!] risk: TokenRisk issuer: TokenIssuer } 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 assetId: String balanceDecimals: Int isBalanceAlias: Boolean } type BalancesResponse { items: [Balance!]! cursor: String } enum BalancesSortAttribute { BALANCE USD_VALUE } enum RankingDirection { ASC DESC } enum UiAmountMode { RAW SCALED } input NumberFilter { gte: Float gt: Float lte: Float lt: Float } input BalanceFilters { balanceUsd: NumberFilter liquidityUsd: NumberFilter hasPrice: Boolean } input BalancesInput { walletAddress: String networks: [Int!] tokens: [String!] includeNative: Boolean limit: Int cursor: String removeScams: Boolean sortBy: BalancesSortAttribute sortDirection: RankingDirection uiAmountMode: UiAmountMode filters: BalanceFilters } ``` ### Example [Test this query in the Explorer →](https://docs.codex.io/explore.md) ```graphql theme={null} { balances( input: {walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", networks: [1], removeScams: true, limit: 10} ) { items { tokenId shiftedBalance balanceUsd tokenPriceUsd token { name symbol info { imageSmallUrl } } } cursor } } ``` > [!NOTE] > > 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`](https://docs.codex.io/api-reference/input-objects/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](https://docs.codex.io/extra/faq.md#can-i-get-a-wallets-historical-portfolio-value-over-time) for the recommended approach to reconstructing historical portfolio value ### Troubleshooting Tips > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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](https://docs.codex.io/recipes/wallets/discover-traders.md): Analyze wallet performance, discover top traders, and build portfolio views This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.