Token Screener

Set filters.include_native_tokens to true to include native, wrapped-native, LST, and LRT assets. The default is false. See Native Tokens for representation and coverage limitations.

Data Retention Limits

This endpoint only supports recent data:

• Minute Granularity: Last 130 minutes

• Hourly Granularity: Last 50 hours

• Daily Granularity: Last 50 days

Historical Analysis Not Supported:

• to_date must be within 5 minutes of current time

• Historical snapshots (e.g., "show me January 2024") are not available

Data Freshness & Historical Coverage

For data freshness and historical coverage, see Data Coverage by Chain; this endpoint follows it except where noted below.

• A live, point-in-time screener: results reflect data as of request time rather than a historical window; no response cache.

Retrieve token screener data

post

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?

Authorizations

apikeystringRequired

API key for authentication

Body

Request model for Token Screener endpoint.

Either 'timeframe' (recommended) or 'date' (deprecated) must be provided.

timeframeany ofOptional

Required (unless using deprecated 'date' parameter).

Time window for token screening data.

Available timeframes and their data characteristics:

• 5m: Last 5 minutes (minute-level granularity, 2-hour retention)
• 10m: Last 10 minutes (minute-level granularity, 2-hour retention)
• 1h: Last 1 hour (minute-level granularity, 2-hour retention)
• 6h: Last 6 hours (hourly granularity, 2-day retention)
• 24h: Last 24 hours (hourly granularity, 2-day retention)
• 7d: Last 7 days (daily granularity, 2-month retention)
• 30d: Last 30 days (daily granularity, 2-month retention)

Cannot be used together with 'date'.

Example: 24h

string · enumOptional

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.

Possible values:

dateany ofOptionalDeprecated

DEPRECATED: Use 'timeframe' instead. It offers better reliability and performance.

Required only if 'timeframe' is not provided.

Custom date range for the token screener. The granularity is automatically determined from the date range:

• ≤ 1 hour: minute-level data (limited to last 2 hours)

• 1 hour to 1 day: hourly data (limited to last 2 days)

• 1 day: daily data (limited to last 2 months)

Cannot be used together with 'timeframe'.

Example: {"from":"2025-01-01T00:00:00Z","to":"2025-01-31T23:59:59Z"}

filtersany ofOptional

Additional filters to apply

Example: {"only_smart_money":true,"token_age_days":{"max":365,"min":1}}

order_byany ofOptional

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

Responses

200

Token screening 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

502

Bad Gateway

application/json

503

Service Unavailable

application/json

504

Gateway Timeout

application/json

post/api/v1/token-screener

POST /api/v1/token-screener HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 217

{
  "chains": [
    "ethereum",
    "solana",
    "base"
  ],
  "timeframe": "24h",
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "only_smart_money": true,
    "token_age_days": {
      "max": 365,
      "min": 1
    }
  },
  "order_by": [
    {
      "field": "chain",
      "direction": "ASC"
    }
  ]
}

{
  "data": [
    {
      "chain": "text",
      "token_address": "text",
      "token_symbol": "text",
      "token_age_days": 1,
      "token_age_hours": 1,
      "token_deployment_date": "text",
      "market_cap_usd": 1,
      "liquidity": 1,
      "price_usd": 1,
      "price_change": 1,
      "fdv": 1,
      "fdv_mc_ratio": 1,
      "buy_volume": 1,
      "inflow_fdv_ratio": 1,
      "outflow_fdv_ratio": 1,
      "sell_volume": 1,
      "volume": 1,
      "netflow": 1
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}