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.
This endpoint requires a Growth or Enterprise plan. Learn more.
Returns
See TokenWalletFilterConnection
Show Properties
Show Properties
The list of wallets matching the filter parameters.
See TokenWalletFilterResult
Show Properties
Show Properties
The wallet address
The token address
The network ID
The unix timestamp for the first transaction from this wallet
The unix timestamp for the last transaction from this wallet
The labels associated with the wallet
Token amount bought in the past day
Token amount sold in the past day
Token amount sold all in the past day
Amount bought in USD in the past day
Amount sold in USD in the past day
Amount sold USD all in the past day
Realized profit in USD in the past day
Realized profit percentage in the past day
Average hold period, in seconds, for positions sold during the past day. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
Number of buys in the past day
Number of sells in the past day
Number of sells all in the past day
Token amount bought in the past week
Token amount sold in the past week
Token amount sold all in the past week
Amount bought in USD in the past week
Amount sold in USD in the past week
Amount sold USD all in the past week
Realized profit in USD in the past week
Realized profit percentage in the past week
Average hold period, in seconds, for positions sold during the past week. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
Number of buys in the past week
Number of sells in the past week
Number of sells all in the past week
Token amount bought in the past 30 days
Token amount sold in the past 30 days
Token amount sold all in the past 30 days
Amount bought in USD in the past 30 days
Amount sold in USD in the past 30 days
Amount sold USD all in the past 30 days
Realized profit in USD in the past 30 days
Realized profit percentage in the past 30 days
Average hold period, in seconds, for positions sold during the past 30 days. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
Number of buys in the past 30 days
Number of sells in the past 30 days
Number of sells all in the past 30 days
Token amount bought in the past year
Token amount sold in the past year
Token amount sold all in the past year
Amount bought in USD in the past year
Amount sold in USD in the past year
Amount sold USD all in the past year
Realized profit in USD in the past year
Realized profit percentage in the past year
Average hold period, in seconds, for positions sold during the past year. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
Number of buys in the past year
Number of sells in the past year
Number of sells all in the past year
The token acquisition cost in USD
The total balance of tokens that the user has bought or sold. This value does not include tokens acquired through external transfers or unsupported methods.
The total balance of tokens held by the user, reflecting the most recent update to the record. This balance includes all tokens, even those transferred in through unsupported methods or DEXs that are not tracked by our system. This value does not update with every transfer and can be slightly stale. Use tokenBalanceLive for live data.
The current token balance in the wallet. This value is updated with every transfer and is therefore more accurate than tokenBalance.
The current USD value of the token balance.
The token metadata
See EnhancedToken
Show Properties
Show Properties
The ID of the token (
address:networkId).The contract address of the token.
The token ID on CoinMarketCap.
The precision to which the token can be divided. For example, the smallest unit for USDC is 0.000001 (6 decimals).
Whether the token has been flagged as a scam.
The token name. For example,
ApeCoin.The network ID the token is deployed on.
The token symbol. For example,
APE.Community gathered links for the socials of this token.
See SocialLinks
More metadata about the token.
See TokenInfo
Show Properties
Show Properties
Uniquely identifies the token.
The contract address of the token.
The circulating supply of the token.
The token ID on CoinMarketCap.
The Grid asset ID, if this token is linked to a Grid asset.
The Grid bluechip rating for this token (e.g.
A+, B-).Whether the token has been flagged as a scam.
The token name. For example,
ApeCoin.The network ID the token is deployed on.
The token symbol. For example,
APE.The total supply of the token.
The thumbhash of the token logo.
The thumbnail token logo URL.
The small token logo URL.
The large token logo URL.
The token banner URL.
The original URL/URI for the video associated with the token.
A description of the token.
The Grid asset ID, if this token is linked to a Grid asset.
The Grid bluechip rating for this token (e.g.
A+, B-).The Grid organization associated with this token.
See Organization
Show Properties
Show Properties
The organization name.
The founding date of the organization.
A short description of the organization.
A detailed description of the organization.
The organization’s tagline.
The type of organization (e.g.
protocol, company).The sector the organization operates in.
URLs associated with the organization.
See OrganizationUrl
Social links for the organization.
See OrganizationSocial
The organization’s logo URL.
The organization’s icon URL.
The Grid root ID for the organization.
Assets managed by this organization.
See Asset
Show Properties
Show Properties
The Grid asset ID.
The asset name.
A description of the asset.
The asset ticker symbol.
The asset type (e.g.
token, stablecoin).The asset status.
The asset icon URL.
The Grid root ID for the parent organization.
Deployments of this asset across chains.
See AssetDeployment
Show Properties
Show Properties
The deployment ID.
The network ID the asset is deployed on.
The contract address of the deployment.
The token standard (e.g.
ERC20, SPL).The Grid asset ID.
The Grid root ID for the parent organization.
The enhanced token this deployment represents.
See EnhancedToken
The Grid asset associated with this token.
See Asset
Show Properties
Show Properties
The Grid asset ID.
The asset name.
A description of the asset.
The asset ticker symbol.
The asset type (e.g.
token, stablecoin).The asset status.
The asset icon URL.
The Grid root ID for the parent organization.
Deployments of this asset across chains.
See AssetDeployment
Show Properties
Show Properties
The deployment ID.
The network ID the asset is deployed on.
The contract address of the deployment.
The token standard (e.g.
ERC20, SPL).The Grid asset ID.
The Grid root ID for the parent organization.
The enhanced token this deployment represents.
See EnhancedToken
A list of exchanges where the token has been traded.
See Exchange
Show Properties
Show Properties
The ID of the exchange (
address:id).The contract address of the exchange.
The hex string for the exchange color.
The name of the exchange.
The version of the exchange, if applicable.
The exchange logo URL.
The network ID the exchange is deployed on.
The URL for the exchange.
The token creator’s wallet address.
The block height the token was created at.
The transaction hash of the token’s creation.
The unix timestamp for the creation of the token.
Returns mint authority address if token is mintable. If null, verify against isMintableValid.
Returns freeze authority address if token is freezable. If null, verify against isFreezableValid.
Determines if freezable is a valid address or null value for the authority, or if the freezable state has not yet been determined.
Determines if mintable is a valid address or null value for the authority, or if the mintable state has not yet been determined.
The launchpad data for the token, if applicable.
See LaunchpadData
Show Properties
Show Properties
The name of the launchpad.
The percentage of the pool that was sold to the public.
The address of the pool.
The unix timestamp when the launchpad was completed.
Indicates if the launchpad is completed.
The slot number when the launchpad was completed.
The slot number when the launchpad was migrated.
The unix timestamp when the launchpad was migrated.
Indicates if the launchpad was migrated.
The pool address after the launchpad was migrated.
The launchpad protocol.
The icon URL of the launchpad.
Whether cashback is enabled for this launchpad token (Pump V1/V2 only).
The token category assigned by the launchpad. Populated by launchpads that publish a category taxonomy (e.g. Scale/Creator, Eitherway). Values include platform, meme, utility, etc.
The name of the launchpad.
This field is deprecated. Use launchpadName instead
The percentage of total supply held by the top 10 holders (excluding exchanges/pairs).
Whether the token name or symbol contains profanity.
All-time high and low price/market cap data for the token.
See TokenExtrema
Show Properties
Show Properties
The token ID (
address:networkId).The contract address of the token.
The network ID the token is deployed on.
The all-time high price in USD.
The unix timestamp when the all-time high price was reached.
The all-time low price in USD.
The unix timestamp when the all-time low price was reached.
The all-time high fully diluted market cap.
The unix timestamp when the all-time high FDV was reached.
The all-time low fully diluted market cap.
The unix timestamp when the all-time low FDV was reached.
The all-time high circulating market cap.
The unix timestamp when the all-time high circulating market cap was reached.
The all-time low circulating market cap.
The unix timestamp when the all-time low circulating market cap was reached.
The Coin Community data for the token
See CoinCommunity
The total supply of the token.
This field is deprecated. Use the TokenInfo type
Information about the token from 3rd party sources.
See ExplorerTokenData
This field is deprecated. Use the TokenInfo type
Show Properties
Show Properties
The ID of the token (
address:networkId).Whether the token has been verified on CoinGecko.
A description of the token.
The precision to which the token can be divided.
The token price in USD.
The token type.
The thumbnail token logo URL.
This field is deprecated. Use the TokenInfo type
The small token logo URL.
This field is deprecated. Use the TokenInfo type
The large token logo URL.
This field is deprecated. Use the TokenInfo type
The circulating supply of the token.
This field is deprecated. Use the TokenInfo type
The amount of this token in the pair.
This field is deprecated. Pooled can be found on the pair instead
The scammer score for the wallet.
The bot score for the wallet.
The backfill state of the wallet.
See WalletAggregateBackfillState
Show Properties
Show Properties
Historical stats calculations for this wallet have been successfully processed
Historical stats calculations for this wallet are being processed
Historical stats calculations were started, then canceled for this wallet. It may have been flagged as a bot
Historical stats calculations have been blocked for this wallet. It may have been flagged as a bot
Historical stats calculations for this wallet are queued and will be processed soon
Historical stats calculations for this wallet have not been started, nor attempted
The number of wallets returned.
Where in the list the server started when returning items.
Arguments
See FilterTokenWalletsInput
Show Properties
Show Properties
The IDs of the tokens to filter wallets for. Maximum 50 tokenIds. If you provide more than one tokenId, you must also provide at least one walletAddress in the wallets list.
A list of wallet addresses to filter wallets for
The network ID to filter wallets for
A set of filters to apply
See WalletTokenFiltersV2
Show Properties
Show Properties
Filter by last transaction timestamp
See NumberFilter
Filter by first transaction timestamp
See NumberFilter
Filter by token amount bought in the past day
See NumberFilter
Filter by token amount sold in the past day
See NumberFilter
Filter by amount bought in USD in the past day
See NumberFilter
Filter by amount sold in USD in the past day
See NumberFilter
Filter by realized profit in USD in the past day
See NumberFilter
Filter by realized profit percentage in the past day
See NumberFilter
Average hold period, in seconds, for positions sold during the past day. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
See NumberFilter
Filter by number of buys in the past day
See NumberFilter
Filter by number of sells in the past day
See NumberFilter
Filter by token amount bought in the past week
See NumberFilter
Filter by token amount sold in the past week
See NumberFilter
Filter by amount bought in USD in the past week
See NumberFilter
Filter by amount sold in USD in the past week
See NumberFilter
Filter by realized profit in USD in the past week
See NumberFilter
Filter by realized profit percentage in the past week
See NumberFilter
Average hold period, in seconds, for positions sold during the past week. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
See NumberFilter
Filter by number of buys in the past week
See NumberFilter
Filter by number of sells in the past week
See NumberFilter
Filter by token amount bought in the past 30 days
See NumberFilter
Filter by token amount sold in the past 30 days
See NumberFilter
Filter by amount bought in USD in the past 30 days
See NumberFilter
Filter by amount sold in USD in the past 30 days
See NumberFilter
Filter by realized profit in USD in the past 30 days
See NumberFilter
Filter by realized profit percentage in the past 30 days
See NumberFilter
Average hold period, in seconds, for positions sold during the past 30 days. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
See NumberFilter
Filter by number of buys in the past 30 days
See NumberFilter
Filter by number of sells in the past 30 days
See NumberFilter
Filter by token amount bought in the past year
See NumberFilter
Filter by token amount sold in the past year
See NumberFilter
Filter by amount bought in USD in the past year
See NumberFilter
Filter by amount sold in USD in the past year
See NumberFilter
Filter by realized profit in USD in the past year
See NumberFilter
Filter by realized profit percentage in the past year
See NumberFilter
Average hold period, in seconds, for positions sold during the past year. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
See NumberFilter
Filter by number of buys in the past year
See NumberFilter
Filter by number of sells in the past year
See NumberFilter
Filter by token balance
See NumberFilter
Filter by purchased token balance
See NumberFilter
Filter by token acquisition cost in USD
See NumberFilter
Filter by scammer score
See NumberFilter
A phrase to search for in token symbol and name
A list of ranking attributes to apply
See WalletTokenRanking
Show Properties
Show Properties
The attribute to rank wallets by
See WalletTokenRankingAttribute
Show Properties
Show Properties
The first transaction timestamp
The last transaction timestamp
Token amount bought in the past day
Token amount sold in the past day
Amount bought in USD in the past day
Amount sold in USD in the past day
Realized profit in USD in the past day
Realized profit percentage in the past day
Average hold period, in seconds, for positions sold during the past day.
Number of buys in the past day
Number of sells in the past day
Token amount bought in the past week
Token amount sold in the past week
Amount bought in USD in the past week
Amount sold in USD in the past week
Realized profit in USD in the past week
Realized profit percentage in the past week
Average hold period, in seconds, for positions sold during the past week.
Number of buys in the past week
Number of sells in the past week
Token amount bought in the past 30 days
Token amount sold in the past 30 days
Amount bought in USD in the past 30 days
Amount sold in USD in the past 30 days
Realized profit in USD in the past 30 days
Realized profit percentage in the past 30 days
Average hold period, in seconds, for positions sold during the past 30 days.
Number of buys in the past 30 days
Number of sells in the past 30 days
Token amount bought in the past year
Token amount sold in the past year
Amount bought in USD in the past year
Amount sold in USD in the past year
Realized profit in USD in the past year
Realized profit percentage in the past year
Average hold period, in seconds, for positions sold during the past year.
Number of buys in the past year
Number of sells in the past year
The total balance of tokens held by the user, reflecting the most recent update to the record. This balance includes all tokens, even those transferred in through unsupported methods or DEXs that are not tracked by our system.
The total balance of tokens that the user has bought or sold. This value does not include tokens acquired through external transfers or unsupported methods.
Token acquisition cost in USD
The scammer score for the wallet.
The bot score for the wallet.
The direction to apply to the ranking attribute
See RankingDirection
Exclude wallets with these labels. See
WalletLabel for possible values.Include wallets with these labels. See
WalletLabel for possible values.The maximum number of wallets to return
Where in the list the server should start when returning items
The ID of the token to filter wallets for
This field is deprecated. Use tokenIds instead
The wallet address to filter wallets for
This field is deprecated. Use wallets instead
A set of filters to apply
See WalletTokenFilters
This field is deprecated. Use filtersV2 instead
Show Properties
Show Properties
Filter by last transaction timestamp
See WalletTokenFilterRange
Filter by first transaction timestamp
See WalletTokenFilterRange
Filter by token amount bought in the past day
See WalletTokenFilterRange
Filter by token amount sold in the past day
See WalletTokenFilterRange
Filter by amount bought in USD in the past day
See WalletTokenFilterRange
Filter by amount sold in USD in the past day
See WalletTokenFilterRange
Filter by realized profit in USD in the past day
See WalletTokenFilterRange
Filter by realized profit percentage in the past day
See WalletTokenFilterRange
Average hold period, in seconds, for positions sold during the past day. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
See WalletTokenFilterRange
Filter by number of buys in the past day
See WalletTokenFilterRange
Filter by number of sells in the past day
See WalletTokenFilterRange
Filter by token amount bought in the past week
See WalletTokenFilterRange
Filter by token amount sold in the past week
See WalletTokenFilterRange
Filter by amount bought in USD in the past week
See WalletTokenFilterRange
Filter by amount sold in USD in the past week
See WalletTokenFilterRange
Filter by realized profit in USD in the past week
See WalletTokenFilterRange
Filter by realized profit percentage in the past week
See WalletTokenFilterRange
Average hold period, in seconds, for positions sold during the past week. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
See WalletTokenFilterRange
Filter by number of buys in the past week
See WalletTokenFilterRange
Filter by number of sells in the past week
See WalletTokenFilterRange
Filter by token amount bought in the past 30 days
See WalletTokenFilterRange
Filter by token amount sold in the past 30 days
See WalletTokenFilterRange
Filter by amount bought in USD in the past 30 days
See WalletTokenFilterRange
Filter by amount sold in USD in the past 30 days
See WalletTokenFilterRange
Filter by realized profit in USD in the past 30 days
See WalletTokenFilterRange
Filter by realized profit percentage in the past 30 days
See WalletTokenFilterRange
Average hold period, in seconds, for positions sold during the past 30 days. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
See WalletTokenFilterRange
Filter by number of buys in the past 30 days
See WalletTokenFilterRange
Filter by number of sells in the past 30 days
See WalletTokenFilterRange
Filter by token amount bought in the past year
See WalletTokenFilterRange
Filter by token amount sold in the past year
See WalletTokenFilterRange
Filter by amount bought in USD in the past year
See WalletTokenFilterRange
Filter by amount sold in USD in the past year
See WalletTokenFilterRange
Filter by realized profit in USD in the past year
See WalletTokenFilterRange
Filter by realized profit percentage in the past year
See WalletTokenFilterRange
Average hold period, in seconds, for positions sold during the past year. Calculated from cost-basis turnover using sold cost basis. Returns null when there are no sells.
See WalletTokenFilterRange
Filter by number of buys in the past year
See WalletTokenFilterRange
Filter by number of sells in the past year
See WalletTokenFilterRange
Filter by token balance
See WalletTokenFilterRange
Filter by purchased token balance
See WalletTokenFilterRange
Filter by token acquisition cost in USD
See WalletTokenFilterRange
Filter by scammer score
See WalletTokenFilterRange
Filter by bot score
See WalletTokenFilterRange
Example
Test this query in the Explorer →{
filterTokenWallets(
input: {
tokenIds: ["0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:1"]
limit: 5
rankings: [
{ attribute: realizedProfitUsd30d, direction: DESC }
]
}
) {
results {
address
tokenAddress
networkId
lastTransactionAt
tokenBalance
tokenBalanceLive
tokenBalanceLiveUsd
realizedProfitUsd30d
realizedProfitPercentage30d
buys30d
sells30d
amountBoughtUsd30d
amountSoldUsd30d
token {
name
symbol
}
}
count
offset
}
}
filterTokenWallets vs holders: Use filterTokenWallets when you need trading performance data (profit, buy/sell counts, volume, etc.). These records are only updated on swaps, so they focus on trader activity. If a wallet received tokens through a transfer rather than a swap, it will not appear here.Use holders when you want the most accurate, up-to-date holder list and balances. holders records are updated on every token transfer.Usage Guidelines
- Query using
tokenIdsarray with token IDs inaddress:networkIdformat - Use
rankingsto sort results by any stat attribute (e.g.,realizedProfitUsd30d,tokenBalance) - Stats are available in multiple time windows:
1d,1w,30d,1y - Use
filtersV2to filter wallets by numeric ranges (e.g., minimum profit, minimum buys) tokenBalanceis the last known balance; usetokenBalanceLivefor real-time balance- Use
includeLabelsandexcludeLabelsto filter by wallet labels (e.g., smart money, bots) - Maximum of 50 token IDs per query; multiple tokens require at least one wallet address
Troubleshooting Tips
When should I use filterTokenWallets vs filterWallets?
When should I use filterTokenWallets vs filterWallets?
Use
filterTokenWallets when you want to find wallets that have traded a specific token and see their stats for that token only — great for finding top holders or profitable traders of a particular token. Use filterWallets when you want to discover wallets based on their overall trading performance across all tokens.What's the difference between tokenBalance and tokenBalanceLive?
What's the difference between tokenBalance and tokenBalanceLive?
tokenBalance is updated periodically and may be slightly stale. tokenBalanceLive is updated with every transfer and reflects the current balance. Use tokenBalanceLive when accuracy is critical.What's the difference between tokenBalance and purchasedTokenBalance?
What's the difference between tokenBalance and purchasedTokenBalance?
tokenBalance includes all tokens held, including those received via transfers. purchasedTokenBalance only includes tokens acquired through tracked buys/sells on supported DEXs, excluding airdrops and transfers.Why are some wallets missing from results?
Why are some wallets missing from results?
Only wallets that have traded the token on tracked DEXs are included. Wallets that received tokens via transfer only (airdrops, direct sends) may not appear.
What do botScore and scammerScore indicate?
What do botScore and scammerScore indicate?
botScore estimates likelihood the wallet is automated (0-100, higher = more likely bot). scammerScore estimates likelihood of fraudulent activity. Use these to filter out suspicious wallets.How do I find top profitable traders?
How do I find top profitable traders?
Use
rankings: [{ attribute: realizedProfitUsd30d, direction: DESC }] to sort by profit. Combine with filtersV2 to set minimum thresholds like realizedProfitUsd30d: { gte: 1000 }.Related Recipes
- Wallets: Analyze wallet performance, discover top traders, and build portfolio views