Screen Hyperliquid perpetual contracts by volume, funding rates, open interest, and smart money activity.
What it does
The Nansen Perp Screener endpoint (`POST /api/v1/perp-screener`) lets you discover and filter perpetual contracts on Hyperliquid. It returns metrics such as trading volume, buy/sell volume, buy/sell pressure, trader count, mark price, funding rate, open interest, and price change for each listed perp. An `only_smart_money` filter switches the response to a smart-money-specific schema that adds net position change, smart money long/short positions in USD, and smart money trader counts.
The endpoint accepts a required date range, optional filters (token symbol, volume ranges, funding rate ranges, open interest ranges, etc.), pagination, and custom sort order. Results can be sorted by any returned metric. The API is documented with a full OpenAPI 3.1 spec and supports both API-key authentication and pay-per-request via the x402 protocol at $0.01 per call. Credit cost is 10 (free tier) or 1 (pro tier) per request.
This endpoint is part of the broader Nansen API v1 suite, which covers smart money analytics, wallet profiling, Token God Mode (TGM) flows, Polymarket prediction markets, and an AI research agent. Rate limits are exposed via response headers (per-second and per-minute windows).
Capabilities
Use cases
- —Identify Hyperliquid perps with the highest trading volume or open interest over a given time window
- —Filter for perps where smart money is actively accumulating long or short positions
- —Monitor funding rate extremes across all Hyperliquid perpetual contracts
- —Screen for perps with unusual buy/sell pressure to detect directional momentum
- —Build automated dashboards tracking smart money net position changes on Hyperliquid
Fit
Best for
- —Quantitative traders screening Hyperliquid perpetual markets
- —Analysts tracking smart money positioning in crypto derivatives
- —Agents that need structured, filterable perp market data via API
- —Portfolio managers monitoring funding rates and open interest shifts
Not for
- —Spot token screening (use /api/v1/token-screener instead)
- —DEX or CEX spot trade data (use TGM or Smart Money DEX endpoints)
- —Non-Hyperliquid perpetual exchanges
Quick start
curl -X POST https://api.nansen.ai/api/v1/perp-screener \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{
"date": {"from": "2025-01-01T00:00:00Z", "to": "2025-01-07T23:59:59Z"},
"pagination": {"page": 1, "per_page": 10},
"order_by": [{"field": "volume", "direction": "DESC"}]
}'Example
Request
{
"date": {
"to": "2025-01-07T23:59:59Z",
"from": "2025-01-01T00:00:00Z"
},
"filters": {
"volume": {
"min": 100000
},
"only_smart_money": false
},
"order_by": [
{
"field": "volume",
"direction": "DESC"
}
],
"pagination": {
"page": 1,
"per_page": 5
}
}Response
{
"data": [
{
"volume": 2500000,
"funding": 0.0001,
"buy_volume": 1250000,
"mark_price": 45000,
"sell_volume": 1250000,
"token_symbol": "BTC",
"trader_count": 500,
"open_interest": 5000000,
"buy_sell_pressure": 25000,
"previous_price_usd": 44000
},
{
"volume": 1800000,
"funding": -0.0001,
"buy_volume": 900000,
"mark_price": 3000,
"sell_volume": 900000,
"token_symbol": "ETH",
"trader_count": 350,
"open_interest": 2500000,
"buy_sell_pressure": -5000,
"previous_price_usd": 2900
}
],
"pagination": {
"page": 1,
"per_page": 5,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear pricing ($0.01/call via x402), and a live 402 MPP challenge captured. Docs pages on the origin return 404 so external documentation is unavailable, but the OpenAPI spec is comprehensive enough to infer all usage details.
Warnings
- —No standalone documentation pages found at api.nansen.ai/docs — rely on the OpenAPI spec for integration details.
- —Response schema references ($ref) for PerpScreenerResponse were not fully resolved in the probe; field names inferred from the OpenAPI components section.
Citations
- —The perp-screener endpoint costs $0.01 per call via x402 and 10 credits (free) / 1 credit (pro).https://api.nansen.ai
- —The endpoint supports only_smart_money filter which returns smart money-specific fields including net_position_change and current smart money position longs/shorts.https://api.nansen.ai
- —The endpoint is POST /api/v1/perp-screener and requires a date range parameter.https://api.nansen.ai
- —The MPP probe returned HTTP 402 confirming the endpoint is live.https://api.nansen.ai/api/v1/perp-screener