{"uid":"cap_IbCx4owLmsNU-Iqgykt_g","slug":"nansen-perp-pnl-leaderboard-f7ed6494","name":"Nansen Perp PnL Leaderboard","description":"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.\n\n**Key Features:**\n- Hyperliquid perpetual contracts only (no chain field needed)\n- Realized and unrealized PnL tracking\n- ROI calculations and trading patterns\n- Position size and balance tracking\n\n**Request Format:**\n- `token_symbol`: Perpetual contract symbol (e.g., \"BTC\", \"ETH\", \"SOL\")\n- `date`: Date range for analysis\n- `filters`: Optional filters for trader addresses, PnL ranges, etc.\n- `pagination`: Page and per_page parameters\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/tgm/perp-pnl-leaderboard?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"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],"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":0.01}],"description":"Token price range filter"},"holding_amount":{"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":100}],"description":"Holding amount range filter"},"trader_address":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Trader Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"Trader address filter"},"max_balance_held":{"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":100}],"description":"Maximum balance held range filter"},"pnl_usd_realised":{"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":"Realized PnL range filter in USD"},"pnl_usd_unrealised":{"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":"Unrealized PnL range filter in USD"},"position_value_usd":{"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":"Position value range filter in USD (+ve = Long position, -ve = Short position, 0 = Flat)"},"max_balance_held_usd":{"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":"Maximum balance held range filter in USD"},"trader_address_label":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Trader Address Label","examples":["Smart Money","%Fund%"],"description":"Trader name filter"},"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":[["Fund","Smart Trader"]],"description":"Include smart money labels"},"still_holding_balance_ratio":{"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":"Still holding balance ratio range filter"}},"description":"Filters for TGM Perp PnL leaderboard endpoint.\n\nThese filters control which traders are included in the leaderboard.","additionalProperties":false}],"examples":[{"pnl_usd_realised":{"min":1000},"position_value_usd":{"min":1000}}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"TGMPerpPnlLeaderboardSortOrder","required":["field","direction"],"properties":{"field":{"enum":["pnl_usd_realised","pnl_usd_unrealised","pnl_usd_total","roi_percent_total","roi_percent_realised","roi_percent_unrealised","holding_amount","position_value_usd","max_balance_held","max_balance_held_usd","still_holding_balance_ratio","netflow_amount_usd","netflow_amount","nof_trades"],"type":"string","title":"TGMPerpPnlLeaderboardSortField","description":"Enum for sortable fields in TGM Perp PnL 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."},"token_symbol":{"type":"string","title":"Token Symbol","examples":["BTC"],"description":"Perpetual contract symbol (e.g., BTC, ETH, SOL)"},"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 TGM Perp PnL leaderboard endpoint.\nSimplified version that only supports Hyperliquid perpetual contracts."},"responseSchema":{"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":"Total ROI."},"netflow_amount_usd":{"anyOf":[{"type":"number"}],"title":"Netflow Amount Usd","examples":[2500.75],"description":"Netflow amount in USD."},"pnl_usd_unrealised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Unrealised","examples":[100.25],"description":"Unrealised profit and loss in USD."},"position_value_usd":{"anyOf":[{"type":"number"}],"title":"Position Value Usd","examples":[6000],"description":"Position value in USD (+ve = Long position, -ve = Short position, 0 = Flat)"},"max_balance_held_usd":{"anyOf":[{"type":"number"}],"title":"Max Balance Held Usd","examples":[12000],"description":"Maximum amount of tokens in current USD value, held at some point in time."},"roi_percent_realised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Realised","examples":[12.3],"description":"Realised ROI."},"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","examples":["🏦 Binance 14 [0x28c6c0]"],"description":"Nansen name of the trader"},"roi_percent_unrealised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Unrealised","examples":[3.2],"description":"Unrealised ROI."},"still_holding_balance_ratio":{"anyOf":[{"type":"number"}],"title":"Still Holding Balance Ratio","examples":[0.5],"description":"The ratio of current holdings to max balance held."}},"description":"Individual TGM Perp PnL leaderboard record.\nRepresents a single trader's PnL performance for a specific perpetual contract."},"title":"Data","description":"List of TGM Perp PnL 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 TGM Perp PnL leaderboard endpoint.\nContains a list of PnL 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_C04smhylc-MeA5NSl6h8f","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":"Ranks traders by realized and unrealized profit/loss performance for a specific Hyperliquid perpetual contract over a given date range.","exampleAgentPrompt":"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.","exampleUseCases":null,"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-10T18:42:30.267Z","isFirstParty":false,"canonicalSlug":"nansen-perp-pnl-leaderboard-f7ed6494"}