Perp Screener

Common Scenarios

Usecase	Required Parameters	Optional Filters	Expected Output
Screen for perps with net buy/sell pressure and strong fundamentals	date ={ "from": "2025-10-01T00:00:00Z", "to": "2025-10-06T23:59:59Z" }	filters ={ "buy_sell_pressure": { "min": 100000 }, "open_interest": { "min": 500000 } }	Perps showing high buy/sell pressure and strong open interest, returned with mark price, volume, and trader details
Discover perps favored by smart money	date ={ "from": "2025-10-01T00:00:00Z", "to": "2025-10-06T23:59:59Z" }	only_smart_money =true filters ={ "smart_money_volume": { "min": 100000 } }	Perps with the highest smart money volume, including smart money long/short counts, USD position sizes, and assets

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

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

Request model for Perp Screener endpoint.

filtersany ofOptional

Additional filters to apply

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

order_byany ofOptional

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

Examples:

• [{"field": "volume", "direction": "DESC"}] - Sort by volume descending
• [{"field": "net_positionz_change", "direction": "DESC"}] - Sort by net_position_change descending
• [{"field": "buy_sell_pressure", "direction": "DESC"}] - Sort by buy/sell pressure descending (smart money)

Default behavior:

• When only_smart_money is False: sorts by buy_sell_pressure DESC
• When only_smart_money is True: 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

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

HTTPcURLJavaScriptPython

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

{
  "date": {
    "from": "2025-10-01T00:00:00Z",
    "to": "2025-10-06T23:59:59Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "token_symbol": "BTC",
    "volume": {
      "min": 10000
    }
  },
  "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,
      "sell_volume": 210984.15843,
      "token_symbol": "ARK",
      "trader_count": 109,
      "volume": 427486.75766
    },
    {
      "buy_sell_pressure": 25000,
      "buy_volume": 1250000,
      "funding": 0.0001,
      "mark_price": 45000,
      "open_interest": 5000000,
      "previous_price_usd": 44000,
      "sell_volume": 1250000,
      "token_symbol": "BTC",
      "trader_count": 500,
      "volume": 2500000
    },
    {
      "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,
      "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
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}