> ## 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. # filterPairs > Returns a list of pairs based on a variety of filters. Reference for the filterPairs query in the Codex API: arguments, response fields, and usage. ## GraphQL ``` type Query { filterPairs( filters: PairFilters statsType: TokenPairStatisticsType phrase: String pairs: [String] matchTokens: PairFilterMatchTokens rankings: [PairRanking] limit: Int offset: Int ): PairFilterConnection } type FilterExchange { address: String! id: String! name: String exchangeVersion: String iconUrl: String networkId: Int! tradeUrl: String } 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 } type PooledTokenValues { token0: String token1: String invalidReserves: Boolean! } type CurrencyUnits { currency0: String! currency1: String! decimals0: Int! decimals1: Int! } type UniswapV4Data { uniswapV4HookAddress: String isToken0NetworkToken: Boolean isDynamicFee: Boolean currencyUnits: CurrencyUnits type: String! } type ArenaTradeData { tokenId: String type: String! } type PumpData { creator: String type: String! } union ProtocolData = UniswapV4Data | ArenaTradeData | PumpData type PairProtocolCustomData { uniswapV4HookAddress: String } type Pair { address: String! exchangeHash: String! fee: Int id: String! networkId: Int! protocol: String tickSpacing: Int token0: String! token1: String! createdAt: Int token0Data: EnhancedToken token1Data: EnhancedToken pooled: PooledTokenValues virtualPooled: PooledTokenValues currencyUnits: CurrencyUnits protocolData: ProtocolData } enum PotentialScamReason { MinimumLiquidity LiquidityUnknown LiquidityRugPull SuspiciousWalletActivity AbnormalBuyerRatio DevConcentration SniperConcentration BundledLaunch ForeignVenueLaunch SellerHub } type PairFilterResult { createdAt: Int lastTransaction: Int buyCount1: Int buyCount4: Int buyCount12: Int buyCount24: Int exchange: FilterExchange highPrice1: String highPrice4: String highPrice12: String highPrice24: String liquidity: String lockedLiquidityPercentage: Float! liquidityToken: String quoteToken: String lowPrice1: String lowPrice4: String lowPrice12: String lowPrice24: String marketCap: String pair: Pair price: String priceScale: String priceChange1: String priceChange4: String priceChange12: String priceChange24: String volumeChange1: String volumeChange4: String volumeChange12: String volumeChange24: String sellCount1: Int sellCount4: Int sellCount12: Int sellCount24: Int token0: EnhancedToken token1: EnhancedToken txnCount1: Int txnCount4: Int txnCount12: Int txnCount24: Int uniqueBuys1: Int uniqueBuys4: Int uniqueBuys12: Int uniqueBuys24: Int uniqueSells1: Int uniqueSells4: Int uniqueSells12: Int uniqueSells24: Int uniqueTransactions1: Int uniqueTransactions4: Int uniqueTransactions12: Int uniqueTransactions24: Int volumeUSD1: String volumeUSD4: String volumeUSD12: String volumeUSD24: String buyVolumeUSD1: String buyVolumeUSD12: String buyVolumeUSD24: String buyVolumeUSD4: String sellVolumeUSD1: String sellVolumeUSD12: String sellVolumeUSD24: String sellVolumeUSD4: String walletAgeAvg: String walletAgeStd: String swapPct1dOldWallet: String swapPct7dOldWallet: String potentialScamReasons: [PotentialScamReason] poolFeeBps: Float dynamicFee: Boolean riskVerdict: RiskVerdict riskScore: Float riskFlaggedAt: Int riskAnalyzedAt: Int riskCoverage: RiskAnalysisCoverage riskReasons: [RiskReasonCode!] riskBuyTax: Float riskSellTax: Float } type PairFilterConnection { results: [PairFilterResult] count: Int offset: Int } input NumberFilter { gte: Float gt: Float lte: Float lt: Float } input PairFilters { createdAt: NumberFilter lastTransaction: NumberFilter buyCount1: NumberFilter buyCount12: NumberFilter buyCount24: NumberFilter buyCount4: NumberFilter exchangeAddress: [String] highPrice1: NumberFilter highPrice12: NumberFilter highPrice24: NumberFilter highPrice4: NumberFilter liquidity: NumberFilter lockedLiquidityPercentage: NumberFilter lowPrice1: NumberFilter lowPrice12: NumberFilter lowPrice24: NumberFilter lowPrice4: NumberFilter network: [Int] price: NumberFilter priceChange1: NumberFilter priceChange12: NumberFilter priceChange24: NumberFilter priceChange4: NumberFilter volumeChange1: NumberFilter volumeChange4: NumberFilter volumeChange12: NumberFilter volumeChange24: NumberFilter sellCount1: NumberFilter sellCount12: NumberFilter sellCount24: NumberFilter sellCount4: NumberFilter tokenAddress: [String] txnCount1: NumberFilter txnCount12: NumberFilter txnCount24: NumberFilter txnCount4: NumberFilter uniqueBuys1: NumberFilter uniqueBuys12: NumberFilter uniqueBuys24: NumberFilter uniqueBuys4: NumberFilter uniqueSells1: NumberFilter uniqueSells12: NumberFilter uniqueSells24: NumberFilter uniqueSells4: NumberFilter uniqueTransactions1: NumberFilter uniqueTransactions12: NumberFilter uniqueTransactions24: NumberFilter uniqueTransactions4: NumberFilter volumeUSD1: NumberFilter volumeUSD12: NumberFilter volumeUSD24: NumberFilter volumeUSD4: NumberFilter buyVolumeUSD1: NumberFilter buyVolumeUSD12: NumberFilter buyVolumeUSD24: NumberFilter buyVolumeUSD4: NumberFilter sellVolumeUSD1: NumberFilter sellVolumeUSD12: NumberFilter sellVolumeUSD24: NumberFilter sellVolumeUSD4: NumberFilter potentialScam: Boolean trendingIgnored: Boolean isTestnet: Boolean hookAddress: [String] poolFeeBps: NumberFilter dynamicFee: Boolean riskVerdicts: [RiskVerdict!] riskCoverages: [RiskAnalysisCoverage!] riskReasons: [RiskReasonCode!] riskScore: NumberFilter riskFlaggedAt: NumberFilter walletAgeAvg: NumberFilter walletAgeStd: NumberFilter swapPct1dOldWallet: NumberFilter swapPct7dOldWallet: NumberFilter } enum TokenPairStatisticsType { FILTERED UNFILTERED } input PairFilterMatchTokens { token0: String token1: String } enum PairRankingAttribute { poolFeeBps riskScore riskFlaggedAt createdAt lastTransaction buyCount1 buyCount4 buyCount12 buyCount24 highPrice1 highPrice4 highPrice12 highPrice24 liquidity lockedLiquidityPercentage lowPrice1 lowPrice4 lowPrice12 lowPrice24 marketCap price priceChange1 priceChange4 priceChange12 priceChange24 volumeChange1 volumeChange4 volumeChange12 volumeChange24 sellCount1 sellCount4 sellCount12 sellCount24 trendingScore trendingScore5m trendingScore1 trendingScore4 trendingScore12 trendingScore24 txnCount1 txnCount4 txnCount12 txnCount24 uniqueBuys1 uniqueBuys4 uniqueBuys12 uniqueBuys24 uniqueSells1 uniqueSells4 uniqueSells12 uniqueSells24 uniqueTransactions1 uniqueTransactions4 uniqueTransactions12 uniqueTransactions24 volumeUSD1 volumeUSD4 volumeUSD12 volumeUSD24 buyVolumeUSD1 buyVolumeUSD4 buyVolumeUSD12 buyVolumeUSD24 sellVolumeUSD1 sellVolumeUSD4 sellVolumeUSD12 sellVolumeUSD24 walletAgeAvg walletAgeStd swapPct1dOldWallet swapPct7dOldWallet } enum RankingDirection { ASC DESC } input PairRanking { attribute: PairRankingAttribute direction: RankingDirection } ``` ### Example [Test this query in the Explorer →](https://docs.codex.io/explore.md) ```graphql theme={null} { filterPairs( filters: {network: 1399811149} phrase: "PUMP" limit: 10 ) { results { buyCount12 highPrice24 liquidity lowPrice24 marketCap price priceChange24 volumeUSD24 pair { token0Data { address name symbol } token1Data { address name symbol } } } } } ``` ### Usage Guidelines * Response limit: 200 pairs per request * Use `phrase` parameter for searching by token name, symbol, or pair address * Apply quality filters such as volume and liquidity minimums to avoid low quality pairs * Results include pre-computed stats like `priceChange24`, `volumeUSD24`, `buyCount12`, etc. for easy display ### Troubleshooting Tips > [accordion] When should I use filterPairs vs filterTokens? > > Use `filterPairs` when you want to discover or search trading pairs and need pair-specific data like which tokens are paired together. Use `filterTokens` when you want to discover tokens and need token-level aggregate data across all their pairs. > [accordion] How do I get the token I care about from pair results? > > Each pair has `token0Data` and `token1Data`. One will be your target token, the other is typically a quote token (like USDC, WETH, or SOL). Check the `address` field to identify which is which, or filter by a known quote token address. > [accordion] Results are returning too many low-quality pairs > > Add quality filters to improve results. Set minimum thresholds for `liquidity` and `volumeUSD24` to filter out inactive or low-liquidity pairs. > [accordion] How do I filter pairs for a specific token? > > Use the `token0` or `token1` filter with the token address, or use `phrase` to search by token name/symbol. You can also filter by `network` to narrow results to a specific chain. > [accordion] Can I fetch pair metadata for multiple pool addresses? > > Yes — use `filterPairs` for this. It accepts pool addresses via the `phrase` parameter or filters and returns metadata for many pairs in a single call. > [accordion] How do I find the pool with the highest liquidity for a token? > > Use `filterPairs` with a phrase containing the token's address (formatted as `address:networkId`) and rank by liquidity descending: > > ```graphql theme={null} > filterPairs( > phrase: "TOKEN_ADDRESS:1" > rankings: [{ attribute: liquidity, direction: DESC }] > ) > ``` > > The `liquidity` value represents the USD value of the base token (e.g. ETH or a stablecoin) backing the pair. Price change metrics across multiple timeframes are available on both `filterPairs` and `filterTokens`. > [accordion] How does `phrase` search work for pairs? > > `phrase` matches pair addresses or the symbols/names of the tokens in the pair. As with `filterTokens`, avoid sorting by `createdAt` for phrase searches — use `liquidity`, `volumeUSD24`, or `trendingScore24` for more meaningful rankings. See [filterTokens — How does `phrase` search work?](https://docs.codex.io/api-reference/queries/filtertokens) for the same gotcha at the token level. ### Related Recipes * [Discover Tokens](https://docs.codex.io/recipes/discover-tokens.md): Build token discovery pages with trending data, filters, and search This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.