token_discovery_screener

io.github.nansen-ai/nansen-mcp · Verify this server

Get comprehensive token screening data across multiple blockchain networks with advanced filtering. A maximum of 25 results per page are returned out of 1000s of tokens. Use the sorting and filtering options to narrow down the results. In a mixed spot + hyperliquid request, `page` applies to both the spot and perps sections. A maximum of 5 chains can be specified per request (excess chains are automatically trimmed). This tool helps with token discovery and finding trending tokens by combining different metrics: volume, liquidity, market cap, smart money activity, and token age. **IMPORTANT - Hyperliquid Special Case:** - Hyperliquid chain queries perpetual futures (perps), not spot tokens - When hyperliquid is mixed with other chains, two sections of up to 25 results each are returned - one for spot tokens and one for perps. - For perps, only these filters are supported: volume, buyVolume, sellVolume, openInterest, netflow, nofTraders, traderType - Additional orderBy fields for perps: openInterest, funding - Unsupported filters/orderBy will fallback to defaults INPUT EXAMPLES: # Find tokens which are going up in price. # Added some liquidity filter to remove spam and low quality tokens. ``` { "chains": ["ethereum", "solana", "bnb", "base"], "timeframe": "24h", "liquidity": {"from": 100000}, "nofTraders": {"from": 10}, "orderBy": "price_change", "orderByDirection": "desc" } ``` # Find top stablecoins by market cap ``` { "chains": ["ethereum", "solana", "bnb", "base"], "timeframe": "7d", "sectors": ["Stablecoin"], "orderBy": "market_cap_usd", "orderByDirection": "desc" } ``` # Find AI memecoins with high trading activity { "chains": ["ethereum", "solana", "bnb", "base"], "timeframe": "7d", "sectors": ["AI Meme"], "liquidity": {"from": 100000}, "volume": {"from": 1000000} } # Find DeFi lending tokens { "chains": ["ethereum", "solana", "bnb", "base"], "timeframe": "24h", "sectors": ["DeFi Lending (Money Markets)"], "netflow": {"from": 1000000} } # Find tokens which have a lot of buying activity (high nofBuyers and buyVolume) # Note that we added some filters to remove spam and low quality tokens. We added liquidity filter so that we only surface tokens which we can buy or sell. # We sort by `netflow` descending to get tokens with the most net buying activity. ``` { "chains": ["ethereum", "solana", "bnb", "base"], "timeframe": "24h", "liquidity": {"from": 100000}, "buyVolume": {"from": 1000000}, "marketCapUsd": {"from": 1000000}, "nofBuyers": {"from": 10}, "orderBy": "netflow", "orderByDirection": "desc" } ``` # Find Hyperliquid perps with high open interest and positive net flow ``` { "chains": ["hyperliquid"], "timeframe": "7d", "openInterest": {"from": 100000}, "volume": {"from": 1000000}, "netflow": {"from": 0}, "nofTraders": {"from": 10}, "orderBy": "netflow", "orderByDirection": "desc" } ``` WARNING: To avoid timeouts, it's recommended to: - Use 4 chains or less at a time (API tends to timeout with more chains) - Use shorter timeframes (e.g., 24h or 1h instead of 7d or 30d) Args: Returns: Comprehensive token metrics as markdown. Returns empty string if no tokens found. Columns returned: - **Token Address**: Token address (e.g., 0x1234567890123456789012345678901234567890) - **Symbol**: Token trading symbol (e.g., ETH, BTC, DOGE) - **Chain**: Blockchain network (ethereum, solana, polygon, etc.) - **Price USD**: Current token price in USD (currency formatted) - **Price Change**: Price change percentage over the date range (percentage, can be negative) - **Market Cap**: Current market capitalization (currency formatted) - **Fully Diluted Valuation (FDV)**: Market cap if all tokens were circulating (currency formatted) - **FDV/MC Ratio**: Ratio indicating how much supply is locked/vested (numeric, >1 means locked supply) - **USD Volume**: Total trading volume in USD (currency formatted) - **Buy USD Volume**: Total buy volume in USD (currency formatted) - **Sell USD Volume**: Total sell volume in USD (currency formatted) - **Net Flow USD**: Net flow (buys minus sells) in USD (currency formatted, can be negative) - **DEX Liquidity**: Available liquidity for trading (currency formatted) - **Inflow/FDV**: Inflow as percentage of FDV (percentage formatted) - **Outflow/FDV**: Outflow as percentage of FDV (percentage formatted) - **Token Age (Days)**: Days since token was first deployed - **Sectors**: List of token sectors/categories Hyperliquid perps columns (smart-money mode, when `onlySmartTradersAndFunds=true`): - **Net Position** (`LONG $X` / `SHORT $X` / `FLAT`): current net direction. Use this when answering long/short questions. - **Current Longs USD** / **Current Shorts USD**: gross notional on each side; sizing only, not direction. - **Net Position Change**: delta over the timeframe — can be positive while Net Position is still SHORT. Notes: - Positive Net Flow on spot tokens indicates more buying than selling - High FDV/MC Ratio suggests significant locked or vested tokens **Filtering Options** (filters parameter): - **Numeric Ranges**: volume, liquidity, marketCapUsd, netflow, tokenAgeDays, nofTraders, nofBuyers, nofSellers, nofBuys, nofSells, buyVolume, sellVolume, fdv, fdvMcRatio, inflowFdvRatio, outflowFdvRatio - **Categories**: sectors (e.g. ["AI", "Meme"]), includeSmartMoneyLabels - **Asset class toggles** (spot chains only, default false for both): includeStablecoins, includeNativeTokens. Set true only when the user asks for stablecoins/native tokens specifically. - **Trader Type**: traderType (string: "all", "sm", "whale", "public_figure") - Use "sm" ONLY when user explicitly asks for "smart money". - Use "whale" ONLY when user specifically asks for whales or large holders. - Use "public_figure" ONLY when user asks for KOLs or popular figures. - Data with "sm", "whale", and "public_figure" is sparse — "whale" and "public_figure" are even sparser than "sm". Pairing any of these with other filters (volume, liquidity, netflow) is likely to return no results. - Only pair traderType="sm/whale/public_figure" with other filters (volume, liquidity, netflow) if the user request explicitly requires it. - Instead of pairing this with other filters, you can rely on orderBy to sort by netflow, volume, liquidity, etc. **CRITICAL WARNING:** 'priceChange' is NOT a valid filter. You cannot filter for "tokens up > 10%". Use `orderBy="priceChange"` instead. **Sorting Options** (orderBy field): Available fields (use with orderByDirection: "asc" or "desc"): - **priceUsd**: Sort by token price - **priceChange**: Sort by price change percentage - **marketCapUsd**: Sort by market capitalization - **volume**: Sort by total trading volume - **buyVolume**: Sort by buy volume - **sellVolume**: Sort by sell volume - **netflow**: Sort by net flow (buys - sells) - **liquidity**: Sort by DEX liquidity - **nofTraders**: Sort by number of traders (Note: Fields like `tokenAgeDays` or `outflowFdvRatio` are for FILTERING only, not sorting) Default: orderBy="netflow", orderByDirection="desc"