balances - Codex

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

Show Properties

walletId

String!

The ID of the wallet (walletAddress:networkId).

tokenId

String!

The ID of the token (tokenAddress:networkId).

address

String!

The wallet address.

networkId

Int!

The wallet network.

tokenAddress

String!

The contract address of the token.

balance

String!

The balance held by the wallet.

shiftedBalance

Float!

The balance held by the wallet, adjusted by the number of decimals in the token.

balanceUsd

String

The balance held by the wallet in USD.

tokenPriceUsd

String

The token price in USD.

firstHeldTimestamp

Int

The time that this address first held a token.

token

EnhancedToken

Metadata for the token. See EnhancedToken

Show Properties

String!

The ID of the token (address:networkId).

address

String!

The contract address of the token.

cmcId

Int

The token ID on CoinMarketCap.

decimals

Int!

The precision to which the token can be divided. For example, the smallest unit for USDC is 0.000001 (6 decimals).

isScam

Boolean

Whether the token has been flagged as a scam.

name

String

The token name. For example, ApeCoin.

networkId

Int!

The network ID the token is deployed on.

symbol

String

The token symbol. For example, APE.

Community gathered links for the socials of this token. See SocialLinks

Show Properties

bitcointalk

String

blog

String

coingecko

String

coinmarketcap

String

discord

String

facebook

String

github

String

instagram

String

slack

String

twitch

String

twitter

String

website

String

wechat

String

whitepaper

String

youtube

String

info

TokenInfo

More metadata about the token. See TokenInfo

Show Properties

String!

Uniquely identifies the token.

address

String!

The contract address of the token.

circulatingSupply

String

The circulating supply of the token.

cmcId

Int

The token ID on CoinMarketCap.

gridAssetId

String

The Grid asset ID, if this token is linked to a Grid asset.

bluechipRating

String

The Grid bluechip rating for this token (e.g. A+, B-).

isScam

Boolean

Whether the token has been flagged as a scam.

name

String

The token name. For example, ApeCoin.

networkId

Int!

The network ID the token is deployed on.

symbol

String!

The token symbol. For example, APE.

totalSupply

String

The total supply of the token.

imageThumbHash

String

The thumbhash of the token logo.

imageThumbUrl

String

The thumbnail token logo URL.

imageSmallUrl

String

The small token logo URL.

imageLargeUrl

String

The large token logo URL.

imageBannerUrl

String

The token banner URL.

videoExternalUrl

String

The original URL/URI for the video associated with the token.

description

String

A description of the token.

gridAssetId

String

The Grid asset ID, if this token is linked to a Grid asset.

bluechipRating

String

The Grid bluechip rating for this token (e.g. A+, B-).

organization

Organization

The Grid organization associated with this token. See Organization

Show Properties

name

String!

The organization name.

foundingDate

String

The founding date of the organization.

descriptionShort

String

A short description of the organization.

descriptionLong

String

A detailed description of the organization.

tagLine

String

The organization’s tagline.

type

String

The type of organization (e.g. protocol, company).

sector

String

The sector the organization operates in.

urls

[OrganizationUrl!]!

URLs associated with the organization. See OrganizationUrl

Show Properties

url

String!

The URL.

type

String

The type of URL (e.g. website, docs).

socials

[OrganizationSocial!]!

Social links for the organization. See OrganizationSocial

Show Properties

url

String!

The social URL.

type

String

The type of social link (e.g. twitter, discord).

logo

String

The organization’s logo URL.

icon

String

The organization’s icon URL.

header

String

rootId

String!

The Grid root ID for the organization.

assets

[Asset!]!

Assets managed by this organization. See Asset

Show Properties

String!

The Grid asset ID.

name

String

The asset name.

description

String

A description of the asset.

ticker

String

The asset ticker symbol.

type

String

The asset type (e.g. token, stablecoin).

status

String

The asset status.

icon

String

The asset icon URL.

rootId

String!

The Grid root ID for the parent organization.

assetDeployments

[AssetDeployment!]!

Deployments of this asset across chains. See AssetDeployment

Show Properties

String!

The deployment ID.

networkId

Int!

The network ID the asset is deployed on.

address

String!

The contract address of the deployment.

standard

String

The token standard (e.g. ERC20, SPL).

assetId

String!

The Grid asset ID.

rootId

String!

The Grid root ID for the parent organization.

token

EnhancedToken

The enhanced token this deployment represents. See EnhancedToken

asset

Asset

The Grid asset associated with this token. See Asset

Show Properties

String!

The Grid asset ID.

name

String

The asset name.

description

String

A description of the asset.

ticker

String

The asset ticker symbol.

type

String

The asset type (e.g. token, stablecoin).

status

String

The asset status.

icon

String

The asset icon URL.

rootId

String!

The Grid root ID for the parent organization.

assetDeployments

[AssetDeployment!]!

Deployments of this asset across chains. See AssetDeployment

Show Properties

String!

The deployment ID.

networkId

Int!

The network ID the asset is deployed on.

address

String!

The contract address of the deployment.

standard

String

The token standard (e.g. ERC20, SPL).

assetId

String!

The Grid asset ID.

rootId

String!

The Grid root ID for the parent organization.

token

EnhancedToken

The enhanced token this deployment represents. See EnhancedToken

exchanges

[Exchange!]

A list of exchanges where the token has been traded. See Exchange

Show Properties

String!

The ID of the exchange (address:id).

address

String!

The contract address of the exchange.

color

String

The hex string for the exchange color.

name

String

The name of the exchange.

exchangeVersion

String

The version of the exchange, if applicable.

iconUrl

String

The exchange logo URL.

networkId

Int!

The network ID the exchange is deployed on.

tradeUrl

String

The URL for the exchange.

creatorAddress

String

The token creator’s wallet address.

createBlockNumber

Int

The block height the token was created at.

createTransactionHash

String

The transaction hash of the token’s creation.

createdAt

Int

The unix timestamp for the creation of the token.

mintable

String

Returns mint authority address if token is mintable. If null, verify against isMintableValid.

freezable

String

Returns freeze authority address if token is freezable. If null, verify against isFreezableValid.

isFreezableValid

Boolean

Determines if freezable is a valid address or null value for the authority, or if the freezable state has not yet been determined.

isMintableValid

Boolean

Determines if mintable is a valid address or null value for the authority, or if the mintable state has not yet been determined.

launchpad

LaunchpadData

The launchpad data for the token, if applicable. See LaunchpadData

Show Properties

launchpadName

String

The name of the launchpad.

graduationPercent

Float

The percentage of the pool that was sold to the public.

poolAddress

String

The address of the pool.

completedAt

Int

The unix timestamp when the launchpad was completed.

completed

Boolean

Indicates if the launchpad is completed.

completedSlot

Int

The slot number when the launchpad was completed.

migratedSlot

Int

The slot number when the launchpad was migrated.

migratedAt

Int

The unix timestamp when the launchpad was migrated.

migrated

Boolean

Indicates if the launchpad was migrated.

migratedPoolAddress

String

The pool address after the launchpad was migrated.

launchpadProtocol

String

The launchpad protocol.

launchpadIconUrl

String

The icon URL of the launchpad.

isCashbackEnabled

Boolean

Whether cashback is enabled for this launchpad token (Pump V1/V2 only).

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.

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.

sortBy

BalancesSortAttribute

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

Show Properties

BALANCE

enum

Sort by raw token balance amount (default).

USD_VALUE

enum

Sort by USD value (descending).

sortDirection

RankingDirection

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

Show Properties

ASC

enum

DESC

enum

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

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 tokens flagged as scams
Use the cursor parameter for pagination through large token holdings

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 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 tokens I don't recognize?

Wallets often receive airdropped scam tokens. Use removeScams: true to filter these out. You can also check the token.isScam field on individual results.

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

Documentation Index

​Returns

​Arguments

​Example

​Usage Guidelines

​Troubleshooting Tips

​Related Recipes

Returns

Arguments

Example

Usage Guidelines

Troubleshooting Tips

Related Recipes