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?
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.
Endpoint
- 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
- balanceand- balanceUsdrepresent position size and USD value for the time window
- changeShortTimeframe,- changeMediumTimeframe,- changeLongTimeframecapture 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.
Endpoint
- 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
- totalBalanceand- totalBalanceUsdreflect net position change across the cohort for the interval
- totalPositivePositionsand- totalNegativePositionscount wallets with net increases vs decreases
3) Position Changes
Tracks whether a wallet increased or decreased positions within the time range.
Endpoint
- 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.
Endpoint
- 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.
Endpoint
- 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 
Last updated
Was this helpful?





