Aggregated perpetual position sizes by trader cohort (Smart Money, Whales, Public Figures) on Hyperliquid via Nansen.
What it does
The Nansen TGM Position Intelligence endpoint returns aggregated perpetual-contract position data on Hyperliquid, broken down by trader cohort: Smart Money (Smart HL Perps Trader), Whales, Top PnL, and Public Figures. For each cohort the response includes the sum of long positions (USD), short positions (USD), and total absolute position size. This lets callers gauge directional sentiment across sophisticated trader segments for any Hyperliquid-listed perpetual contract.
The endpoint accepts a POST request with a JSON body containing `token_address` (which here is the perp symbol, e.g. "BTC", "ETH", "SOL"). It is part of the broader Nansen API v1 suite, which covers smart-money analytics, wallet profiling, token screening, DEX/CEX flow analysis, Polymarket prediction-market data, and an AI research agent across 25+ chains. The position-intelligence endpoint costs 10 credits on the free tier and 1 credit on the pro tier per call. Via x402 pay-per-request, the fixed price is $0.01 per call. Rate limits are enforced per-second and per-minute, reported in response headers. Authentication is via an `apiKey` header, or via x402 payment signature for pay-per-request access.
Capabilities
Use cases
- —Gauge smart-money directional bias (long vs short) on a Hyperliquid perpetual before entering a trade
- —Monitor whale and public-figure position sizing to detect large directional bets
- —Feed cohort position data into an automated trading agent for sentiment-aware order execution
- —Build dashboards showing real-time long/short breakdowns by trader type for any Hyperliquid asset
- —Compare smart-money positioning across multiple perp contracts to identify sector rotations
Fit
Best for
- —Crypto traders wanting smart-money sentiment signals on Hyperliquid perps
- —Quantitative strategies that incorporate cohort-level positioning data
- —Research analysts tracking whale and public-figure derivatives exposure
Not for
- —Spot-only token analytics (use Nansen TGM flow/holder endpoints instead)
- —Historical time-series of positions (this returns a current snapshot only)
- —Non-Hyperliquid perpetual exchanges
Quick start
curl -X POST https://api.nansen.ai/api/v1/tgm/position-intelligence \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{"token_address": "BTC"}'Example
Request
{
"token_address": "BTC"
}Response
{
"data": [
{
"whale_longs_usd": 45000000,
"whale_total_usd": 77000000,
"whale_shorts_usd": 32000000,
"smart_trader_longs_usd": 12500000.5,
"smart_trader_total_usd": 20800000.75,
"public_figure_longs_usd": 2100000,
"public_figure_total_usd": 3000000,
"smart_trader_shorts_usd": 8300000.25,
"public_figure_shorts_usd": 900000
}
]
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear pricing ($0.01/call via x402, 1 credit on pro), and the endpoint returned 402 confirming it is live. Docs are comprehensive but no worked response example was captured from the probe itself; the example response is inferred from the schema. No external crawl docs were available beyond the OpenAPI spec.
Warnings
- —No dedicated documentation page was reachable (api.nansen.ai/docs returned 404); all information is derived from the OpenAPI spec.
- —The endpoint returns a current snapshot only — no historical time-series of position intelligence is available from this path.
- —The probe returned 402 via HEAD confirming liveness, but no WWW-Authenticate or x402 challenge body was captured, so exact x402 payment flow details are inferred from the OpenAPI x-payment-info annotation.
Citations
- —The position-intelligence endpoint costs 10 credits (free) / 1 credit (pro) per call, with x402 fixed price of $0.01.https://api.nansen.ai/api/v1/tgm/position-intelligence
- —The endpoint provides aggregated position sizes broken down by Smart Money, Whales, Top PnL, and Public Figures on Hyperliquid.https://api.nansen.ai/api/v1/tgm/position-intelligence
- —The Nansen API uses apiKey header authentication and supports x402 pay-per-request protocol.https://api.nansen.ai