{"uid":"cap_1pcVX2JHgedm3aA4AeQdZ","slug":"api-nansen-ai-bfe84718","name":"Nansen TGM Perp PnL Leaderboard","description":"Get \"Token God Mode\" (TGM) perp PnL leaderboard data","url":"https://api.nansen.ai/api/v1/tgm/perp-pnl-leaderboard","method":"GET","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"},"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":"SortOrder[TGMPerpPnlLeaderboardSortField]","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 (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 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."},"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":{"request":{"date":{"to":"2025-01-31","from":"2025-01-01"},"token_symbol":"ETH"},"response":{"data":[{"price_usd":2016.8,"nof_trades":56706,"pnl_usd_total":107485057.826948,"holding_amount":0,"netflow_amount":0,"trader_address":"0x2ea18c23f72a4b6172c55b411823cdc5335923f4","max_balance_held":0,"pnl_usd_realised":107485057.826948,"roi_percent_total":0.07301943908729798,"netflow_amount_usd":0,"pnl_usd_unrealised":0,"position_value_usd":0,"max_balance_held_usd":0,"roi_percent_realised":0.07301943908729798,"trader_address_label":"Garrett Jin's client: Bitcoin OG [0x2ea18c]","roi_percent_unrealised":null,"still_holding_balance_ratio":0},{"price_usd":2016.8,"nof_trades":235040,"pnl_usd_total":25950946.320779998,"holding_amount":0.43,"netflow_amount":0,"trader_address":"0xd47587702a91731dc1089b5db0932cf820151a91","max_balance_held":0,"pnl_usd_realised":25950963.058617,"roi_percent_total":0.012443577279500507,"netflow_amount_usd":0,"pnl_usd_unrealised":-16.737836999999978,"position_value_usd":861,"max_balance_held_usd":0,"roi_percent_realised":0.012443585305356891,"trader_address_label":"​​Trading Bot [0xd47587]","roi_percent_unrealised":-0.01943152698786524,"still_holding_balance_ratio":0},{"price_usd":2016.8,"nof_trades":50862,"pnl_usd_total":14662553.653878,"holding_amount":40000.58,"netflow_amount":0,"trader_address":"0xa5b0edf6b55128e0ddae8e51ac538c3188401d41","max_balance_held":0,"pnl_usd_realised":25160764.072004,"roi_percent_total":0.009134188847960975,"netflow_amount_usd":0,"pnl_usd_unrealised":-10498210.418126002,"position_value_usd":80673167,"max_balance_held_usd":0,"roi_percent_realised":0.0156741571773817,"trader_address_label":"Token Millionaire [0xa5b0ed]","roi_percent_unrealised":-0.1301326174040478,"still_holding_balance_ratio":0},{"price_usd":2016.8,"nof_trades":9135,"pnl_usd_total":24954463.23829996,"holding_amount":0,"netflow_amount":0,"trader_address":"0x86523927bffeafe2e532f0218feb1f3c29f6120d","max_balance_held":0,"pnl_usd_realised":24954463.23829996,"roi_percent_total":0.244023432315326,"netflow_amount_usd":0,"pnl_usd_unrealised":0,"position_value_usd":0,"max_balance_held_usd":0,"roi_percent_realised":0.244023432315326,"trader_address_label":"HL Perps Scalper [0x865239]","roi_percent_unrealised":null,"still_holding_balance_ratio":0},{"price_usd":2016.8,"nof_trades":77872,"pnl_usd_total":23435964.701966986,"holding_amount":0,"netflow_amount":0,"trader_address":"0xb0a55f13d22f66e6d495ac98113841b2326e9540","max_balance_held":0,"pnl_usd_realised":23435964.701966986,"roi_percent_total":0.014071507907838109,"netflow_amount_usd":0,"pnl_usd_unrealised":0,"position_value_usd":0,"max_balance_held_usd":0,"roi_percent_realised":0.014071507907838109,"trader_address_label":"Hyperliquid: HLP Liquidator 2 [0xb0a55f]","roi_percent_unrealised":null,"still_holding_balance_ratio":0},{"price_usd":2016.8,"nof_trades":227180,"pnl_usd_total":21934320.517991997,"holding_amount":0,"netflow_amount":0,"trader_address":"0x0ddf9bae2af4b874b96d287a5ad42eb47138a902","max_balance_held":0,"pnl_usd_realised":21934320.517991997,"roi_percent_total":0.0043283138583025986,"netflow_amount_usd":0,"pnl_usd_unrealised":0,"position_value_usd":0,"max_balance_held_usd":0,"roi_percent_realised":0.0043283138583025986,"trader_address_label":"​​Pension Fund: pension-usdt.eth [0x0ddf9b]","roi_percent_unrealised":null,"still_holding_balance_ratio":0},{"price_usd":2016.8,"nof_trades":221680,"pnl_usd_total":20736159.924524006,"holding_amount":0,"netflow_amount":0,"trader_address":"0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036","max_balance_held":0,"pnl_usd_realised":20736159.924524006,"roi_percent_total":0.004343866781042852,"netflow_amount_usd":0,"pnl_usd_unrealised":0,"position_value_usd":0,"max_balance_held_usd":0,"roi_percent_realised":0.004343866781042852,"trader_address_label":"Former Smart Trader [0x2ba553]","roi_percent_unrealised":null,"still_holding_balance_ratio":0},{"price_usd":2016.8,"nof_trades":16700,"pnl_usd_total":20141491.105015,"holding_amount":0,"netflow_amount":0,"trader_address":"0xfa6af5f4f7440ce389a1e650991eea45c161e13e","max_balance_held":0,"pnl_usd_realised":20141491.105015,"roi_percent_total":0.04301571839776769,"netflow_amount_usd":0,"pnl_usd_unrealised":0,"position_value_usd":0,"max_balance_held_usd":0,"roi_percent_realised":0.04301571839776769,"trader_address_label":"👤 The White Whale [0xfa6af5]","roi_percent_unrealised":null,"still_holding_balance_ratio":0},{"price_usd":2016.8,"nof_trades":143286,"pnl_usd_total":19317265.269562002,"holding_amount":-1037.01,"netflow_amount":0,"trader_address":"0xcac19662ec88d23fa1c81ac0e8570b0cf2ff26b3","max_balance_held":0,"pnl_usd_realised":19227942.606986,"roi_percent_total":0.1290055543435661,"netflow_amount_usd":0,"pnl_usd_unrealised":89322.66257600015,"position_value_usd":-2091438,"max_balance_held_usd":0,"roi_percent_realised":0.12840903514479435,"trader_address_label":"🤓 Galaxy Digital [0xcac196]","roi_percent_unrealised":0.042708736247233,"still_holding_balance_ratio":0},{"price_usd":2016.8,"nof_trades":21586,"pnl_usd_total":8616238.201381996,"holding_amount":40000,"netflow_amount":0,"trader_address":"0x6c8512516ce5669d35113a11ca8b8de322fd84f6","max_balance_held":0,"pnl_usd_realised":19090482.336541,"roi_percent_total":0.017940637044931342,"netflow_amount_usd":0,"pnl_usd_unrealised":-10474244.135159004,"position_value_usd":80672000,"max_balance_held_usd":0,"roi_percent_realised":0.03974999374525424,"trader_address_label":"HL Perps Whale [0x6c8512]","roi_percent_unrealised":-0.12983741738346644,"still_holding_balance_ratio":0}],"pagination":{"page":1,"per_page":10,"is_last_page":false}}},"exampleRequest":{"date":{"to":"2025-01-31","from":"2025-01-01"},"token_symbol":"ETH"},"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":"mpp","network":"tempo","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.05","per":"call","confidence":"exact"},{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_L0U6gBMx72ie3_9wvhTgN","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_uCY206U0bo4BI4x9PJ_wJ","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":"Returns a leaderboard of traders ranked by perpetual contract profit and loss (PnL) within the Token God Mode (TGM) analytics suite.","exampleAgentPrompt":"Pull up the Nansen TGM perp PnL leaderboard for the top traders — I want to see which wallet addresses are winning the most on perpetual contracts right now.","exampleUseCases":null,"resultDescription":"A ranked list of trader wallet addresses with their associated perpetual contract PnL metrics, showing top performers by profit and loss in the TGM analytics universe.","failureModes":["Invalid or missing token parameter returns 400 error","Unsupported filter or sort field causes malformed request error","Rate limit exceeded returns 429 response","Authentication or payment failure returns 401/402","No data available for the specified time range returns empty leaderboard"],"whenToPreferThis":"Use this endpoint when you need a ranked view of top perpetual traders by PnL, specifically within Nansen's Token God Mode analytics framework. Prefer this over generic on-chain data sources when smart money wallet labeling and PnL ranking context are needed together.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-13T12:54:01.073Z","isFirstParty":false}