Accessing Hyperliquid on Nansen API Beta

A guide to accessing Hyperliquid perpetuals data via Nansen API. This page covers available endpoints, required parameters, example requests and responses, and key caveats specific to Hyperliquid.

We're rolling out a more robust /v1 soon, but here’s a quick solution to get you started right away..

What Can You Do

📊 See who's holding positions: Find perp positions of any asset for Smart Money, Whales, Public Figures and Top Perp Traders.
💰 Track position flows: Monitor when different cohorts open/close positions over time.
🔄 Watch position changes: See who's increasing vs decreasing their positions over a selected period.
📈 Monitor real-time trades: Get a feed of every trade as it happens.
🎯 Find profitable traders: Rank traders by realized and unrealized PnL for any perp market.

Quick Start

Get the top 10 positions for PENGU perps right now:

curl -L \
  --request POST \
  --url 'https://api.nansen.ai/api/beta/tgm/holders' \
  --header 'apiKey: fj4WdE74qYC5NRwOvvyJX8o72u5Urg7B' \
  --header 'Content-Type: application/json' \
  --data '{
    "parameters": {
      "chain": "hyperliquid",
      "tokenAddress": "PENGU",
      "date": {
        "from": "2025-10-08",
        "to": "2025-10-09"
      },
      "isEntity": false,
      "includeLabels": [],
      "label": "top_100_holders",
      "isStablecoin": false
    },
    "pagination": {
      "page": 1,
      "recordsPerPage": 10
    },
    "order": {
      "orderBy": "balanceUsd",
      "order": "desc"
    }
  }'

That's it! You'll get back wallet addresses, position sizes, and USD values.

Which Endpoint Should I Use?

I want to...

Use this endpoint

Best for

See who's holding positions now

Perp Positions

Snapshot of current positions

Track Smart Money flows over time

Perp Flows

Aggregate trends by hour/day

Find who's opening/closing positions

Position Changes

Net buyer/seller analysis

See every single trade

Trades

Trade-by-trade detail

Find the most profitable traders

PnL Leaderboard

Performance rankings

Usecase & API Example

1) Hyperliquid Perp Positions

Returns wallets with active perpetual positions for a given market and time range.

App Reference

Link Here

Endpoint

POST: https://api.nansen.ai/api/beta/tgm/holders
API Link: Click Here

Parameters

chain: "hyperliquid" (required)
tokenAddress: token symbol or name, for example "PENGU" (required)
date.from, date.to: ISO 8601 timestamps delimiting the window (required)
isEntity: false for wallet‑level positions
includeLabels: optional array of label filters; examples below
label: optional segment label such as top_100_holders
isStablecoin: optional boolean

Example request

curl -L \\
  --request POST \\
  --url '<https://api.nansen.ai/api/beta/tgm/holders>'' \\
  --header 'apiKey: YOUR_API_KEY' \\
  --header 'Content-Type: application/json' \\
  --data '{
    "parameters": {
      "chain": "hyperliquid",
      "tokenAddress": "PENGU",
      "date": {
        "from": "2025-08-05T00:00:00.000Z",
        "to":   "2025-09-05T23:59:59.000Z"
      },
      "isEntity": false,
      "includeLabels": [
        "180D Smart Trader",
        "30D Smart Trader",
        "90D Smart Trader",
        "Fund",
        "Smart HL Perps Trader"
      ],
      "label": "top_100_holders",
      "isStablecoin": false
    },
    "pagination": { "page": 1, "recordsPerPage": 20 },
    "order": { "orderBy": "balance", "order": "desc" }
  }'

Example response

{
  "address": "0x27388d079cb5cf1ad50f60ab4c260356449bf92b",
  "name": "🤓 Smart HL Perps Trader [0x27388d]",
  "balance": 10143138,
  "sent": 0,
  "received": 10143138,
  "changeShortTimeframe": 0,
  "changeMediumTimeframe": 0,
  "changeLongTimeframe": 0,
  "percentOwnership": 0,
  "balanceUsd": 294932.023626,
  "shortTimeframeHours": 0,
  "mediumTimeframeHours": 0,
  "longTimeframeHours": 0
}

Field notes

balance and balanceUsd represent position size and USD value for the time window
changeShortTimeframe, changeMediumTimeframe, changeLongTimeframe capture deltas across predefined hour buckets

2) Hyperliquid Perp Flows

Aggregated flows across label cohorts such as Smart Money, Whales, Public Figures, and High Win‑rate Perps Traders.

App Reference

Link Here

Endpoint

POST: https://api.nansen.ai/api/beta/tgm/flows
Link: Click Here

Parameters

chain: "hyperliquid" (required)
tokenAddress: token symbol or name, for example "PENGU" (required)
label: cohort label such as smart_money or top_100_holders
date.from, date.to: date strings (YYYY-MM-DD) or ISO 8601
pagination optional

Example request

curl -L \\
  --request POST \\
  --url '<https://api.nansen.ai/api/beta/tgm/flows>'' \\
  --header 'apiKey: YOUR_API_KEY' \\
  --header 'Content-Type: application/json' \\
  --data '{
    "parameters": {
      "chain": "hyperliquid",
      "tokenAddress": "PENGU",
      "date": { "from": "2025-05-01", "to": "2025-05-03" },
      "label": "smart_money"
    },
    "pagination": { "page": 1, "recordsPerPage": 100 }
  }'

Example response

{
  "blockDate": "2025-06-18T01:00:00Z",
  "priceUsd": 0.009264,
  "totalBalance": -25843981,
  "totalBalanceUsd": -751465.435537,
  "totalHolders": "3",
  "totalInflows": 0,
  "totalOutflows": 0,
  "totalPositivePositions": "1",
  "totalNegativePositions": "2"
}

Field notes

totalBalance and totalBalanceUsd reflect net position change across the cohort for the interval
totalPositivePositions and totalNegativePositions count wallets with net increases vs decreases

3) Position Changes

Tracks whether a wallet increased or decreased positions within the time range.

App Reference

Link Here

Endpoint

POST: https://api.nansen.ai/api/beta/tgm/who-bought-sold
Link: Click Here

Parameters

chain: "hyperliquid" (required)
buyOrSell: BUY or SELL to focus on directionality
timeRange.from, timeRange.to: YYYY-MM-DD or ISO 8601
tokenAddress: token symbol or name

Example request

curl -L \\
  --request POST \\
  --url '<https://api.nansen.ai/api/beta/tgm/who-bought-sold>'' \\
  --header 'apiKey: YOUR_API_KEY' \\
  --header 'Content-Type: application/json' \\
  --data '{
    "parameters": {
      "chain": "hyperliquid",
      "buyOrSell": "BUY",
      "timeRange": { "from": "2025-05-01", "to": "2025-05-02" },
      "tokenAddress": "PENGU"
    },
    "pagination": { "page": 1, "recordsPerPage": 100 }
  }'

Example response

{
  "address": "0x00c511ab1b583f4efab3608d0897d377c4de47a6",
  "addressLabel": "High Balance [0x00c511]",
  "boughtTokenVolume": 17835948,
  "soldTokenVolume": 5452519,
  "tokenTradeVolume": 12383429,
  "boughtVolumeUsd": 198902.1348184976,
  "soldVolumeUsd": 63002.2294680785,
  "tradeVolumeUsd": 261904.3642865761
}

4) Trades

Live or historical list of trades executed by individual traders for the specified market.

App Reference

Link Here

Endpoint

POST: https://api.nansen.ai/api/beta/tgm/dex-trades
Link: Click Here

Parameters

chain: "hyperliquid" (required)
tokenAddress: token symbol or name
onlySmartMoney: boolean to restrict to Smart Money cohort
date.from, date.to: YYYY-MM-DD or ISO 8601

Example request

curl -L \\
  --request POST \\
  --url '<https://api.nansen.ai/api/beta/tgm/dex-trades>'' \\
  --header 'apiKey: YOUR_API_KEY' \\
  --header 'Content-Type: application/json' \\
  --data '{
    "parameters": {
      "chain": "hyperliquid",
      "tokenAddress": "PENGU",
      "onlySmartMoney": false,
      "date": { "from": "2025-07-07", "to": "2025-07-14" }
    },
    "pagination": { "page": 1, "recordsPerPage": 100 }
  }'

Example response

{
  "action": "MARKET SELL|Close Long",
  "tokenAmount": 5315,
  "estimatedValueUsd": 159.58819,
  "estimatedSwapPriceUsd": 0.030026,
  "traderAddressHex": "0x5099991c26843e6b137b5603aa3be0bb5babb6da",
  "traderName": "[0x509999]",
  "transactionHash": "0x41ff68366cba8816b99204277226b401f000a4b2852662e0af0e059a94f05dd3",
  "blockTimestamp": "2025-07-13T23:59:58.836Z"
}

5) TGM PnL Leaderboard

Ranks traders by realised and unrealised PnL over the period.

App Reference

Link Here

Endpoint

POST: https://api.nansen.ai/api/beta/tgm/pnl-leaderboard
Link: Click Here

Parameters

chain: "hyperliquid" (required)
date.from, date.to
tokenAddress

Example request

curl -L \\
  --request POST \\
  --url '<https://api.nansen.ai/api/beta/tgm/pnl-leaderboard>'' \\
  --header 'apiKey: YOUR_API_KEY' \\
  --header 'Content-Type: application/json' \\
  --data '{
    "parameters": {
      "chain": "hyperliquid",
      "date": { "from": "2025-07-14", "to": "2025-07-15" },
      "tokenAddress": "PENGU"
    },
    "pagination": { "page": 1, "recordsPerPage": 100 }
  }'

Example response

{
  "traderAddress": "0x6f5bbfbfb82729cf356f37f88911952ca115d3f5",
  "fullName": "High Balance [0x6f5bbf]",
  "holdingAmount": 0,
  "holdingUsd": 0,
  "tokenPrice": 0.029225,
  "maxBalanceHeld": 0,
  "maxBalanceHeldUsd": 0,
  "stillHoldingBalanceRatio": 0,
  "pnlUsdRealised": 1924261.762444,
  "pnlUsdUnrealised": 0,
  "roiPercentRealised": 0.18026886923180446,
  "roiPercentUnrealised": null,
  "pnlUsdTotal": 1924261.762444,
  "roiPercentTotal": 0.18026886923180446,
  "nofTrades": "2629",
  "netflowAmountUsd": 0
}

This endpoint supports flexible sorting through the order parameter. You can sort traders by various performance metrics to analyze different aspects of trading behavior. Supported OrderBy Fields:

pnlUsdTotal - Total profit/loss in USD
pnlUsdUnrealised - Unrealized profit/loss in USD
pnlUsdRealised - Realized profit/loss in USD
roiPercentRealised - Realized ROI percentage
nofTrades - Number of trades
netflowAmountUsd - Net flow amount in USD
holdingUsd - Current USD value of holdings

Example

{
  "parameters": {
    "chain": "hyperliquid",
    "date": { "from": "2025-07-14", "to": "2025-07-15" },
    "tokenAddress": "PENGU"
  },
  "pagination": { "page": 1, "recordsPerPage": 100 },
  "order": { "orderBy": "roiPercentRealised", "order": "desc" }
}

General guidance

Chain must be set to "hyperliquid" for all endpoints
tokenAddress accepts the token symbol (for example, "PENGU")
Labels supported include: top_100_holders, Smart Money, Public Figures, Whale, high_winrate_hl_perps_trader
Pagination is supported with page and recordsPerPage
Dates accept ISO 8601 or YYYY-MM-DD

Authentication

Send your API key in header: apiKey: YOUR_API_KEY
Content type: application/json

Errors and limits

Standard HTTP status codes
If a query returns no data, verify tokenAddress symbol, date range, and label filters

Previousnansen-api-reference NextData Redistribution Guidelines

Last updated 21 days ago

Was this helpful?