Token Perp Positions

Data Freshness & Historical Coverage

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

• Returns a current, point-in-time snapshot of open positions for the token — there is no date-range parameter or historical look-back, and values reflect within the standard live latency.

Get "Token God Mode" (TGM) perp positions data

post

Retrieve current perpetual positions for a specific token on Hyperliquid. Shows active positions with detailed metrics including entry price, mark price, leverage, PnL, and liquidation price.

Key Features:

• Hyperliquid perpetual contracts only (no chain field needed)

• Real-time position tracking with live PnL calculations

• Leverage and margin information

• Smart money filtering capabilities

• Support for both Long and Short positions

What it helps to answer:

1. What are the current perp positions for a specific token?

2. Which addresses have the largest positions by value?

3. What are the unrealized gains/losses on current positions?

4. What leverage levels are traders using?

5. Which smart money wallets are holding positions?

Authorizations

apikeystringRequired

API key for authentication

Body

Request model for TGM perp positions endpoint.

This endpoint provides perp positions data for a specific token.

token_symbolstringRequired

Token symbol

Example: BTC

label_typestring · enumOptional

Label type filter

Default: all_tradersExample: all_tradersPossible values:

filtersany ofOptional

Additional filters to apply to the query.

Example: {"include_smart_money_labels":["Smart HL Perps Trader","Fund"],"position_value_usd":{"min":10000},"side":["Long"],"upnl_usd":{"min":0}}

order_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

• [{"field": "position_value_usd", "direction": "DESC"}] - Sort by position value USD descending
• [{"field": "upnl_usd", "direction": "ASC"}] - Sort by unrealized PnL ascending
• [{"field": "leverage", "direction": "DESC"}] - Sort by leverage descending
• [{"field": "size_base", "direction": "DESC"}] - Sort by absolute position size descending, longs and shorts together

position_size is signed (a short is negative), so a sort on it ranks every long above every short. size_base sorts both sides by the size of the position.

Responses

200

TGM perp positions 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/perp-positions

POST /api/v1/tgm/perp-positions HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 284

{
  "token_symbol": "BTC",
  "label_type": "all_traders",
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "include_smart_money_labels": [
      "Smart HL Perps Trader",
      "Fund"
    ],
    "position_value_usd": {
      "min": 10000
    },
    "side": [
      "Long"
    ],
    "upnl_usd": {
      "min": 0
    }
  },
  "order_by": [
    {
      "field": "address",
      "direction": "ASC"
    }
  ]
}

{
  "data": [
    {
      "address": "0x1234567890123456789012345678901234567890",
      "address_label": "Smart Money",
      "side": "Long",
      "position_value_usd": 50000,
      "position_size": 1.5,
      "leverage": "5X",
      "leverage_type": "cross",
      "entry_price": 50000,
      "mark_price": 50500,
      "liquidation_price": 45000,
      "funding_usd": 10.5,
      "upnl_usd": 500
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}