> ## 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. # filterTokenWallets > Returns a list of wallets with stats narrowed down to a specific token. filterTokenWallets query reference: arguments and response fields. ## GraphQL ``` type Query { # Requires a Growth or Enterprise plan. filterTokenWallets( input: FilterTokenWalletsInput! ): TokenWalletFilterConnection! } 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 } enum WalletAggregateBackfillState { BackfillComplete BackfillInProgress BackfillCanceled BackfillBlocked BackfillRequestReceived BackfillNotFound } type TokenWalletFilterResult { address: String! tokenAddress: String! networkId: Int! firstTransactionAt: Int lastTransactionAt: Int! labels: [String!]! walletTradeSourceIds: [String!] tokenAmountBought1d: String! tokenAmountSold1d: String! tokenAmountSoldAll1d: String! amountBoughtUsd1d: String! amountSoldUsd1d: String! amountSoldUsdAll1d: String! realizedProfitUsd1d: String! realizedProfitPercentage1d: Float! avgHoldPeriodSec1d: Float buys1d: Int! sells1d: Int! sellsAll1d: Int! tokenAmountBought1w: String! tokenAmountSold1w: String! tokenAmountSoldAll1w: String! amountBoughtUsd1w: String! amountSoldUsd1w: String! amountSoldUsdAll1w: String! realizedProfitUsd1w: String! realizedProfitPercentage1w: Float! avgHoldPeriodSec1w: Float buys1w: Int! sells1w: Int! sellsAll1w: Int! tokenAmountBought30d: String! tokenAmountSold30d: String! tokenAmountSoldAll30d: String! amountBoughtUsd30d: String! amountSoldUsd30d: String! amountSoldUsdAll30d: String! realizedProfitUsd30d: String! realizedProfitPercentage30d: Float! avgHoldPeriodSec30d: Float buys30d: Int! sells30d: Int! sellsAll30d: Int! tokenAmountBought1y: String! tokenAmountSold1y: String! tokenAmountSoldAll1y: String! amountBoughtUsd1y: String! amountSoldUsd1y: String! amountSoldUsdAll1y: String! realizedProfitUsd1y: String! realizedProfitPercentage1y: Float! avgHoldPeriodSec1y: Float buys1y: Int! sells1y: Int! sellsAll1y: Int! tokenAcquisitionCostUsd: String! purchasedTokenBalance: String! tokenBalance: String! tokenBalanceLive: String tokenBalanceLiveUsd: String token: EnhancedToken! scammerScore: Int botScore: Int backfillState: WalletAggregateBackfillState } type TokenWalletFilterConnection { results: [TokenWalletFilterResult!]! count: Int! offset: Int! } input WalletTokenFilterRange { min: String max: String } input WalletTokenFilters { lastTransactionAt: WalletTokenFilterRange firstTransactionAt: WalletTokenFilterRange tokenAmountBought1d: WalletTokenFilterRange tokenAmountSold1d: WalletTokenFilterRange amountBoughtUsd1d: WalletTokenFilterRange amountSoldUsd1d: WalletTokenFilterRange realizedProfitUsd1d: WalletTokenFilterRange realizedProfitPercentage1d: WalletTokenFilterRange avgHoldPeriodSec1d: WalletTokenFilterRange buys1d: WalletTokenFilterRange sells1d: WalletTokenFilterRange tokenAmountBought1w: WalletTokenFilterRange tokenAmountSold1w: WalletTokenFilterRange amountBoughtUsd1w: WalletTokenFilterRange amountSoldUsd1w: WalletTokenFilterRange realizedProfitUsd1w: WalletTokenFilterRange realizedProfitPercentage1w: WalletTokenFilterRange avgHoldPeriodSec1w: WalletTokenFilterRange buys1w: WalletTokenFilterRange sells1w: WalletTokenFilterRange tokenAmountBought30d: WalletTokenFilterRange tokenAmountSold30d: WalletTokenFilterRange amountBoughtUsd30d: WalletTokenFilterRange amountSoldUsd30d: WalletTokenFilterRange realizedProfitUsd30d: WalletTokenFilterRange realizedProfitPercentage30d: WalletTokenFilterRange avgHoldPeriodSec30d: WalletTokenFilterRange buys30d: WalletTokenFilterRange sells30d: WalletTokenFilterRange tokenAmountBought1y: WalletTokenFilterRange tokenAmountSold1y: WalletTokenFilterRange amountBoughtUsd1y: WalletTokenFilterRange amountSoldUsd1y: WalletTokenFilterRange realizedProfitUsd1y: WalletTokenFilterRange realizedProfitPercentage1y: WalletTokenFilterRange avgHoldPeriodSec1y: WalletTokenFilterRange buys1y: WalletTokenFilterRange sells1y: WalletTokenFilterRange tokenBalance: WalletTokenFilterRange purchasedTokenBalance: WalletTokenFilterRange tokenAcquisitionCostUsd: WalletTokenFilterRange scammerScore: WalletTokenFilterRange botScore: WalletTokenFilterRange } input NumberFilter { gte: Float gt: Float lte: Float lt: Float } input WalletTokenFiltersV2 { lastTransactionAt: NumberFilter firstTransactionAt: NumberFilter tokenAmountBought1d: NumberFilter tokenAmountSold1d: NumberFilter amountBoughtUsd1d: NumberFilter amountSoldUsd1d: NumberFilter realizedProfitUsd1d: NumberFilter realizedProfitPercentage1d: NumberFilter avgHoldPeriodSec1d: NumberFilter buys1d: NumberFilter sells1d: NumberFilter trades1d: NumberFilter tokenAmountBought1w: NumberFilter tokenAmountSold1w: NumberFilter amountBoughtUsd1w: NumberFilter amountSoldUsd1w: NumberFilter realizedProfitUsd1w: NumberFilter realizedProfitPercentage1w: NumberFilter avgHoldPeriodSec1w: NumberFilter buys1w: NumberFilter sells1w: NumberFilter trades1w: NumberFilter tokenAmountBought30d: NumberFilter tokenAmountSold30d: NumberFilter amountBoughtUsd30d: NumberFilter amountSoldUsd30d: NumberFilter realizedProfitUsd30d: NumberFilter realizedProfitPercentage30d: NumberFilter avgHoldPeriodSec30d: NumberFilter buys30d: NumberFilter sells30d: NumberFilter trades30d: NumberFilter tokenAmountBought1y: NumberFilter tokenAmountSold1y: NumberFilter amountBoughtUsd1y: NumberFilter amountSoldUsd1y: NumberFilter realizedProfitUsd1y: NumberFilter realizedProfitPercentage1y: NumberFilter avgHoldPeriodSec1y: NumberFilter buys1y: NumberFilter sells1y: NumberFilter trades1y: NumberFilter tokenBalance: NumberFilter purchasedTokenBalance: NumberFilter tokenAcquisitionCostUsd: NumberFilter scammerScore: NumberFilter botScore: NumberFilter } enum WalletTokenRankingAttribute { firstTransactionAt lastTransactionAt tokenAmountBought1d tokenAmountSold1d amountBoughtUsd1d amountSoldUsd1d realizedProfitUsd1d realizedProfitPercentage1d avgHoldPeriodSec1d buys1d sells1d tokenAmountBought1w tokenAmountSold1w amountBoughtUsd1w amountSoldUsd1w realizedProfitUsd1w realizedProfitPercentage1w avgHoldPeriodSec1w buys1w sells1w tokenAmountBought30d tokenAmountSold30d amountBoughtUsd30d amountSoldUsd30d realizedProfitUsd30d realizedProfitPercentage30d avgHoldPeriodSec30d buys30d sells30d tokenAmountBought1y tokenAmountSold1y amountBoughtUsd1y amountSoldUsd1y realizedProfitUsd1y realizedProfitPercentage1y avgHoldPeriodSec1y buys1y sells1y tokenBalance purchasedTokenBalance tokenAcquisitionCostUsd scammerScore botScore } enum RankingDirection { ASC DESC } input WalletTokenRanking { attribute: WalletTokenRankingAttribute! direction: RankingDirection! } input FilterTokenWalletsInput { tokenIds: [String] wallets: [String] networkId: Int filtersV2: WalletTokenFiltersV2 phrase: String rankings: [WalletTokenRanking] excludeLabels: [String] includeLabels: [String] includeTradeSourceIds: [String] excludeTradeSourceIds: [String] limit: Int offset: Int } ``` ### Example [Test this query in the Explorer →](https://docs.codex.io/explore.md) ```graphql theme={null} { 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 } } ``` > [!TIP] > > **`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`](https://docs.codex.io/api-reference/queries/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 `tokenIds` array with token IDs in `address:networkId` format * Use `rankings` to sort results by any stat attribute (e.g., `realizedProfitUsd30d`, `tokenBalance`) * Stats are available in multiple time windows: `1d`, `1w`, `30d`, `1y` * Use `filtersV2` to filter wallets by numeric ranges (e.g., minimum profit, minimum buys) * `tokenBalance` is the last known balance; use `tokenBalanceLive` for real-time balance * Use `includeLabels` and `excludeLabels` to filter by wallet labels (e.g., smart money, bots) * Maximum of 50 token IDs per query; multiple tokens require at least one wallet address * `count` is the number of wallets in this page, not the total number of matching wallets. Page with `offset` until a page returns fewer results than `limit`. The maximum `limit` is 10,000. * `walletTradeSourceIds` and the `includeTradeSourceIds` / `excludeTradeSourceIds` filters describe the wallet's apps **overall, not its activity on the queried token** — see [Filter by Trade Source](https://docs.codex.io/recipes/wallets/discover-traders.md#filter-by-trade-source) ### Troubleshooting Tips > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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. Trades are credited to the transaction's signer (`maker`). When a buy goes through a router, aggregator or custodial wallet that signs on the user's behalf, it is credited to that signer, so the end wallet may not appear. > [accordion] 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. > [accordion] 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](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.