Historical Token Screener

Get Historical Token Screener (Beta)

post

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"]).

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

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_datestring · dateRequired

End date of the screener window

Example: 2025-06-01

timeframe_daysinteger · min: 1 · max: 365Required

Number of days in the screener window

Example: 7

sectors_filterstring[]Optional

Sector filter. Empty list includes all sectors.

Example: ["DeFi"]

exclude_sectorsstring[]Optional

Sectors to exclude. Empty list excludes nothing.

Example: ["Stablecoin"]

only_smart_moneybooleanOptionalDeprecated

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.

Default: false

trader_typeany ofOptional

Filter by trader type. Overrides only_smart_money when provided. Supported values: all, sm, whale, public_figure.

Example: whale

string · enumOptional

Trader type filter for token screener.

Possible values:

filtersany ofOptional

Optional filters applied server-side

apply_blacklist_filterbooleanOptional

When True, exclude blacklisted addresses from the results. Defaults to True.

Default: trueExample: true

Responses

200

Historical token screener data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

402

Payment Required

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1beta1/token-screener/historical

HTTPcURLJavaScriptPython

POST /api/v1beta1/token-screener/historical HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 833

{
  "to_date": "2025-06-01",
  "timeframe_days": 7,
  "chains": [
    "ethereum"
  ],
  "sectors_filter": [
    "DeFi"
  ],
  "exclude_sectors": [
    "Stablecoin"
  ],
  "trader_type": "whale",
  "filters": {
    "sm_label_filter": [
      "Smart Trader"
    ],
    "exclude_sm_labels_filter": [
      "Fund"
    ],
    "volume_usd": {
      "max": 100000,
      "min": 1000
    },
    "buy_volume_usd": {
      "min": 1000
    },
    "sell_volume_usd": {
      "min": 1000
    },
    "market_cap_usd": {
      "min": 1000000
    },
    "nof_traders": {
      "min": 10
    },
    "nof_buyers": {
      "min": 5
    },
    "nof_sellers": {
      "min": 5
    },
    "nof_buys": {
      "min": 10
    },
    "nof_sells": {
      "min": 10
    },
    "fdv_usd": {
      "min": 1000000
    },
    "fdv_mc_ratio": {
      "max": 5,
      "min": 1
    },
    "liquidity_usd": {
      "min": 100000
    },
    "netflow_usd": {
      "max": 100000,
      "min": -100000
    },
    "inflow_fdv_ratio": {
      "min": 0.01
    },
    "outflow_fdv_ratio": {
      "min": 0.01
    },
    "token_age_days": {
      "max": 365,
      "min": 30
    }
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "order_by": [
    {
      "field": "volume",
      "direction": "ASC"
    }
  ],
  "apply_blacklist_filter": true
}

{
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  },
  "data": [
    {
      "token_address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
      "token_symbol": "AAVE",
      "chain": "ethereum",
      "price_usd": 85.5,
      "price_change": 0.12,
      "market_cap_usd": 1200000000,
      "fdv": 1500000000,
      "fdv_mc_ratio": 1.25,
      "volume": 50000000,
      "buy_volume": 28000000,
      "sell_volume": 22000000,
      "netflow": 6000000,
      "inflow_fdv_ratio": 0.019,
      "outflow_fdv_ratio": 0.015,
      "token_age_days": 1460,
      "liquidity": 8000000,
      "sectors": [
        "DeFi",
        "Lending"
      ]
    }
  ]
}