---
title: "Get Historical Token Screener (Beta)"
method: POST
path: "/api/v1beta1/token-screener/historical"
tags: ["Token Screener"]
---

# Get Historical Token Screener (Beta)

`POST /api/v1beta1/token-screener/historical`

**Beta — subject to breaking changes.**

Historical token screener data anchored to `to_date` over a `timeframe_days` window.

Output columns match the production token screener API response shape exactly.

When `trader_type='sm'` (or the deprecated `only_smart_money=True`),
volume/netflow/nof_traders fields reflect smart-money flows only;
`sm_label_filter` / `exclude_sm_labels_filter` narrow that cohort by
sub-label. When `trader_type` is `whale` or `public_figure`, those
fields reflect the corresponding notable-label cohort instead;
smart-money sub-label filters are not applicable in those modes.
`trader_type` overrides `only_smart_money` when both are set.

Use `exclude_sectors` to drop tokens whose sector tags include any of the
listed sectors (e.g. `["Stablecoin"]`).

## Request body

- TokenScreenerHistoricalRequest — Request model for the historical token screener endpoint. Returns token screener data anchored to to_date over a timeframe_days window. Output columns match the production token screener API response shape exactly. trader_type selects the wallet cohort whose flows drive the volume/netflow/nof_traders fields: - 'all' (default): all wallets. - 'sm': smart-money cohort. sm_label_filter / exclude_sm_labels_filter narrow the cohort by smart-money sub-label. - 'whale' / 'public_figure': notable-label cohort. Label-filter fields are not applicable in these modes and will be rejected.
  - `to_date` string, date, required — End date of the screener window
  - `timeframe_days` integer, required — Number of days in the screener window
  - `chains` TokenScreenerChain[], required — Chains to include (required, must be non-empty)
  - `sectors_filter` string[] — Sector filter. Empty list includes all sectors.
  - `exclude_sectors` string[] — Sectors to exclude. Empty list excludes nothing.
  - `only_smart_money` boolean — Deprecated: use trader_type instead. When True, aggregate smart money flows only. Volume/netflow/nof_traders fields reflect SM flows. Ignored when trader_type is provided.
  - `trader_type` 'all' | 'sm' | 'whale' | 'public_figure' | 'trending' | 'consistent_perps_winner' | 'high_winrate_hl_perps_trader' | 'predicted_winner' — Trader type filter for token screener.
  - `filters` TokenScreenerHistoricalFilters — Filters for the historical token screener endpoint. When trader_type='sm' (or only_smart_money=True), sm_label_filter restricts results to specific smart-money labels and exclude_sm_labels_filter removes them. Both lists are ignored in other trader_type modes.
    - `sm_label_filter` HistoricalSmartMoneyFilterType[] — Include smart-money labels (only applied when trader_type='sm'). Empty list includes all smart-money labels.
    - `exclude_sm_labels_filter` HistoricalSmartMoneyFilterType[] — Exclude smart-money labels (only applied when trader_type='sm'). Empty list excludes nothing.
    - `volume_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)
    - `buy_volume_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)
    - `sell_volume_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)
    - `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)
    - `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_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_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)
    - `fdv_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)
    - `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)
    - `liquidity_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)
    - `netflow_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)
    - `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)
    - `token_age_days` 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)
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `order_by` SortOrderTokenScreenerHistoricalSortField[] — Sort order. Defaults to netflow DESC. Only the first element is used.
    - `field` 'volume' | 'buy_volume' | 'sell_volume' | 'netflow' | 'price_change' | 'market_cap_usd' | 'fdv' | 'liquidity' | 'price_usd' | 'nof_traders' | 'nof_buyers' | 'nof_sellers' | 'nof_buys' | 'nof_sells' | 'token_age_days', required — Sortable fields for the historical token screener endpoint.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.
  - `apply_blacklist_filter` boolean — When True, exclude blacklisted addresses from the results. Defaults to True.

## Response `200`

Historical token screener data

- TokenScreenerHistoricalResponse — Response model for the historical token screener endpoint.
  - `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
  - `data` TokenScreenerHistoricalItem[], required — List of token screener records
    - `token_address` string, required — Token contract address
    - `token_symbol` string, required — Token symbol
    - `chain` string, required — Blockchain chain
    - `price_usd` number — Token price in USD at to_date
    - `price_change` number — Price change over the timeframe as a ratio
    - `market_cap_usd` number — Market cap in USD (falls back to FDV if zero)
    - `fdv` number — Fully diluted valuation in USD
    - `fdv_mc_ratio` number — FDV / market cap ratio
    - `volume` number — Total DEX volume (buy + sell) in USD over the timeframe
    - `buy_volume` number — Buy volume in USD over the timeframe
    - `sell_volume` number — Sell volume in USD over the timeframe
    - `netflow` number — Net flow (buy - sell) in USD over the timeframe
    - `inflow_fdv_ratio` number — Buy volume / FDV ratio
    - `outflow_fdv_ratio` number — Sell volume / FDV ratio
    - `token_age_days` integer — Days since token deployment as of to_date
    - `liquidity` number — Total on-chain liquidity in USD at to_date
    - `sectors` string[] — Token sector classifications

## 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)