Accessing Hyperliquid on Nansen API Beta

A public, developer‑friendly 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.

Supported now: Perp Positions, Perp Flows, Position Changes, Trades, PnL Leaderboard

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

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

Endpoints

1) Hyperliquid Perp Positions

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

Endpoint

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

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.

Endpoint

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

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.

Endpoint

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

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

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

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

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

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" }
}

Previousnansen-api-reference NextData Redistribution Guidelines

Last updated 4 days ago

Was this helpful?