--- 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` ## Request - Base URL: `https://api.nansen.ai` - URL: `https://api.nansen.ai/api/v1beta1/tgm/historical-pnl-leaderboard` - Auth: API key in header `apiKey` - TypeScript: (a function with typed inputs; its response is checked against the schema) **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.dev/nansen/apis/nansen-api.md) - [All operations](https://skmtc.dev/nansen/apis/nansen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nansen/apis/nansen-api/revisions/02a4d2e7d827?raw)