# Nansen Perpetual Trading Leaderboard > Nansen Perpetual Trading Leaderboard is a paid API for AI agents from api.nansen.ai, paid per call via x402, $0.05/call, status unknown (last checked 2026-09-13). Retrieves ranked perpetual trading leaderboard data with filtering, sorting, and pagination options for a given date range. ## Facts - Endpoint: GET https://api.nansen.ai/api/v1/perp-leaderboard - Price: $0.05/call - Payment: x402 - Status: unknown - Last checked: 2026-09-13 - Activations on Zero: 0 - Tags: x402 - Canonical page: https://www.zero.xyz/c/api-nansen-ai-d135e86d - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_TRLaHna2g1u5dD7Nn27LO 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 api-nansen-ai-d135e86d ``` Example prompt: Pull up the Nansen perp trading leaderboard for the date range 2024-01-01 to 2024-01-31, sorted by top PnL, with premium wallet labels enabled and the first page of results. ## When to prefer this Use this endpoint when you need a ranked view of perpetual traders over a specific time window, especially when smart money / wallet label context from Nansen is important. Prefer this over generic DEX analytics when you need curated leaderboard rankings with Nansen's proprietary wallet intelligence layered in. ## Known failure modes - Invalid date format (non-YYYY-MM-DD) returns validation error - Missing or malformed pagination object causes bad request - Unsupported filter keys in filters object return error - Payment not received results in 402 Payment Required - Rate limiting or quota exceeded returns 429 - No data available for specified date range returns empty results ## How this service works Get Perpetual Trading Leaderboard Data ## Output Returns a ranked list of perpetual traders with performance metrics, wallet labels (including smart money tiers when premium labels are enabled), and relevant on-chain analytics for the specified date range and filters. ## 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": 100, "min": 10 } ], "description": "ROI range filter as percentage" }, "total_pnl": { "anyOf": [ { "type": "object", "title": "NumericRangeFilter", "properties": { "max": { "anyOf": [ { "type": "number" } ], "title": "Max", "examples": [ 50000, 10000000, 100 ], "description": "Maximum value (inclusive)" }, "min": { "anyOf": [ { "type": "number" } ], … (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": [ 15.5 ], "description": "Return on investment for the selected timeframe as percentage." }, "total_pnl": { "anyOf": [ { "type": "number" } ], "title": "Total Pnl", "examples": [ 1250.5 ], "description": "Profit and loss for the selected timeframe in USD." }, "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." }, "trader_address": { "type": "string", "title": "Trader Address", "examples": [ "0x28c6c06298d514db089934071355e5743bf21d60" ], "description": "The Ethereum wallet address of the trader." }, "trader_address_label": { "anyOf": [ { "type": "string" } ], "title": "Trader Address Label", "examples": [ "🏦 Binance 14 [0x28c6c0]" ], "description": "The name associated with the address, derived using Nansen's multichain label function for Ethereum." } }, "description": "Individual Perp Leaderboard record.\nRepresents a single trader's perpetual trading performance." }, "title": "Data", "description": "List of Perp Leaderboard records" }, "pagination": { "type": "object", "title": "PaginationInfo", "properties": { "page": { "type": "integer", "title": "Page", "default": 1, "minimum": 1, "description": "Current page number" }, "per_page": { "type": "integer", "title": "Per Page", "default": 10, "maximum": 1000, "minimum": 1, "description": "Number of records per page" }, "is_last_page": { "type": "boolean", "title": "Is Last Page", "default": true, "description": "Whether this is the la … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/api-nansen-ai-d135e86d/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)