Skip to main content

Don't have an API key yet?

Sign-up to Moralis to get your free API key and start building today.

Get Your Free API Key

Filtered Tokens API Tutorials

For the complete API reference, please see the Get Filtered Tokens API documentation and for FAQ, please see the Filtered Tokens API FAQ.

The Filtered Tokens API enables you to discover and analyze tokens across multiple blockchains using powerful filtering, sorting, and metric selection capabilities.

What is the Filtered Tokens API?​

It's a POST endpoint (/api/v2.2/discovery/tokens) that allows you to:

  • Search tokens across multiple chains in one request
  • Filter by various metrics like volume, market cap, and holder activity
  • Sort results by any supported metric
  • Analyze time-based changes in token performance

Supported Chains​

Query tokens across these blockchains:

  • eth - Ethereum
  • solana - Solana
  • base - Base
  • arbitrum - Arbitrum
  • polygon - Polygon
  • binance - BNB Chain
  • avalanche - Avalanche
  • optimism - Optimism
  • ronin - Ronin
  • linea - Linea
  • fantom - Fantom
  • pulse - PulseChain

Key Metrics​

Time-Based Metrics (require timeFrame)​

  • volumeUsd - Trading volume
  • usdPricePercentChange - Price change percentage
  • liquidityChange / liquidityChangeUSD - Liquidity changes
  • holders - Change in holder count
  • buyers / sellers / netBuyers - Trading activity
  • experiencedBuyers / experiencedSellers / netExperiencedBuyers - Smart money activity

Snapshot Metrics (current state, no timeFrame)​

  • marketCap - Market capitalization
  • fullyDilutedValuation - FDV
  • totalLiquidityUsd - Total liquidity
  • totalHolders - Current holder count
  • securityScore - Token security (0-100)
  • tokenAge - Days since creation
  • Holder distribution: holdersWhale, holdersShark, etc.
  • Holder supply concentration: holderSupplyPercentTop10, etc.
  • Acquisition methods: holdersBySwap, holdersByTransfer, holdersByAirdrop

Time Frames​

Available time periods for analysis:

  • tenMinutes, thirtyMinutes
  • oneHour, fourHours, twelveHours
  • oneDay, oneWeek, oneMonth

Basic Request Structure​

{
  "chains": ["eth", "base"],
  "filters": [
    {
      "metric": "marketCap",
      "gt": 1000000
    },
    {
      "metric": "volumeUsd",
      "timeFrame": "oneDay",
      "gt": 100000
    }
  ],
  "sortBy": {
    "metric": "volumeUsd",
    "timeFrame": "oneDay",
    "type": "DESC"
  },
  "limit": 50
}

Filter Operators​

  • gt - Greater than
  • lt - Less than
  • Can combine both for ranges

Categories​

Include or exclude token categories:

{
  "categories": {
    "include": ["meme", "gaming"],
    "exclude": ["stablecoin", "wrapped"]
  }
}

Always include these to avoid low-quality tokens:

{
  "filters": [
    { "metric": "marketCap", "gt": 0, "lt": 5000000000000 },
    { "metric": "totalLiquidityUsd", "gt": 500 },
    { "metric": "volumeUsd", "timeFrame": "oneDay", "gt": 1000 }
  ]
}

Authentication​

Required header:

X-API-Key: YOUR_API_KEY

Limitations​

  • Maximum 100 tokens per request
  • No pagination support
  • Use filters to narrow results

Data Updates​

  • Most metrics update every 10 seconds
  • Holder distribution metrics may have up to 5-minute delay for very active tokens

Common Use Cases​

  1. Trending Tokens - High volume and buyer activity
  2. Top Gainers/Losers - Biggest price movements
  3. Blue Chip Tokens - Large cap, established tokens
  4. Smart Money Tracking - Following experienced buyers
  5. New Token Discovery - Recently launched tokens

Next Steps​

Explore our tutorials to see what you can do with the Filtered Tokens API: