---
title: "Get \"Token God Mode\" (TGM) perp positions data"
method: POST
path: "/api/v1/tgm/perp-positions"
tags: ["Token God Mode"]
---

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

`POST /api/v1/tgm/perp-positions`

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?**

## Request body

- TGMPerpPositionsRequest — Request model for TGM perp positions endpoint. This endpoint provides perp positions data for a specific token.
  - `token_symbol` string, required — Token symbol
  - `label_type` 'smart_money' | 'all_traders' | 'whale' | 'public_figure' — TGM perp positions label types.
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `filters` TGMPerpPositionsFilters — Filters for TGM perp positions endpoint. These filters control which perp positions are included in the analysis.
    - `include_smart_money_labels` LabelType[] — Include smart money labels for traders
    - `exclude_smart_money_labels` LabelType[] — Exclude smart money labels for traders
    - `address` union — Trader address filter
      - string
      - string[]
    - `address_label` union — Trader label filter
      - string
      - string[]
    - `side` union — Position side filter (Long or Short)
      - 'Long' | 'Short' — Shared enum for position side direction.
      - PositionSide[]
    - `position_value_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `position_size` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `entry_price` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `upnl_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `funding_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
  - `order_by` SortOrderTGMPerpPositionsSortField[] — 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` 'address' | 'address_label' | 'side' | 'position_value_usd' | 'position_size' | 'leverage' | 'entry_price' | 'mark_price' | 'liquidation_price' | 'funding_usd' | 'upnl_usd', required — Enum for sortable fields in TGM perp positions.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

TGM perp positions data

- TGMPerpPositionsResponse — Response model for TGM perp positions endpoint. Contains a list of perp position records with pagination and metadata.
  - `data` TGMPerpPosition[], required — List of TGM perp position records
    - `address` string — The wallet address of the trader.
    - `address_label` string — Wallet or labeled entity holding the position.
    - `side` 'Long' | 'Short' — Shared enum for position side direction.
    - `position_value_usd` number — USD notional size of the position.
    - `position_size` number — The position size (token amount).
    - `leverage` string, required — The leverage applied to the position.
    - `leverage_type` string — The type of leverage used, e.g., cross or isolated.
    - `entry_price` number — Average price where the position was opened.
    - `mark_price` number — The current mark price of the asset.
    - `liquidation_price` number — The price at which the position would be liquidated.
    - `funding_usd` number — Net funding paid (-) or received (+) since entry.
    - `upnl_usd` number — Unrealized profit/loss including funding.
  - `pagination` PaginationInfo, required — Pagination information for API responses.
    - `page` integer — Current page number
    - `per_page` integer — Number of records per page
    - `is_last_page` boolean — Whether this is the last page

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)