# Nansen Historical PnL Leaderboard > Nansen Historical PnL Leaderboard is a paid API for AI agents from api.nansen.ai, paid per call via x402, $0.25/call, status unknown (last checked 2026-09-14). Returns per-trader profit/loss statistics for a specific token over a historical date range, with labels resolved at the end date to avoid forward-looking bias. ## Facts - Endpoint: GET https://api.nansen.ai/api/v1beta1/tgm/historical-pnl-leaderboard - Price: $0.25/call - Payment: x402 - Status: unknown - Last checked: 2026-09-14 - Activations on Zero: 0 - Tags: x402 - Canonical page: https://www.zero.xyz/c/nansen-historical-pnl-leaderboard-bce2e827 - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_Lndh6nM3AtrG7_ogsSD4V Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently. ## How to call it through Zero Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`): ```sh zero fetch --capability nansen-historical-pnl-leaderboard-bce2e827 ``` Example prompt: Show me the top 25 traders by total PnL for the USDC token at address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Ethereum from January 1 2024 to March 31 2024, filtering for traders with at least 5 buys. ## When to prefer this Use this endpoint when you need historical PnL rankings for a token over a specific past date range and require temporally-correct labels (no forward-looking bias). Prefer this over /tgm/pnl-leaderboard when you need date-bounded analysis, explicit pagination, or server-side filtering before pagination. Choose this for backtesting trader performance, historical smart money analysis, or quarterly reporting. ## Known failure modes - Invalid or unsupported chain name returns 422 validation error - Token address not found or not tracked returns empty data array - Date range with date_from after date_to returns validation error - Unsupported chain for historical data returns error or empty result - Invalid filter values (e.g. min > max) return 422 validation error - Missing required fields (chain, token_address, date_range) return 422 - Exceeding API rate limits or invalid API key returns 401/429 - Page number beyond available results returns empty data with valid pagination metadata ## How this service works Get historical "Token God Mode" (TGM) PnL leaderboard (Beta) ## Output A paginated list of trader addresses with their PnL metrics (realized, unrealized, total), ROI percentage, number of trades, buy/sell counts, holding amounts and USD values, netflow, and max balance held — all computed with labels resolved at the specified end date. Also includes pagination metadata (total records, current page, per-page count). ## Request schema (JSON Schema) ```json { "type": "object", "title": "TGMHistoricalPnlLeaderboardRequest", "required": [ "chain", "token_address", "date_range" ], "properties": { "chain": { "enum": [ "arbitrum", "avalanche", "base", "bnb", "ethereum", "hyperevm", "injective", "iotaevm", "linea", "mantle", "mantra", "monad", "near", "optimism", "plasma", "polygon", "ronin", "scroll", "sei", "solana", "sonic", "starknet", "sui", "ton", "tron" ], "type": "string", "title": "TGMChain", "description": "Chains supported in TGM (Token God Mode) endpoints." }, "filters": { "anyOf": [ { "type": "object", "title": "TGMHistoricalPnlLeaderboardFilters", "properties": { "nof_buys": { "anyOf": [ { "type": "object", "title": "NumericRangeFilter", "properties": { "max": { "anyOf": [ { "type": "number" } ], "title": "Max", "examples": [ 50000, 10000000, 100 ], "description": "Maximum value (inclusive)" }, "min": { "anyOf": [ { "type": "number" } ], "title": "Min", "examples": [ 1000, 1000000, -50, 0 ], "description": "Minimum value (inclusive)" } }, "description": "Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75" } ], "examples": [ { "max": 100, "min": 1 } ], "description": "Number of buy trades range filter" }, "sold_usd": { "anyOf": [ { "type": "object", "title": "NumericRangeFilter", "properties": { "max": { "anyOf": [ { "type": "number" } ], "title": "Max", "examples": [ 50000, 10000000, 100 ], "description": "Maximum value (inclusive)" }, "min": { "anyOf": [ { "type": "number" } ], "title": "Min", … (truncated) ``` ## Response schema (JSON Schema) ```json { "type": "object", "title": "TGMHistoricalPnlLeaderboardResponse", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "title": "TGMPnlLeaderboard", "required": [ "trader_address" ], "properties": { "price_usd": { "anyOf": [ { "type": "number" } ], "title": "Price Usd", "examples": [ 1.23 ], "description": "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." }, "nof_trades": { "anyOf": [ { "type": "integer" } ], "title": "Nof Trades", "examples": [ 25 ], "description": "Number of trades." }, "holding_usd": { "anyOf": [ { "type": "number" } ], "title": "Holding Usd", "examples": [ 6000 ], "description": "USD value of token balance" }, "pnl_usd_total": { "anyOf": [ { "type": "number" } ], "title": "Pnl Usd Total", "examples": [ 1350.75 ], "description": "Total PNL in USD." }, "holding_amount": { "anyOf": [ { "type": "number" } ], "title": "Holding Amount", "examples": [ 5000 ], "description": "Current token balance" }, "netflow_amount": { "anyOf": [ { "type": "number" } ], "title": "Netflow Amount", "examples": [ 1500 ], "description": "Netflow amount." }, "trader_address": { "type": "string", "title": "Trader Address", "examples": [ "0x28c6c06298d514db089934071355e5743bf21d60" ], "description": "Hexadecimal representation of the trader's address." }, "max_balance_held": { "anyOf": [ { "type": "number" } ], "title": "Max Balance Held", "examples": [ 10000 ], "description": "Maximum amount of tokens held at some point in time." }, "pnl_usd_realised": { "anyOf": [ { "type": "number" } ], "title": "Pnl Usd Realised", "examples": [ 1250.5 ], "description": "Realised profit and loss in USD." }, "roi_percent_total": { "anyOf": [ { … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-historical-pnl-leaderboard-bce2e827/health.json - [Zero catalog index](https://www.zero.xyz/llms.txt) - [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)