Perp Screener

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_position_change", "direction": "DESC"}] - Sort by net_position_change descending
• [{"field": "buy_sell_pressure", "direction": "DESC"}] - Sort by buy/sell pressure descending

Available sort fields depend on trader_type: buy_sell_pressure only applies to trader_type all, net_position_change to the other trader types.

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

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