{"uid":"cap_usHYv-dBcmoeEiuDUy7w9","slug":"nansen-perp-leaderboard-7789d109","name":"Nansen Perp Leaderboard","description":"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.\n\n**What it helps to answer:**\n\n1. **Who are the most profitable perpetual traders in a given timeframe?**\n2. **What is the ROI of the top performing traders?**\n3. **What are the account values of successful perpetual traders?**\n4. **How do trader addresses and labels correlate with performance?**\n5. **What is a top trader holding right now?**\n\n**Key Features:**\n- Trader address and label information\n- Total, realized and unrealized PnL in USD\n- ROI as a fractional ratio (0.15 means 15%)\n- Traded notional and fill count over the timeframe\n- The five largest open positions per trader\n- Account value tracking\n- Flexible filtering and sorting options\n\n**Label Tier Control (`premium_labels`):**\nWhen 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.","url":"https://api.nansen.ai/api/v1/perp-leaderboard?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"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":{"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":[{"min":1000}],"description":"Total PnL range filter in USD"},"account_value":{"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":[{"min":10000}],"description":"Account value range filter in USD. Note: Only the top 500K traders have account value data available."},"trader_address":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Trader Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Trader Address Label","examples":["%Smart HL Perps Trader%","%Binance%","%.eth%"],"description":"Filter by wallet display name. Use LIKE patterns (%) for partial matching. Note: This filters by the wallet's display name, not by label category. To filter by smart money labels, use include_smart_money_labels instead."},"exclude_smart_money_labels":{"anyOf":[{"type":"array","items":{"enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"type":"string","title":"SmartMoneyFilterType","description":"Filter by smart money label type."}}],"title":"Exclude Smart Money Labels","examples":[["30D Smart Trader"]],"description":"Exclude smart money labels"},"include_smart_money_labels":{"anyOf":[{"type":"array","items":{"enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"type":"string","title":"SmartMoneyFilterType","description":"Filter by smart money label type."}}],"title":"Include Smart Money Labels","examples":[["Smart HL Perps Trader"]],"description":"Filter to include only traders with these smart money labels. For Hyperliquid, use 'Smart HL Perps Trader'. See SmartMoneyFilterType enum for valid values."}},"description":"Filters for Perp Leaderboard endpoint.\n\nThese filters control which traders are included in the leaderboard.","additionalProperties":false}],"examples":[{"total_pnl":{"min":1000},"account_value":{"min":10000}}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"PerpLeaderboardSortOrder","required":["field","direction"],"properties":{"field":{"enum":["total_pnl","realized_pnl_usd","unrealized_pnl_usd","roi","volume_usd","total_trades","account_value"],"type":"string","title":"PerpLeaderboardSortField","description":"Sort field for the perpetuals leaderboard."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering"},"pagination":{"type":"object","title":"PaginationRequest","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Page number (1-based)"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page (max 1000)"}},"description":"Pagination parameters for API requests."},"premium_labels":{"anyOf":[{"type":"boolean"}],"title":"Premium Labels","description":"Controls label tier in the response. When null/omitted or false (the default), returns free-tier labels at the standard credit cost for this endpoint. When true, returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan."}},"description":"Request model for Perp Leaderboard endpoint.\nThis endpoint provides a perpetual trading leaderboard showing the most profitable\ntraders within a given date range.","additionalProperties":false},"responseSchema":{"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 market symbol the position is in."},"side":{"type":"string","title":"Side","examples":["long"],"description":"Position direction: 'long' or 'short'."},"size_base":{"type":"number","title":"Size Base","examples":[12.5],"description":"Position size in base/coin units (absolute); `side` carries direction."},"entry_price":{"type":"number","title":"Entry Price","examples":[60000],"description":"Average entry price of the position."},"position_value_usd":{"type":"number","title":"Position Value Usd","examples":[125000],"description":"Notional value of the position in USD."},"unrealized_pnl_usd":{"type":"number","title":"Unrealized Pnl Usd","examples":[5000],"description":"Unrealized PnL on the position, in USD."}},"description":"A single open perpetual position held by a leaderboard trader."},"title":"Top Positions","description":"The trader's five largest open positions by absolute position value, largest first. Covers only positions in coins the trader traded during the selected timeframe, so a position held through the window in a coin that was not traded is not listed. Empty for a trader with no such open position."},"trader_address":{"type":"string","title":"Trader Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"The Ethereum wallet address of the trader."},"realized_pnl_usd":{"anyOf":[{"type":"number"}],"title":"Realized Pnl Usd","examples":[800.25],"description":"Realized profit and loss for the selected timeframe in USD."},"unrealized_pnl_usd":{"anyOf":[{"type":"number"}],"title":"Unrealized Pnl Usd","examples":[450.25],"description":"Unrealized profit and loss in USD on positions still open, valued at the current mark price."},"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 last page"}},"description":"Pagination information for API responses."}},"description":"Response model for Perp Leaderboard endpoint.\nContains a list of leaderboard records with pagination and metadata."},"example":null,"exampleRequest":null,"tags":["blockchain","smart-money","wallet","tokens","defi","analytics","profiler","dex","pnl","onchain","prediction-market","data"],"displayCostAmount":"0.05","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.05/call","primary":{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_QuJKUh0N6hWsndfdtZrKN","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":"Nansen","brandSlug":"nansen","brandBaseUrl":"https://nansen.ai","brandDocsUrl":"https://docs.nansen.ai","whatItDoes":"Returns ranked perpetual trading performance data (PnL, ROI, account value) for top traders within a specified date range.","exampleAgentPrompt":"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.","exampleUseCases":null,"resultDescription":"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).","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-12T18:40:34.580Z","isFirstParty":false,"canonicalSlug":"nansen-perp-leaderboard-7789d109"}