Skip to main content
filterTokens is the workhorse query for token discovery on Codex. Almost every numeric attribute Codex computes per token is exposed here as both a filter input and a sortable ranking attribute, and most are evaluated over five rolling time windows (5m, 1h, 4h, 12h, and 24h) so you can build views tuned to any cadence. For continuously updating results, use our subscription version, onFilterTokensUpdated, which mirrors the same filter shape and pushes new matches as the underlying data changes on a polling basis.

​
Use this data for

  • Token screeners and trending feeds. Rank by volume24, change24, trendingScore24, or any of 100+ ranking attributes to power gainer boards and new-listing feeds, scoped to one network or every network at once. Narrow further by specific exchanges or specific launchpads.
  • Quality filtering for legit tokens. Combine profanity: false, potentialScam: false, and trendingIgnored: false with sensible liquidity and volume thresholds to surface real tokens and filter out scams, low-effort copies, stablecoins, and base assets.
  • Launchpad (memescope) filtering. Filter by launchpadProtocol, launchpadCompleted, launchpadMigrated, and migration timestamps to surface graduating tokens (Pump.fun, Bonk, Meteora DBC) the moment they hit the open market. For live-streamed launchpad data, combine with our onLaunchpadTokenEventBatch subscription.
  • Global fee data. Filter and sort on the full Global Fees Paid surface (totalFees{w}, feeToVolumeRatio{w}, poolFees24, builder tips, and more) to identify low-friction trading pairs or tokens where MEV dominates. See Global Fees Paid for the full field map.
  • Holder-quality and bot-detection screens. Use top10HoldersPercent, insiderHeldPercentage, bundlerHeldPercentage, sniperHeldPercentage, and walletAgeAvg to filter out concentrated supplies and bot-driven launches.
Every filter and field listed above is available in a single filterTokens call, so a full screening page can blend trending rankings, risk filters, launchpad status, fee economics, and holder analysis in one query rather than chaining multiple requests.
Some fields on this endpoint (asset, assetDeployments, organization) are powered by The Grid and will only be populated for established, verified tokens. See Verified Metadata in the Discover Tokens recipe for full details.
Boolean filtering: The filters input supports an optional boolFilter field that accepts and, or, and not operators (nestable up to 4 levels). Use it when you need different filter conditions for a subsets of tokens, such as per-network thresholds, or across different fields. For example, you might want different filter conditions depending on whether tokens are on Solana or Base. See Advanced Filtering for details.
Note on market cap: marketCap is fully diluted, price multiplied by total supply, and replaces the deprecated FDV field. For a circulating-supply-based value, use circulatingMarketCap.

​
Returns

​
TokenFilterConnection
TokenFilterConnection
See TokenFilterConnection

​
Arguments

​
filters
TokenFilters
A set of filters to apply. See TokenFilters
​
statsType
TokenPairStatisticsType
The type of statistics returned. Can be FILTERED or UNFILTERED. Default is UNFILTERED. See TokenPairStatisticsType
​
phrase
String
A phrase to search for. Can match a token or pair contract address or partially match a token’s name or symbol.
​
tokens
[String]
A list of token IDs (address:networkId) or addresses. Can be left blank to discover new tokens.
​
excludeTokens
[String]
A list of token IDs (address:networkId) to exclude from results
​
rankings
[TokenRanking]
A list of ranking attributes to apply. See TokenRanking
​
useAggregatedStats
Boolean
Flag to use aggregated token stats. Default is false.
​
limit
Int
The maximum number of tokens to return.
​
offset
Int
Where in the list the server should start when returning items. Use count+page from the previous query to request the next page of results.

​
Example

Test this query in the Explorer → 
{
  filterTokens(
    filters: {network: 1399811149, buyVolume24: {gt: 5000}, circulatingMarketCap: {gt: 1000000, lt: 20000000}}
    rankings: {attribute: trendingScore24, direction: DESC}
    limit: 25
  ) {
    results {
      buyVolume24
      sellVolume24
      circulatingMarketCap
      createdAt
      holders
      liquidity
      token {
        info {
          address
          name
          symbol
        }
        createdAt
        creatorAddress
        createTransactionHash
      }
      txnCount24
      walletAgeAvg
      walletAgeStd
    }
  }
}

​
Usage Guidelines

  • Response limit: 200 tokens per request
  • Use trendingScore24 or volume24 rankings for better results instead of createdAt
  • Apply quality filters such as volume and liquidity minimums to avoid low quality tokens
  • Use phrase parameter for searching by token name, symbol, or contract address
  • For exact symbol searches, use the $ prefix and combine phrase with volume/liquidity rankings to improve results
  • We recommend the use of useAggregatedStats: true to include aggregated token stats in results. This is not enabled by default.
Paginating results: filterTokens uses offset-based pagination, not a cursor. Set limit for the page size (up to 200 results per request) and offset to skip results. For the next page, set offset to your previous offset plus the number of results returned.

​
Troubleshooting Tips

Codex doesn’t expose a single “verified” or “spam” label, but several fields together cover this. Detection is automated, based on transaction flow patterns and the wallets interacting with each token. Defined.fi users can also flag tokens on the frontend (moderated daily), and confirmed flags are reflected in the isScam response field.Reading verification status (response fields):
  • isScam (boolean): isScam: false is Codex’s equivalent of a token being “verified.” Includes both algorithmic detection and confirmed user flags from Defined.fi. Available on token, tokens, filterTokens, and pairMetadata (via enhancedToken0 / enhancedToken1).
  • potentialScamReasons ([PotentialScamReason]): array of enum values explaining why a token was flagged. Possible values: MinimumLiquidity, LiquidityRugPull, SuspiciousWalletActivity, AbnormalBuyerRatio. Available on filterTokens results (TokenFilterResult) and filterPairs results (PairFilterResult).
Note: there is no isVerified or potentialScam response field. Both are filter inputs only.Filtering on filterTokens (input fields):
  • isVerified: true: only return verified tokens (excludes anything flagged as a scam).
  • potentialScam: true: return only tokens flagged as potential scams (useful for inspection).
  • potentialScam: false: explicitly exclude flagged tokens.
  • includeScams: true: include scam-flagged tokens in your results. Default is false, so by default filterTokens already excludes flagged tokens.
Detection isn’t perfect, but the defaults cut exposure significantly.Recommended for trending pages: Combine potentialScam: false with trendingIgnored: false to also exclude uninteresting tokens like stablecoins, network base tokens, and known rugs.
Check if the token has been flagged as a potential scam by adding includeScams: true to your filters. Also verify you’re searching the correct network and the token has trading activity (we only index tokens after swaps have occurred).
Add quality filters to improve results. We recommend setting minimum thresholds for volume, liquidity, holders, etc. Additionally, rank results by trendingScore24 or volume24 rather than liquidity to get more meaningful results. Experiment with filters that will suit your needs.
Response times are generally 60-150ms and it takes ~2-5 seconds to update the search cluster with new data. Contact our team if you are experiencing consistently delayed response times.
A null or undefined value for Mintable/Freezable will both return null through Codex. To differentiate between the two, we’ve included an isMintableValid and isFreezableValid field to show whether the null value returned is trustworthy or if we simply lack that information for the token (ie: undefined).
Avoid sorting by createdAt when using phrase search. Instead, rank by trendingScore24 or volume24 (those produce far more meaningful results). We index over 75+ Million tokens, so finding the right token from a one-word phrase requires sensible ranking. For exact symbol matches, prefix the phrase with $ (e.g. $PEPE); for contract address matches, pass the address directly.
These two timestamps represent different things and often won’t match:
  • createdAt (result level): on-chain creation timestamp of the token’s current top pair — not the token itself. For newly launched tokens the two usually coincide, but for older tokens with multiple pairs the current top pair may have been created later than both the token and its first pair. To see creation timestamps for every pair, use listPairsForToken.
  • token.createdAt (nested): Codex indexing time — when we first saw the token, not its on-chain creation. Typically 1-2s after pair creation for new tokens, but can be months or years later for historical tokens that predate our coverage of their source (e.g. pump.fun tokens created before we supported it).
You may also notice lastTransaction (the last on-chain trade) timestamped prior to token.createdAt. That’s expected — our indexing time can be later than the token’s last trade, and transfers or burns don’t update lastTransaction.
  • Discover Tokens: Build token discovery pages with trending data, filters, and search
  • Launchpads: Build a launchpad discovery view with real-time token lifecycle updates
  • Launchpad Lifecycle: Understand how tokens progress through launchpad stages from bonding curve to graduation