# Nansen Perp Leaderboard > Nansen Perp 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-12). Returns ranked perpetual trading performance data (PnL, ROI, account value) for top traders within a specified date range. ## Facts - Endpoint: POST https://api.nansen.ai/api/v1/perp-leaderboard?utm_source=zero.xyz - Price: $0.05/call - Payment: MPP - Status: unknown - Last checked: 2026-10-12 - 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-leaderboard-7789d109 - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_usHYv-dBcmoeEiuDUy7w9 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-leaderboard-7789d109 -d '' ``` Example prompt: Pull the Nansen perp leaderboard for January 2025 (from 2025-01-01 to 2025-01-31), filter for traders with at least $5,000 total PnL, sort by ROI descending, and show me the top 20 results. ## When to prefer this Use this endpoint when you need to identify the best-performing perpetual traders on-chain over a specific time window, especially for smart money research, copy-trading analysis, or competitive benchmarking. Prefer this over individual trade lookups when you want aggregated leaderboard-style rankings rather than raw trade history. ## Known failure modes - Missing required 'date' field returns validation error - Invalid date format (not YYYY-MM-DD) causes request failure - Filters with inverted min/max (min > max) may return empty results - Account value data may be null or 0 for traders outside the top 500K - Requesting very large page sizes (>1000) will be rejected - Overly restrictive filter combinations may yield zero results ## How this service works Get perpetual trading leaderboard data showing the most profitable traders within a given date range. This endpoint provides trader performance metrics including total PnL, ROI, and account values. **What it helps to answer:** 1. **Who are the most profitable perpetual traders in a given timeframe?** 2. **What is the ROI of the top performing traders?** 3. **What are the account values of successful perpetual traders?** 4. **How do trader addresses and labels correlate with performance?** 5. **What is a top trader holding right now?** **Key Features:** - Trader address and label information - Total, realized and unrealized PnL in USD - ROI as a fractional ratio (0.15 means 15%) - Traded notional and fill count over the timeframe - The five largest open positions per trader - Account value tracking - Flexible filtering and sorting options **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 trader records, each containing the trader's Ethereum wallet address, optional human-readable label (e.g. exchange name), total PnL in USD for the period, ROI as a percentage, and current account value in USD. Includes pagination metadata (current page, per-page count, is_last_page). ## Request schema (JSON Schema) ```json { "type": "object", "title": "PerpLeaderboardRequest", "required": [ "date" ], "properties": { "date": { "type": "object", "title": "DateOnlyRange", "properties": { "to": { "anyOf": [ { "type": "string" } ], "title": "To", "examples": [ "2025-01-31" ], "description": "End date in YYYY-MM-DD format" }, "from": { "anyOf": [ { "type": "string" } ], "title": "From", "examples": [ "2025-01-01" ], "description": "Start date in YYYY-MM-DD format" } }, "description": "Date range model that only accepts YYYY-MM-DD format (no time components)." }, "filters": { "anyOf": [ { "type": "object", "title": "PerpLeaderboardFilters", "properties": { "roi": { "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": 1, "min": 0.1 } ], "description": "ROI range filter as a fractional ratio (0.15 means 15%). Signed, so a loss is negative and a min of 0 keeps profitable traders only." }, "total_pnl": { "anyOf": [ { "type": "object", "title": "NumericRangeFilter", "properties": { "max": { "anyOf": [ { "type": "number" } ], "title": "Max", "examples": [ 50000, 10000000, 100 ], "description": "Maximum value (inclusive)" }, "min" … (truncated) ``` ## Response schema (JSON Schema) ```json { "type": "object", "title": "PerpLeaderboardResponse", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "title": "PerpLeaderboard", "required": [ "trader_address" ], "properties": { "roi": { "anyOf": [ { "type": "number" } ], "title": "Roi", "examples": [ 0.155 ], "description": "Return on investment for the selected timeframe as a fractional ratio (0.15 means 15%, -0.20 means -20%). Computed as total_pnl divided by traded notional in USD plus the notional of positions still open, so it measures PnL per dollar traded rather than return on capital: a position that was opened and closed contributes both fills to the denominator." }, "total_pnl": { "anyOf": [ { "type": "number" } ], "title": "Total Pnl", "examples": [ 1250.5 ], "description": "Profit and loss for the selected timeframe in USD, realized plus unrealized." }, "volume_usd": { "anyOf": [ { "type": "number" } ], "title": "Volume Usd", "examples": [ 5000000 ], "description": "Traded notional in USD over the selected timeframe. Both the opening and the closing fill of a position count." }, "total_trades": { "anyOf": [ { "type": "integer" } ], "title": "Total Trades", "examples": [ 420 ], "description": "Number of fills over the selected timeframe." }, "account_value": { "anyOf": [ { "type": "number" } ], "title": "Account Value", "examples": [ 10000 ], "description": "Current total account value in USD. Note: Account value data is only available for the top 500K traders due to upstream data limitations. Traders outside the top 500K may show 0 or null values." }, "top_positions": { "type": "array", "items": { "type": "object", "title": "PerpLeaderboardPosition", "required": [ "coin", "side", "size_base", "position_value_usd", "entry_price", "unrealized_pnl_usd" ], "properties": { "coin": { "type": "string", "title": "Coin", "examples": [ "BTC" ], "description": "Perp mark … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-perp-leaderboard-7789d109/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)