# Nansen Perp PnL Leaderboard > Nansen Perp 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-10). Ranks traders by realized and unrealized profit/loss performance for a specific Hyperliquid perpetual contract over a given date range. ## Facts - Endpoint: POST https://api.nansen.ai/api/v1/tgm/perp-pnl-leaderboard?utm_source=zero.xyz - Price: $0.05/call - Payment: MPP - Status: unknown - Last checked: 2026-10-10 - 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-perp-pnl-leaderboard-f7ed6494 - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_IbCx4owLmsNU-Iqgykt_g 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-perp-pnl-leaderboard-f7ed6494 -d '' ``` Example prompt: Show me the top traders ranked by total PnL for BTC perpetual contracts on Hyperliquid from January 1 to January 31 2025, filtering for traders with at least 10 trades. ## When to prefer this Use this endpoint when you need to identify and rank the most profitable traders for a specific Hyperliquid perpetual contract, especially when you want both realized and unrealized PnL breakdowns with ROI metrics. Prefer this over general wallet profilers when the focus is specifically on perpetual contract performance rankings rather than spot trading or cross-chain activity. ## Known failure modes - Invalid or unsupported token_symbol returns empty data or 400 error - Date range too broad may result in timeout or truncated results - Malformed date format (non-ISO 8601) returns validation error - Invalid trader address in filters returns 400 or empty results - Pagination out of bounds returns empty data array - Missing required fields (token_symbol or date) returns 422 validation error ## How this service works Rank traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. 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 perpetual contract. **Key Features:** - Hyperliquid perpetual contracts only (no chain field needed) - Realized and unrealized PnL tracking - ROI calculations and trading patterns - Position size and balance tracking **Request Format:** - `token_symbol`: Perpetual contract symbol (e.g., "BTC", "ETH", "SOL") - `date`: Date range for analysis - `filters`: Optional filters for trader addresses, PnL ranges, etc. - `pagination`: Page and per_page parameters **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 profit/loss performance, each entry containing their wallet address, realized PnL in USD, unrealized PnL in USD, total PnL, ROI percentage, number of trades, current holding amount, position value, netflow amounts, and token price — all scoped to the queried perpetual contract and date range. ## Request schema (JSON Schema) ```json { "type": "object", "title": "TGMPerpPnlLeaderboardRequest", "required": [ "token_symbol", "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." }, "filters": { "anyOf": [ { "type": "object", "title": "TGMPerpPnlLeaderboardFilters", "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. Counts trades since the start of the requested date range." }, "token_price": { "anyOf": [ { "type": "object", "title": "NumericRangeFilter", "properties": { "max": { "anyOf": [ { "type": "number" } ], "title": "Max", "examples": [ 50000, 10000000, 100 ], "descript … (truncated) ``` ## Response schema (JSON Schema) ```json { "type": "object", "title": "TGMPerpPnlLeaderboardResponse", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "title": "TGMPerpPnlLeaderboard", "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 since the start of the requested date range, on the same window as the realised PnL." }, "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": [ { "type": "number" } ], "title": "Roi Percent Total", "examples": [ 15.5 ], "description": … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-perp-pnl-leaderboard-f7ed6494/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)