{"uid":"cap_TRLaHna2g1u5dD7Nn27LO","slug":"api-nansen-ai-d135e86d","name":"Nansen Perpetual Trading Leaderboard","description":"Get Perpetual Trading Leaderboard Data","url":"https://api.nansen.ai/api/v1/perp-leaderboard","method":"GET","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":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"}],"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":"SortOrder[PerpLeaderboardSortField]","required":["field","direction"],"properties":{"field":{"enum":["total_pnl","roi","account_value"],"type":"string","title":"PerpLeaderboardSortField","description":"Enum for sortable fields in Perp 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 (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels. Note: In a future release, the default will change from true to false — pass premium_labels=true explicitly to preserve premium label behavior."}},"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":[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 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":["x402"],"displayCostAmount":"0.05","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","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":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_HfQCQ_KvABiyOBV2DlUcr","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Retrieves ranked perpetual trading leaderboard data with filtering, sorting, and pagination options for a given date range.","exampleAgentPrompt":"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.","exampleUseCases":null,"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-13T12:58:53.659Z","isFirstParty":false}