> ## 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. # filterWallets > Returns a list of wallets based on a variety of filters. Reference for the filterWallets query in the Codex API: arguments, response fields, and usage. ## GraphQL ``` type Query { # Requires a Growth or Enterprise plan. filterWallets( input: FilterWalletsInput! ): WalletFilterConnection! } enum WalletCategory { NORMIE TOKEN_CREATOR EXCHANGE DEFI_EXCHANGE PAIR PAIR_TOKEN_HOLDER POOL_AUTHORITY STAKING_VAULT NOTORIOUS BURN LOCKER } enum WalletAggregateBackfillState { BackfillComplete BackfillInProgress BackfillCanceled BackfillBlocked BackfillRequestReceived BackfillNotFound } 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 } type WalletFilterResult { address: String! networkId: Int firstTransactionAt: Int lastTransactionAt: Int! labels: [String!]! identityLabels: [String!] tradeSourceIds: [String!] volumeUsd1d: String! volumeUsdAll1d: String! realizedProfitUsd1d: String! realizedProfitUsdExNative1d: String averageProfitUsdPerTrade1d: String! averageSwapAmountUsd1d: String! realizedProfitPercentage1d: Float! realizedProfitPercentageExNative1d: Float avgHoldPeriodSec1d: Float swaps1d: Int! swapsAll1d: Int! uniqueTokens1d: Int! winRate1d: Float! volumeUsd1w: String! volumeUsdAll1w: String! realizedProfitUsd1w: String! realizedProfitUsdExNative1w: String averageProfitUsdPerTrade1w: String! averageSwapAmountUsd1w: String! realizedProfitPercentage1w: Float! realizedProfitPercentageExNative1w: Float avgHoldPeriodSec1w: Float swaps1w: Int! swapsAll1w: Int! uniqueTokens1w: Int! winRate1w: Float! volumeUsd30d: String! volumeUsdAll30d: String! realizedProfitUsd30d: String! realizedProfitUsdExNative30d: String averageProfitUsdPerTrade30d: String! averageSwapAmountUsd30d: String! realizedProfitPercentage30d: Float! realizedProfitPercentageExNative30d: Float avgHoldPeriodSec30d: Float swaps30d: Int! swapsAll30d: Int! uniqueTokens30d: Int! winRate30d: Float! volumeUsd1y: String! volumeUsdAll1y: String! realizedProfitUsd1y: String! averageProfitUsdPerTrade1y: String! averageSwapAmountUsd1y: String! realizedProfitPercentage1y: Float! avgHoldPeriodSec1y: Float swaps1y: Int! swapsAll1y: Int! winRate1y: Float! scammerScore: Int botScore: Int tokensCreatedCount: Int tokensMigratedCount: Int category: WalletCategory nativeTokenBalance: String backfillState: WalletAggregateBackfillState wallet: Wallet } type WalletFilterConnection { results: [WalletFilterResult!]! count: Int! offset: Int! } input NumberFilter { gte: Float gt: Float lte: Float lt: Float } input WalletFilters { lastTransactionAt: NumberFilter firstTransactionAt: NumberFilter volumeUsd1d: NumberFilter volumeUsdAll1d: NumberFilter realizedProfitUsd1d: NumberFilter realizedProfitUsdExNative1d: NumberFilter averageProfitUsdPerTrade1d: NumberFilter averageSwapAmountUsd1d: NumberFilter realizedProfitPercentage1d: NumberFilter realizedProfitPercentageExNative1d: NumberFilter avgHoldPeriodSec1d: NumberFilter swaps1d: NumberFilter swapsAll1d: NumberFilter uniqueTokens1d: NumberFilter winRate1d: NumberFilter volumeUsd1w: NumberFilter volumeUsdAll1w: NumberFilter realizedProfitUsd1w: NumberFilter realizedProfitUsdExNative1w: NumberFilter averageProfitUsdPerTrade1w: NumberFilter averageSwapAmountUsd1w: NumberFilter realizedProfitPercentage1w: NumberFilter realizedProfitPercentageExNative1w: NumberFilter avgHoldPeriodSec1w: NumberFilter swaps1w: NumberFilter swapsAll1w: NumberFilter uniqueTokens1w: NumberFilter winRate1w: NumberFilter volumeUsd30d: NumberFilter volumeUsdAll30d: NumberFilter realizedProfitUsd30d: NumberFilter realizedProfitUsdExNative30d: NumberFilter averageProfitUsdPerTrade30d: NumberFilter averageSwapAmountUsd30d: NumberFilter realizedProfitPercentage30d: NumberFilter realizedProfitPercentageExNative30d: NumberFilter avgHoldPeriodSec30d: NumberFilter swaps30d: NumberFilter swapsAll30d: NumberFilter uniqueTokens30d: NumberFilter winRate30d: NumberFilter volumeUsd1y: NumberFilter volumeUsdAll1y: NumberFilter realizedProfitUsd1y: NumberFilter averageProfitUsdPerTrade1y: NumberFilter averageSwapAmountUsd1y: NumberFilter realizedProfitPercentage1y: NumberFilter avgHoldPeriodSec1y: NumberFilter swaps1y: NumberFilter swapsAll1y: NumberFilter winRate1y: NumberFilter scammerScore: NumberFilter botScore: NumberFilter ethosScore: NumberFilter tokensCreatedCount: NumberFilter tokensMigratedCount: NumberFilter categories: [WalletCategory!] networkId: Int nativeTokenBalance: NumberFilter hasTwitter: Boolean hasDiscord: Boolean hasTelegram: Boolean hasFarcaster: Boolean hasGithub: Boolean hasDisplayName: Boolean hasSocials: Boolean } enum WalletRankingAttribute { firstTransactionAt lastTransactionAt volumeUsd1d volumeUsdAll1d realizedProfitUsd1d realizedProfitUsdExNative1d averageProfitUsdPerTrade1d averageSwapAmountUsd1d realizedProfitPercentage1d realizedProfitPercentageExNative1d avgHoldPeriodSec1d swaps1d swapsAll1d uniqueTokens1d winRate1d volumeUsd1w volumeUsdAll1w realizedProfitUsd1w realizedProfitUsdExNative1w averageProfitUsdPerTrade1w averageSwapAmountUsd1w realizedProfitPercentage1w realizedProfitPercentageExNative1w avgHoldPeriodSec1w swaps1w swapsAll1w uniqueTokens1w winRate1w volumeUsd30d volumeUsdAll30d realizedProfitUsd30d realizedProfitUsdExNative30d averageProfitUsdPerTrade30d averageSwapAmountUsd30d realizedProfitPercentage30d realizedProfitPercentageExNative30d avgHoldPeriodSec30d swaps30d swapsAll30d uniqueTokens30d winRate30d volumeUsd1y volumeUsdAll1y realizedProfitUsd1y averageProfitUsdPerTrade1y averageSwapAmountUsd1y realizedProfitPercentage1y avgHoldPeriodSec1y swaps1y swapsAll1y winRate1y nativeTokenBalance scammerScore botScore ethosScore } enum RankingDirection { ASC DESC } input WalletRanking { attribute: WalletRankingAttribute direction: RankingDirection } input FilterWalletsInput { filters: WalletFilters wallets: [String] phrase: String excludeLabels: [String] includeLabels: [String] includeTradeSourceIds: [String] excludeTradeSourceIds: [String] rankings: [WalletRanking] limit: Int offset: Int } ``` ### Example [Test this query in the Explorer →](https://docs.codex.io/explore.md) ```graphql theme={null} { filterWallets( input: { filters: { networkId: 1399811149 realizedProfitUsd1w: { gte: 10000 } winRate1w: { gte: 30 } swaps1w: { gte: 100 } } rankings: [{ attribute: realizedProfitUsd1w, direction: DESC }] limit: 10 } ) { results { address labels lastTransactionAt firstTransactionAt volumeUsd1w realizedProfitUsd1w realizedProfitPercentage1w winRate1w swaps1w uniqueTokens1w } count offset } } ``` ### Usage Guidelines * Use `filters` to narrow results by metrics like `realizedProfitUsd`, `winRate`, `volumeUsd`, `swaps`, etc. — available for multiple time periods: `1d`, `1w`, `30d`, `1y` * Filters use `NumberFilter` with `gte`, `gt`, `lte`, `lt` operators for range queries * Use `rankings` to sort results by any metric — specify `attribute` and `direction` (`ASC` or `DESC`) * Filter by `networkId` to scope results to a specific chain (e.g., 1399811149 for Solana) * Use `includeLabels` or `excludeLabels` to filter by wallet classifications like `SMART_TRADER_TOKENS_OVER_TWO_DAYS_OLD`, `WEALTHY`, `SNIPER` * Use `limit` and `offset` for pagination — the response includes `count` to help with page navigation. `limit` accepts a maximum of **100** wallets per request; page through larger result sets by increasing `offset` * Pass a list of `wallets` to filter results to specific wallet addresses — a maximum of **100** addresses per request * Requests are counted per query response, not per wallet, so raising `limit` or passing more addresses in `wallets` does not increase your request cost — batching up to 100 wallets per request is the most efficient approach (see [Rate Limits](https://docs.codex.io/concepts/rate-limits.md)) * Wins, losses, and `winRate` only count a closed position when its realized profit or loss is greater than $1 USD. The threshold applies to the profit or loss amount, not the trade size, so positions with a sub-$1 profit or loss are excluded and a wallet whose trades are all under \$1 will show a `winRate` of 0 * Use `includeTradeSourceIds` / `excludeTradeSourceIds` to filter by the apps a wallet trades through, and read them back from `tradeSourceIds`. Means "trades through", never "is owned by" — 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 filterWallets vs filterTokenWallets? > > Use `filterWallets` when you want to discover wallets based on their overall trading performance across all tokens — great for finding top traders on a network. Use `filterTokenWallets` when you want to find wallets that have traded a specific token and see their stats for that token only. > [accordion] What time periods are available for metrics? > > All metrics are available across four time periods: `1d` (24 hours), `1w` (7 days), `30d` (30 days), and `1y` (1 year). Append the period to the metric name, e.g., `realizedProfitUsd1w`, `winRate30d`, `volumeUsd1y`. > [accordion] What do the wallet labels mean? > > Labels classify wallet behavior: `SMART_TRADER_TOKENS_OVER_TWO_DAYS_OLD` indicates $7.5K+ profit on established tokens, `SNIPER` indicates $3K+ profit on tokens launched within 1 hour, `WEALTHY`/`MEGA_WEALTHY` indicate high asset holdings ($1M+/$10M+). Use `excludeLabels` to filter out bots or known patterns. > [accordion] How does winRate work? > > `winRate` is a percentage (0–100) representing the portion of profitable trades. A `winRate1w` of 52 means 52% of trades in the last week were profitable. Use filters like `winRate1w: { gte: 50 }` to find wallets with above-average win rates. Only closed positions with a realized profit or loss greater than $1 USD count toward wins, losses, and `winRate`. The threshold is on the profit or loss amount, not the trade size, so a wallet whose positions all have a sub-$1 profit or loss will show a `winRate` of 0. > [accordion] What's the difference between volumeUsd and volumeUsdAll? > > `volumeUsd` only counts volume from tokens where we have a reliable USD price. `volumeUsdAll` includes volume from all tokens, even those without reliable pricing. Use `volumeUsd` for more conservative figures. ### 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.