Token Screener

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

Get Token Screening 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

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

Request model for Token Screener endpoint.

Use the 'timeframe' parameter (recommended) for predefined time windows, or 'date' for custom date ranges (deprecated).

timeframeany ofOptional

Time window for token screening data (recommended).

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)

This parameter 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 Superapp token-screener widget.

Possible values:

dateany ofOptionalDeprecated

DEPRECATED: Use 'timeframe' instead for better reliability and performance.

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)

This parameter 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

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/v1/token-screener

HTTPcURLJavaScriptPython

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,
      "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
  }
}