---
title: "Retrieve token screener data"
method: POST
path: "/api/v1/token-screener"
tags: ["Token Screener"]
---

# Retrieve token screener data

`POST /api/v1/token-screener`

Discover and screen tokens across multiple blockchains with advanced filtering capabilities. This endpoint helps identify trending tokens, new launches, and smart money movements by combining metrics like volume, liquidity, market cap, and trading activity.

**What it helps to answer:**

1. **Which tokens are experiencing significant smart money activity across different chains?**
2. **How do market metrics (price, volume, liquidity) correlate with holder behavior and smart money movements?**
3. **What tokens show strong fundamentals in terms of holder distribution and trading patterns?**
4. **Which emerging tokens are attracting fresh wallet inflows while maintaining healthy smart money participation?**

## Request body

- TokenScreenerRequest — Request model for Token Screener endpoint. Either 'timeframe' (recommended) or 'date' (deprecated) must be provided.
  - `chains` TokenScreenerChain[], required — List of blockchain chains to filter by
  - `timeframe` '5m' | '10m' | '1h' | '6h' | '24h' | '7d' | '30d' — Token screener timeframe options. Defines the time window for token screening data. Each timeframe corresponds to different data granularity and retention periods. Matches the timeframe options in the Nansen token-screener widget.
  - `date` DateRange — Date range model matching the API schema.
    - `from` string — Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
    - `to` string — End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `filters` TokenScreenerFilters — Filters for token screener endpoints. These filters control which tokens are included in the screening results based on various criteria.
    - `token_address` union — Token address or symbol filter
      - string
      - string[]
    - `token_symbol` union — Token symbol filter
      - string
      - string[]
    - `only_smart_money` boolean — Deprecated: use trader_type instead. Whether to only include smart money tokens
    - `trader_type` 'all' | 'sm' | 'whale' | 'public_figure' | 'trending' | 'consistent_perps_winner' | 'high_winrate_hl_perps_trader' | 'predicted_winner' — Trader type filter for token screener.
    - `sectors` string[] — Token sectors to include, as bare sector names (e.g. DeFi, Gaming). Note: this differs from the perp screener's sectors_filter, which uses category:subcategory values.
    - `exclude_sectors` string[] — Token sectors to exclude, as bare sector names.
    - `token_age_days` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `market_cap_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `liquidity` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `price_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `price_change` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `fdv` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `fdv_mc_ratio` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `nof_buyers` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
    - `nof_traders` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
    - `nof_sellers` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
    - `nof_buys` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
    - `nof_sells` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
    - `buy_volume` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `sell_volume` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `volume` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `netflow` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `inflow_fdv_ratio` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `outflow_fdv_ratio` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `include_stablecoins` boolean — Whether to include stablecoins in token screener results. Default true preserves current behavior. Set to false to exclude USDC, USDT, DAI, and other major stablecoins.
    - `include_smart_money_labels` SmartMoneyFilterType[] — Include smart money labels
    - `exclude_smart_money_labels` SmartMoneyFilterType[] — Exclude smart money labels
  - `order_by` SortOrderTokenScreenerSortField[] — Custom sort order to override the endpoint's default ordering. Examples: - [{"field": "buy_volume", "direction": "DESC"}] - Sort by buy volume descending - [{"field": "price_change", "direction": "DESC"}] - Sort by price change descending
    - `field` 'chain' | 'token_address' | 'token_symbol' | 'market_cap_usd' | 'volume' | 'liquidity' | 'nof_traders' | 'nof_buyers' | 'nof_sellers' | 'nof_buys' | 'nof_sells' | 'price_change' | 'price_usd' | 'netflow' | 'buy_volume' | 'sell_volume' | 'fdv' | 'fdv_mc_ratio' | 'inflow_fdv_ratio' | 'outflow_fdv_ratio' | 'token_age_days', required — Enum for sortable fields in token screener.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

Token screening data

- TokenScreenerResponse — Response model for token screener endpoint.
  - `data` union[], required — List of token screening results
    - union
      - TokenScreenerDataDefault — Data model for token screener results with non-default query (excludes trader-related columns).
        - `chain` string, required — The blockchain network on which the token is deployed.
        - `token_address` string, required — Address of token
        - `token_symbol` string, required — The symbol of the token.
        - `token_age_days` number — Number of days since token deployment.
        - `token_age_hours` number — Number of hours since token deployment.
        - `token_deployment_date` string — ISO 8601 timestamp of token deployment.
        - `market_cap_usd` number — Market capitalization in USD.
        - `liquidity` number — Total on-chain liquidity in USD.
        - `price_usd` number — Price of the token
        - `price_change` number — Price change percentage from the previous period.
        - `fdv` number — Fully Diluted Valuation in USD.
        - `fdv_mc_ratio` number — Ratio of Fully Diluted Valuation to Market Cap.
        - `buy_volume` number — Total buy volume in USD.
        - `inflow_fdv_ratio` number — Ratio of inflow to Fully Diluted Valuation.
        - `outflow_fdv_ratio` number — Ratio of outflow to Fully Diluted Valuation.
        - `sell_volume` number — Total sell volume in USD.
        - `volume` number — Total trading volume in USD.
        - `netflow` number — Net flow (buy_volume - sell_volume) in USD.
      - TokenScreenerDataSmartMoneyDefault — Data model for smart money token screener with default query. Includes nof_traders but excludes other trader-related columns (nof_buyers, nof_sellers, nof_buys, nof_sells).
        - `chain` string, required — The blockchain network on which the token is deployed.
        - `token_address` string, required — Address of token
        - `token_symbol` string, required — The symbol of the token.
        - `token_age_days` number — Number of days since token deployment.
        - `token_age_hours` number — Number of hours since token deployment.
        - `token_deployment_date` string — ISO 8601 timestamp of token deployment.
        - `market_cap_usd` number — Market capitalization in USD.
        - `liquidity` number — Total on-chain liquidity in USD.
        - `price_usd` number — Price of the token
        - `price_change` number — Price change percentage from the previous period.
        - `fdv` number — Fully Diluted Valuation in USD.
        - `fdv_mc_ratio` number — Ratio of Fully Diluted Valuation to Market Cap.
        - `nof_traders` integer — Total number of unique traders.
        - `buy_volume` number — Total buy volume in USD.
        - `inflow_fdv_ratio` number — Ratio of inflow to Fully Diluted Valuation.
        - `outflow_fdv_ratio` number — Ratio of outflow to Fully Diluted Valuation.
        - `sell_volume` number — Total sell volume in USD.
        - `volume` number — Total trading volume in USD.
        - `netflow` number — Net flow (buy_volume - sell_volume) in USD.
      - TokenScreenerDataNonDefault — Data model for token screener results with non-default query (includes all columns).
        - `chain` string, required — The blockchain network on which the token is deployed.
        - `token_address` string, required — Address of token
        - `token_symbol` string, required — The symbol of the token.
        - `token_age_days` number — Number of days since token deployment.
        - `token_age_hours` number — Number of hours since token deployment.
        - `token_deployment_date` string — ISO 8601 timestamp of token deployment.
        - `market_cap_usd` number — Market capitalization in USD.
        - `liquidity` number — Total on-chain liquidity in USD.
        - `price_usd` number — Price of the token
        - `price_change` number — Price change percentage from the previous period.
        - `fdv` number — Fully Diluted Valuation in USD.
        - `fdv_mc_ratio` number — Ratio of Fully Diluted Valuation to Market Cap.
        - `nof_buyers` integer — Number of unique buyers.
        - `nof_traders` integer — Total number of unique traders.
        - `nof_sellers` integer — Number of unique sellers.
        - `nof_buys` integer — Total number of buy transactions.
        - `nof_sells` integer — Total number of sell transactions.
        - `buy_volume` number — Total buy volume in USD.
        - `inflow_fdv_ratio` number — Ratio of inflow to Fully Diluted Valuation.
        - `outflow_fdv_ratio` number — Ratio of outflow to Fully Diluted Valuation.
        - `sell_volume` number — Total sell volume in USD.
        - `volume` number — Total trading volume in USD.
        - `netflow` number — Net flow (buy_volume - sell_volume) in USD.
  - `pagination` PaginationInfo, required — Pagination information for API responses.
    - `page` integer — Current page number
    - `per_page` integer — Number of records per page
    - `is_last_page` boolean — Whether this is the last page

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)