Perp Screener

Data Freshness & Historical Coverage

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

• Covers the Hyperliquid perpetuals dataset (reliable from May 2025), not per-chain history — see the Hyperliquid note on the coverage page.

Get Perpetual Contract Screening Data

post

Discover and screen perpetual contracts on Hyperliquid with advanced filtering capabilities. This endpoint helps identify trending perpetual contracts, trading activity, funding rates, and smart money movements by combining metrics like volume, open interest, funding rates, and position data.

What it helps to answer:

1. Which perpetual contracts are experiencing significant trading volume and activity?

2. How do funding rates correlate with trading patterns and smart money positions?

3. What perpetual contracts show strong fundamentals in terms of open interest and trading patterns?

4. Which perpetual contracts are attracting smart money participation with long/short positions?

Authorizations

apikeystringRequired

API key for authentication

Body

Request model for Perp Screener endpoint.

filtersany ofOptional

Additional filters to apply

Example: {"token_symbol":"BTC","volume":{"min":10000}}

include_price_changebooleanOptional

Return previous_price_usd, window_end_price_usd and price_change for notable-label trader cohorts even when not sorting or filtering by price. These fields are otherwise null unless price_change or previous_price_usd is used for sorting, or previous_price_usd is used for filtering. All and Smart Money results always include these fields.

Default: false

order_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

• [{"field": "volume", "direction": "DESC"}] - Sort by volume descending
• [{"field": "net_position_change", "direction": "DESC"}] - Sort by net_position_change descending
• [{"field": "buy_sell_pressure", "direction": "DESC"}] - Sort by buy/sell pressure descending
• [{"field": "price_change", "direction": "DESC"}] - Top gainers first

Available sort fields depend on trader_type: buy_sell_pressure only applies to trader_type all, net_position_change to the other trader types. price_change applies to every trader type. Rows with a null price_change (outcome contracts, missing prices) sort last in both directions, and token_symbol ASC is added as a final tie-breaker so pages don't overlap.

Default behavior:

• trader_type all (or unset): sorts by buy_sell_pressure DESC
• all other trader types: sorts by net_position_change DESC

Example: [{"direction":"DESC","field":"buy_sell_pressure"}]

Responses

200

Perpetual contract 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/perp-screener

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

{
  "date": {
    "from": "2026-10-01T00:00:00Z",
    "to": "2026-10-05T23:59:59Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "token_symbol": "BTC",
    "volume": {
      "min": 10000
    }
  },
  "include_price_change": false,
  "order_by": [
    {
      "direction": "DESC",
      "field": "buy_sell_pressure"
    }
  ]
}

{
  "data": [
    {
      "buy_sell_pressure": 5518.4408,
      "buy_volume": 216502.59923,
      "funding": 0.0000125,
      "mark_price": 0.3301,
      "open_interest": 261310.461,
      "previous_price_usd": 0.4155,
      "price_change": -0.2055,
      "sell_volume": 210984.15843,
      "token_symbol": "ARK",
      "trader_count": 109,
      "volume": 427486.75766,
      "window_end_price_usd": 0.3301
    },
    {
      "buy_sell_pressure": 25000,
      "buy_volume": 1250000,
      "funding": 0.0001,
      "mark_price": 45000,
      "open_interest": 5000000,
      "previous_price_usd": 44000,
      "price_change": 0.0227,
      "sell_volume": 1250000,
      "token_symbol": "BTC",
      "trader_count": 500,
      "volume": 2500000,
      "window_end_price_usd": 45000
    },
    {
      "current_smart_money_position_longs_usd": 500000,
      "current_smart_money_position_shorts_usd": -500000,
      "funding": -0.0001,
      "mark_price": 3000,
      "net_position_change": 25000,
      "open_interest": 2000000,
      "previous_price_usd": 2900,
      "price_change": 0.0345,
      "smart_money_buy_volume": 75000,
      "smart_money_longs_count": 5,
      "smart_money_sell_volume": 75000,
      "smart_money_shorts_count": 5,
      "smart_money_volume": 150000,
      "token_symbol": "ETH",
      "trader_count": 15,
      "window_end_price_usd": 3000
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}