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

# Get historical "Token God Mode" (TGM) PnL leaderboard (Beta)

`POST /api/v1beta1/tgm/historical-pnl-leaderboard`

**Beta — subject to breaking changes.**

Per-trader PnL statistics for a specific token over a historical date range with
temporally-correct labels resolved at `date_to`. Uses label history tables to
avoid forward-looking bias.

**Key differences from `/tgm/pnl-leaderboard`:**
- Accepts an explicit `date_range` with Date-only granularity
- Labels resolved at `date_to`, not the current state
- Supports page-based pagination via `per_page` and `page`
- Filter parameters are applied server-side before pagination

## Request body

- TGMHistoricalPnlLeaderboardRequest — Request model for the historical PnL leaderboard endpoint. Returns per-trader PnL statistics for a token over a date range with temporally-correct labels resolved at date_to. Uses label history tables to avoid forward-looking bias. Supports page-based pagination via per_page and page.
  - `chain` 'base' | 'bnb' | 'ethereum' | 'solana', required — Chains supported for the TGM historical endpoints (pnl-leaderboard, who-bought-sold, top-holders, token-flow-summary).
  - `token_address` string, required — Token contract address
  - `date_range` 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` TGMHistoricalPnlLeaderboardFilters — Filters for the historical PnL leaderboard endpoint.
    - `trader_address` string[] — Filter to specific trader addresses (empty = all traders)
    - `pnl_usd_total` 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)
    - `roi_percent_total` 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)
    - `roi_percent_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)
    - `roi_percent_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)
    - `netflow_amount_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)
    - `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)
    - `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)
    - `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)
    - `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)
    - `nof_buys` 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_sells` 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)
    - `bought_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)
    - `sold_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)
    - `bought_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)
    - `sold_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)
  - `order_by` SortOrderTGMHistoricalPnlLeaderboardSortField[] — Sort order. Defaults to pnl_usd_total DESC. Only the first element is used.
    - `field` 'pnl_usd_total' | 'roi_percent_total' | 'pnl_usd_realised' | 'roi_percent_realised' | 'pnl_usd_unrealised' | 'roi_percent_unrealised' | 'holding_usd' | 'holding_amount' | 'nof_trades' | 'still_holding_balance_ratio' | 'netflow_amount_usd' | 'max_balance_held' | 'max_balance_held_usd' | 'nof_buys' | 'nof_sells' | 'bought_amount' | 'sold_amount' | 'bought_usd' | 'sold_usd', required — Sortable fields for the historical PnL leaderboard endpoint.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.
  - `apply_blacklist_filter` boolean — When True, exclude blacklisted addresses from the results. Defaults to True.

## Response `200`

Historical TGM PnL leaderboard data

- TGMHistoricalPnlLeaderboardResponse — Response model for the historical PnL leaderboard endpoint.
  - `data` TGMPnlLeaderboard[], required — List of historical 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)