# Nansen PnL Leaderboard > Nansen PnL Leaderboard is a paid API for AI agents from Nansen at api.nansen.ai, paid per call via MPP, $0.05/call, status unknown (last checked 2026-10-09). Ranks traders by realized and unrealized profit/loss performance for a specific token on a given chain and date range, including ROI percentages and trading patterns. ## Facts - Endpoint: POST https://api.nansen.ai/api/v1/tgm/pnl-leaderboard?utm_source=zero.xyz - Price: $0.05/call - Payment: MPP - Status: unknown - Last checked: 2026-10-09 - Activations on Zero: 0 - Provider: Nansen - Docs: https://docs.nansen.ai - Website: https://nansen.ai - Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data - Canonical page: https://www.zero.xyz/c/nansen-pnl-leaderboard-ccf8cde4 - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_FvvJciogmfRlZE0HfwPwW 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-pnl-leaderboard-ccf8cde4 -d '' ``` Example prompt: Show me the top traders ranked by PnL for the token at 0x28c6c06298d514db089934071355e5743bf21d60 on Ethereum between January 1 2025 and January 31 2025, including both realized and unrealized profits. ## When to prefer this Use this endpoint when you need to identify and rank individual traders by their profitability (realized + unrealized PnL) for a specific token on a supported chain. It is ideal for smart money analysis, token holder performance benchmarking, and identifying top-performing wallets. Prefer this over general token holder or trade history endpoints when the goal is comparative PnL ranking and ROI analysis across traders. ## Known failure modes - Invalid or unsupported chain returns validation error - Token address not found or no trading activity for the given date range returns empty data array - Malformed date range (e.g. 'from' after 'to') returns 400 error - Missing required fields (chain, token_address, date) returns 422 unprocessable entity - Exceeding filter bounds or invalid numeric range returns 400 error - Rate limit or payment failure returns 402 or 429 error ## How this service works 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. ## Output A paginated list of traders ranked by their profit/loss for the specified token, each entry including realized PnL (USD), unrealized PnL (USD), total PnL (USD), ROI percentage, number of trades, current holding amount and USD value, netflow, max balance held, token price at the end date, and optional entity labels (e.g. smart money, exchange). ## Request schema (JSON Schema) ```json { "type": "object", "title": "TGMPnlLeaderboardRequest", "required": [ "chain", "token_address", "date" ], "properties": { "date": { "type": "object", "title": "DateRange", "properties": { "to": { "anyOf": [ { "type": "string" } ], "title": "To", "examples": [ "2025-01-31T23:59:59Z" ], "description": "End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)" }, "from": { "anyOf": [ { "type": "string" } ], "title": "From", "examples": [ "2025-01-01T00:00:00Z" ], "description": "Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)" } }, "description": "Date range model matching the API schema." }, "chain": { "enum": [ "arbitrum", "arc", "avalanche", "base", "bnb", "ethereum", "hyperevm", "hyperliquid", "linea", "mantle", "monad", "optimism", "plasma", "polygon", "robinhood", "sei", "solana", "sonic", "sui" ], "type": "string", "title": "TGMPnLLeaderboardChain", "description": "Chains supported for TGM PnL leaderboard endpoint." }, "filters": { "anyOf": [ { "type": "object", "title": "TGMPnlLeaderboardFilters", "properties": { "nof_trades": { "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": 10 } ], "description": "Number of trades range filter" }, "holding_usd": … (truncated) ``` ## Response schema (JSON Schema) ```json { "type": "object", "title": "TGMPnlLeaderboardResponse", "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": [ { "typ … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-pnl-leaderboard-ccf8cde4/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)