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

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

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

Rank traders by their profit/loss performance for a specific token. 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 token.

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

- TGMPnlLeaderboardRequest — Request model for TGM PnL leaderboard endpoint. This endpoint provides a token PnL leaderboard showing the most profitable traders for a specific token within a given date range.
  - `chain` 'arbitrum' | 'avalanche' | 'base' | 'bnb' | 'ethereum' | 'hyperevm' | 'hyperliquid' | 'linea' | 'mantle' | 'monad' | 'optimism' | 'plasma' | 'polygon' | 'robinhood' | 'sei' | 'solana' | 'sonic', required — Chains supported for TGM PnL leaderboard endpoint.
  - `token_address` string, required — Token address
  - `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` TGMPnlLeaderboardFilters — Filters for TGM 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)
    - `holding_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)
  - `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` SortOrderTGMPnlLeaderboardSortField[] — 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' | 'holding_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 PnL leaderboard.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

TGM PnL leaderboard data

- TGMPnlLeaderboardResponse — Response model for TGM PnL leaderboard endpoint. Contains a list of PnL leaderboard records with pagination and metadata.
  - `data` TGMPnlLeaderboard[], required — List of TGM 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
    - `holding_usd` number — USD value of token balance
    - `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)