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

# Get "Token God Mode" (TGM) perp PnL leaderboard data

`POST /api/v1/tgm/perp-pnl-leaderboard`

Rank traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input perpetual contract.

**Key Features:**
- Hyperliquid perpetual contracts only (no chain field needed)
- Realized and unrealized PnL tracking
- ROI calculations and trading patterns
- Position size and balance tracking

**Request Format:**
- `token_symbol`: Perpetual contract symbol (e.g., "BTC", "ETH", "SOL")
- `date`: Date range for analysis
- `filters`: Optional filters for trader addresses, PnL ranges, etc.
- `pagination`: Page and per_page parameters

**Label Tier Control (`premium_labels`):**
When omitted or set to `false` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at **150 credits per call**, and requires a paid plan.

## Request body

- TGMPerpPnlLeaderboardRequest — Request model for TGM Perp PnL leaderboard endpoint. Simplified version that only supports Hyperliquid perpetual contracts.
  - `token_symbol` string, required — Perpetual contract symbol (e.g., BTC, ETH, SOL)
  - `date` DateRange, required — Date range model matching the API schema.
    - `from` string — Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
    - `to` string — End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `filters` TGMPerpPnlLeaderboardFilters — Filters for TGM Perp PnL leaderboard endpoint. These filters control which traders are included in the leaderboard.
    - `trader_address` union — Trader address filter
      - string
      - string[]
    - `trader_address_label` union — Trader name filter
      - string
      - string[]
    - `token_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)
    - `pnl_usd_realised` 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)
    - `pnl_usd_unrealised` 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)
    - `holding_amount` 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_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)
    - `max_balance_held` 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)
    - `max_balance_held_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)
    - `still_holding_balance_ratio` 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)
    - `nof_trades` 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)
    - `include_smart_money_labels` SmartMoneyFilterType[] — Include smart money labels
    - `exclude_smart_money_labels` SmartMoneyFilterType[] — Exclude smart money labels
  - `premium_labels` boolean — Controls label tier in the response. When null/omitted or false (the default), returns free-tier labels at the standard credit cost for this endpoint. When true, returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan.
  - `order_by` SortOrderTGMPerpPnlLeaderboardSortField[] — Custom sort order to override the endpoint's default ordering
    - `field` 'pnl_usd_realised' | 'pnl_usd_unrealised' | 'pnl_usd_total' | 'roi_percent_total' | 'roi_percent_realised' | 'roi_percent_unrealised' | 'holding_amount' | 'position_value_usd' | 'max_balance_held' | 'max_balance_held_usd' | 'still_holding_balance_ratio' | 'netflow_amount_usd' | 'netflow_amount' | 'nof_trades', required — Enum for sortable fields in TGM Perp PnL leaderboard.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

TGM Perp PnL leaderboard data

- TGMPerpPnlLeaderboardResponse — Response model for TGM Perp PnL leaderboard endpoint. Contains a list of PnL leaderboard records with pagination and metadata.
  - `data` TGMPerpPnlLeaderboard[], required — List of TGM Perp PnL leaderboard records
    - `trader_address` string, required — Hexadecimal representation of the trader's address.
    - `trader_address_label` string — Nansen name of the trader
    - `price_usd` number — Token price in USD at date_to. Uses latest spot price if date_to is today or later, otherwise the daily median price for that date.
    - `pnl_usd_realised` number — Realised profit and loss in USD.
    - `pnl_usd_unrealised` number — Unrealised profit and loss in USD.
    - `holding_amount` number — Current token balance
    - `position_value_usd` number — Position value in USD (+ve = Long position, -ve = Short position, 0 = Flat)
    - `max_balance_held` number — Maximum amount of tokens held at some point in time.
    - `max_balance_held_usd` number — Maximum amount of tokens in current USD value, held at some point in time.
    - `still_holding_balance_ratio` number — The ratio of current holdings to max balance held.
    - `netflow_amount_usd` number — Netflow amount in USD.
    - `netflow_amount` number — Netflow amount.
    - `roi_percent_total` number — Total ROI.
    - `roi_percent_realised` number — Realised ROI.
    - `roi_percent_unrealised` number — Unrealised ROI.
    - `pnl_usd_total` number — Total PNL in USD.
    - `nof_trades` integer — Number of trades.
  - `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)