Position Intelligence

Aggregated perpetual position analytics on Hyperliquid broken down by trader cohort.

Position Intelligence shows aggregated long/short position sizes for a token's perpetual contract on Hyperliquid, broken down by trader cohorts: Smart Money, Whales, Top PnL, and Public Figures. Use it to understand sentiment and positioning distribution across high-signal wallet groups.

Data Freshness & Historical Coverage

For data freshness and historical coverage, see Data Coverage by Chain; this endpoint follows it except where noted below.

• Covers the Hyperliquid perpetuals dataset (reliable from May 2025), not per-chain history — see the Hyperliquid note on the coverage page.

Get "Token God Mode" (TGM) position intelligence data

post

This endpoint provides position intelligence analytics for perpetual contracts on Hyperliquid, showing aggregated position sizes (longs, shorts, and totals) broken down by various trader cohorts (Smart Money, Whales, Top PnL, Public Figures). It can be used for analyzing position distributions and sentiment across different trader segments.

Authorizations

apikeystringRequired

API key for authentication

Body

Request model for TGM position-intelligence endpoint.

This endpoint provides position intelligence analytics for perpetual contracts on Hyperliquid, showing aggregated position sizes by different trader cohorts.

token_addressstring · min: 1Required

Token address (for perps and hyperliquid, validation is skipped)

Example: BTC

Responses

200

TGM position intelligence 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

502

Bad Gateway

application/json

503

Service Unavailable

application/json

504

Gateway Timeout

application/json

post/api/v1/tgm/position-intelligence

POST /api/v1/tgm/position-intelligence HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "token_address": "BTC"
}

{
  "data": [
    {
      "smart_trader_longs_usd": 1000000.5,
      "smart_trader_shorts_usd": 500000.25,
      "smart_trader_total_usd": 1500000.75,
      "whale_longs_usd": 2000000.5,
      "whale_shorts_usd": 1000000.25,
      "whale_total_usd": 3000000.75,
      "public_figure_longs_usd": 500000.5,
      "public_figure_shorts_usd": 250000.25,
      "public_figure_total_usd": 750000.75
    }
  ]
}