> ## 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.
## 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 } 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 } 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 identitySource: String identityUpdatedAt: Int polymarket: WalletPolymarketProfile tokensCreatedCount: Int tokensMigratedCount: Int } 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 isCashbackEnabled: Boolean 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 Token2022Extensions { scaledUiAmountConfig: Token2022ScaledUiAmountConfig } type B20Extensions { multiplier: String multiplierObservedAt: String pausedTransfer: Boolean pausedMint: Boolean pausedBurn: Boolean supplyCap: String } type TokenExtensions { token2022: Token2022Extensions b20: B20Extensions } 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 } 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 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!] } enum WalletAggregateBackfillState { BackfillComplete BackfillInProgress BackfillCanceled BackfillBlocked BackfillRequestReceived BackfillNotFound } type TokenWalletFilterResult { address: String! tokenAddress: String! networkId: Int! firstTransactionAt: Int lastTransactionAt: Int! labels: [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 tokenAmountBought1w: NumberFilter tokenAmountSold1w: NumberFilter amountBoughtUsd1w: NumberFilter amountSoldUsd1w: NumberFilter realizedProfitUsd1w: NumberFilter realizedProfitPercentage1w: NumberFilter avgHoldPeriodSec1w: NumberFilter buys1w: NumberFilter sells1w: NumberFilter tokenAmountBought30d: NumberFilter tokenAmountSold30d: NumberFilter amountBoughtUsd30d: NumberFilter amountSoldUsd30d: NumberFilter realizedProfitUsd30d: NumberFilter realizedProfitPercentage30d: NumberFilter avgHoldPeriodSec30d: NumberFilter buys30d: NumberFilter sells30d: NumberFilter tokenAmountBought1y: NumberFilter tokenAmountSold1y: NumberFilter amountBoughtUsd1y: NumberFilter amountSoldUsd1y: NumberFilter realizedProfitUsd1y: NumberFilter realizedProfitPercentage1y: NumberFilter avgHoldPeriodSec1y: NumberFilter buys1y: NumberFilter sells1y: 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] limit: Int offset: Int } ```
### Example Test this query in the Explorer → ```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 } } ``` **`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`](/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 ### Troubleshooting Tips 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. `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. `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. 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. `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. Use `rankings: [{ attribute: realizedProfitUsd30d, direction: DESC }]` to sort by profit. Combine with `filtersV2` to set minimum thresholds like `realizedProfitUsd30d: { gte: 1000 }`. ### Related Recipes * [Wallets](/recipes/wallets): Analyze wallet performance, discover top traders, and build portfolio views