---
title: "Get Perpetual Contract Screening Data"
method: POST
path: "/api/v1/perp-screener"
tags: ["Token Screener"]
---

# Get Perpetual Contract Screening Data

`POST /api/v1/perp-screener`

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?**

## Request body

- PerpScreenerRequest — Request model for Perp Screener endpoint.
  - `date` DateRange, required — Date range model matching the API schema.
    - `from` string — Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
    - `to` string — End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `filters` PerpScreenerFilters — Filters for perp screener endpoints. These filters control which perpetual contracts are included in the screening results based on various criteria.
    - `trader_type` 'all' | 'sm' | 'whale' | 'public_figure' | 'high_winrate_hl_perps_trader' — Trader type for perp screener.
    - `only_smart_money` boolean — Deprecated: use trader_type=sm instead.
    - `sectors_filter` string[] — Filter by sector in category:subcategory format (e.g. Crypto:DeFi, Crypto:AI, TradFi:Stocks). Values in any other format are rejected. Note: this differs from the token screener's sectors filter, which uses bare sector names. Applied server-side.
    - `sm_label_filter` string[] — Filter by Nansen smart money label. Applies when trader_type is all or sm; ignored for other trader types. Applied server-side.
    - `trader_label_filter` string[] — Filter by Hyperliquid perps trader label (e.g. HL Perps Whale, HL Perps Swing Trader). Applies when trader_type is all or sm; ignored for other trader types. Applied server-side.
    - `token_symbol` string — Asset symbol filter (e.g., BTC, ETH)
    - `volume` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `buy_volume` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `sell_volume` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `buy_sell_pressure` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `trader_count` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
    - `mark_price` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `funding` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `previous_price_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `open_interest` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `smart_money_volume` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `smart_money_buy_volume` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `smart_money_sell_volume` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `net_position_change` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `current_smart_money_position_longs_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `current_smart_money_position_shorts_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `smart_money_longs_count` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
    - `smart_money_shorts_count` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
  - `order_by` SortOrderUnionPerpScreenerSortFieldDefaultPerpScreenerSortFieldSmartMoneyPerpScreenerSortFieldNotableLabel[] — 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
    - `field` union, required — Field to sort by
      - 'token_symbol' | 'volume' | 'buy_volume' | 'sell_volume' | 'buy_sell_pressure' | 'trader_count' | 'mark_price' | 'funding' | 'previous_price_usd' | 'open_interest' — Sort fields available for default perp screener data (only_smart_money=False).
      - 'token_symbol' | 'smart_money_volume' | 'smart_money_buy_volume' | 'smart_money_sell_volume' | 'net_position_change' | 'trader_count' | 'mark_price' | 'funding' | 'previous_price_usd' | 'open_interest' | 'current_smart_money_position_longs_usd' | 'current_smart_money_position_shorts_usd' | 'smart_money_longs_count' | 'smart_money_shorts_count' — Sort fields available for smart money perp screener data (only_smart_money=True).
      - 'token_symbol' | 'volume' | 'buy_volume' | 'sell_volume' | 'net_position_change' | 'trader_count' | 'mark_price' | 'funding' | 'open_interest' | 'current_position_longs_usd' | 'current_position_shorts_usd' | 'longs_count' | 'shorts_count' — Sort fields available for notable-label perp screener data (trader_type whale/public_figure/high_winrate_hl_perps_trader).
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

Perpetual contract screening data

- PerpScreenerResponse — Response model for perp screener endpoint.
  - `data` union[], required — List of perp screening results
    - union
      - PerpScreenerDataDefault — Data model for perp screener results when only_smart_money is False.
        - `volume` number — Total traded notional in USD over the recent window.
        - `buy_volume` number — Total USD value of market buy trades over the recent window.
        - `sell_volume` number — Total USD value of market sell trades over the recent window.
        - `buy_sell_pressure` number — Changes in position by Market Orders. Buys and sells through market orders (top of orderbook) indicate a rush into adjusting the position.
        - `trader_count` integer — Number of unique traders active over the recent window.
        - `token_symbol` string, required — Asset symbol (e.g., BTC, ETH) on Hyperliquid.
        - `mark_price` number — Latest mark price for the coin.
        - `funding` number — Latest funding rate/value for the coin.
        - `open_interest` number — Latest open interest for the coin.
        - `previous_price_usd` number — First price in the time window.
      - PerpScreenerDataSmartMoney — Data model for perp screener results when only_smart_money is True.
        - `smart_money_volume` number — Total traded notional in USD by Smart Money over the window.
        - `smart_money_buy_volume` number — Total USD value of Smart Money market buy trades over the window.
        - `smart_money_sell_volume` number — Total USD value of Smart Money market sell trades over the window.
        - `net_position_change` number — Net USD flow (buy_market_vol - sell_market_vol) over the window.
        - `trader_count` integer — Number of unique Smart Money traders active over the window.
        - `token_symbol` string, required — Asset symbol (e.g., BTC, ETH) on Hyperliquid.
        - `mark_price` number — Latest mark price for the coin.
        - `funding` number — Latest funding rate/value for the coin.
        - `previous_price_usd` number — First observed price within the time window.
        - `open_interest` number — Latest open interest in USD (open_interest × mark_price).
        - `current_smart_money_position_longs_usd` number — Aggregate USD value of Smart Money long positions for the coin.
        - `current_smart_money_position_shorts_usd` number — Aggregate USD value of Smart Money short positions for the coin (negative).
        - `smart_money_longs_count` integer — Number of Smart Money accounts with a net long position.
        - `smart_money_shorts_count` integer — Number of Smart Money accounts with a net short position.
      - PerpScreenerDataNotableLabel — Data model for perp screener when trader_type is whale, public_figure or high_winrate_hl_perps_trader.
        - `volume` number — Total traded notional in USD by the selected trader cohort over the window.
        - `buy_volume` number — Total USD value of buys by the selected trader cohort over the window.
        - `sell_volume` number — Total USD value of sells by the selected trader cohort over the window.
        - `net_position_change` number — Net USD flow (buys minus sells) by the selected trader cohort over the window.
        - `trader_count` integer — Number of unique cohort traders active over the window.
        - `token_symbol` string, required — Asset symbol (e.g., BTC, ETH) on Hyperliquid.
        - `mark_price` number — Latest mark price for the coin.
        - `funding` number — Latest funding rate/value for the coin.
        - `open_interest` number — Latest open interest for the coin.
        - `current_position_longs_usd` number — Aggregate USD value of cohort long positions for the coin.
        - `current_position_shorts_usd` number — Aggregate USD value of cohort short positions for the coin (negative).
        - `longs_count` integer — Number of cohort accounts with a net long position.
        - `shorts_count` integer — Number of cohort accounts with a net short position.
  - `pagination` PaginationInfo, required — Pagination information for API responses.
    - `page` integer — Current page number
    - `per_page` integer — Number of records per page
    - `is_last_page` boolean — Whether this is the last page

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)