🆕Token Perp Positions

Get 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

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

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

Responses

200

TGM perp positions data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/perp-positions

HTTPcURLJavaScriptPython

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