{"uid":"cap_rV5_Mh7FjavC1mTxtbd3l","slug":"api-nansen-ai-10769572","name":"Nansen Token God Mode PnL Leaderboard","description":"Get \"Token God Mode\" (TGM) PnL leaderboard data","url":"https://api.nansen.ai/api/v1/tgm/pnl-leaderboard","method":"GET","headers":{},"bodySchema":{"type":"object","title":"TGMPnlLeaderboardRequest","required":["chain","token_address","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."},"chain":{"enum":["arbitrum","avalanche","base","bnb","ethereum","hyperevm","linea","mantle","monad","optimism","plasma","polygon","ronin","scroll","sei","solana","sonic"],"type":"string","title":"TGMPnLLeaderboardChain","description":"Chains supported for TGM PnL leaderboard endpoint."},"filters":{"anyOf":[{"type":"object","title":"TGMPnlLeaderboardFilters","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"},"holding_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":"Holding value range filter in USD"},"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"},"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"},"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 PnL leaderboard endpoint.\n\nThese filters control which traders are included in the leaderboard.","additionalProperties":false}],"examples":[{"holding_usd":{"min":1000},"pnl_usd_realised":{"min":1000}}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"SortOrder[TGMPnlLeaderboardSortField]","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","holding_usd","max_balance_held","max_balance_held_usd","still_holding_balance_ratio","netflow_amount_usd","netflow_amount","nof_trades"],"type":"string","title":"TGMPnlLeaderboardSortField","description":"Enum for sortable fields in TGM 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_address":{"type":"string","title":"Token Address","examples":["0x6982508145454ce325ddbe47a25d4ec3d2311933"],"description":"Token address"},"premium_labels":{"anyOf":[{"type":"boolean"}],"title":"Premium Labels","description":"Controls label tier in the response. When null/omitted, defaults to true (premium labels filtered by subscription plan). When false, returns free-tier labels for all users. When true, returns premium labels (filtered by subscription plan). 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 PnL leaderboard endpoint.\nThis endpoint provides a token PnL leaderboard showing the most profitable\ntraders for a specific token within a given date range.","additionalProperties":false},"responseSchema":{"type":"object","title":"TGMPnlLeaderboardResponse","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","title":"TGMPnlLeaderboard","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."},"holding_usd":{"anyOf":[{"type":"number"}],"title":"Holding Usd","examples":[6000],"description":"USD value of token balance"},"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."},"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 PnL leaderboard record.\nRepresents a single trader's PnL performance for a specific token."},"title":"Data","description":"List of TGM 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 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"},"chain":"ethereum","pagination":{"page":1,"per_page":10},"token_address":"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"},"response":{"data":[{"price_usd":3293.558694559951,"nof_trades":7181,"holding_usd":55312905.94435069,"pnl_usd_total":3018676.0398597396,"holding_amount":16794.26756101609,"netflow_amount":2569.0987022941554,"trader_address":"0xbbbbbbbbbb9cc5e90e3b3af64bdaf62c37eeffcb","max_balance_held":90355.66908950031,"pnl_usd_realised":3201506.7945587463,"roi_percent_total":0.0001812295616673112,"netflow_amount_usd":4630526.173786201,"pnl_usd_unrealised":-182830.75469900685,"max_balance_held_usd":297591699.5325056,"roi_percent_realised":0.00019220600865794098,"trader_address_label":"🤖 Morpho: Morpho Blue [0xbbbbbb]","roi_percent_unrealised":-0.003294500903564681,"still_holding_balance_ratio":0.18586844334449903},{"price_usd":3293.558694559951,"nof_trades":2,"holding_usd":0,"pnl_usd_total":660803.1727021682,"holding_amount":0,"netflow_amount":-744.2897753496442,"trader_address":"0x24c098e495dc3c1ee7942d68453fc4a833a26b07","max_balance_held":745.8457164835817,"pnl_usd_realised":660803.1727021682,"roi_percent_total":0.3386490407876173,"netflow_amount_usd":-2606816.5873997663,"pnl_usd_unrealised":0,"max_balance_held_usd":2456486.6443247967,"roi_percent_realised":0.3386490407876173,"trader_address_label":"​​Yield Farmer [0x24c098]","roi_percent_unrealised":null,"still_holding_balance_ratio":0},{"price_usd":3293.558694559951,"nof_trades":15144,"holding_usd":2481251.2111359523,"pnl_usd_total":619147.0962186427,"holding_amount":753.3648072628229,"netflow_amount":126.29820667604278,"trader_address":"0x5dc62cea20b0e7c3607adcc61a885ff9369dbc60","max_balance_held":1003.0342894918998,"pnl_usd_realised":619925.5812018639,"roi_percent_total":0.0008187794007784396,"netflow_amount_usd":-228889.30883582216,"pnl_usd_unrealised":-778.4849832213305,"max_balance_held_usd":3303552.3050978095,"roi_percent_realised":0.0008198088935629003,"trader_address_label":"​​🤖 DEX/CEX Trading Bot [0x5dc62c]","roi_percent_unrealised":-0.0003136485370979026,"still_holding_balance_ratio":0.7510857955259432},{"price_usd":3293.558694559951,"nof_trades":24,"holding_usd":0,"pnl_usd_total":350119.9797159946,"holding_amount":0,"netflow_amount":0,"trader_address":"0xee2826453a4fd5afeb7ceffeef3ffa2320081268","max_balance_held":2921.710257156997,"pnl_usd_realised":350119.9797159946,"roi_percent_total":0.0105756026688948,"netflow_amount_usd":-350119.979715994,"pnl_usd_unrealised":0,"max_balance_held_usd":9622824.220444418,"roi_percent_realised":0.0105756026688948,"trader_address_label":"\"flomp\" on OpenSea [0xee2826]","roi_percent_unrealised":null,"still_holding_balance_ratio":0},{"price_usd":3293.558694559951,"nof_trades":3298,"holding_usd":118.07737023766995,"pnl_usd_total":221361.53654342573,"holding_amount":0.035850999234566895,"netflow_amount":-701.4994548565761,"trader_address":"0x4c405bc9dc26435a48fe6a637b6b08ebe78b9da5","max_balance_held":1509.390957972879,"pnl_usd_realised":221364.42114445375,"roi_percent_total":0.0024554171650870674,"netflow_amount_usd":-2610538.468202066,"pnl_usd_unrealised":-2.8846010280256733,"max_balance_held_usd":4971267.713121749,"roi_percent_realised":0.002455449162059031,"trader_address_label":"​​🤖 DEX/CEX Trading Bot [0x4c405b]","roi_percent_unrealised":-0.023847172775397184,"still_holding_balance_ratio":0.000023751963694492377},{"price_usd":3293.558694559951,"nof_trades":2,"holding_usd":0,"pnl_usd_total":218772.85308499908,"holding_amount":0,"netflow_amount":-74.62016154288389,"trader_address":"0x8af74a92ec9c6b870b75ce89ef771ac71e1ae8c6","max_balance_held":74.62016154288389,"pnl_usd_realised":218772.85308499908,"roi_percent_total":10.870615940312529,"netflow_amount_usd":-238898.01014014837,"pnl_usd_unrealised":0,"max_balance_held_usd":245765.88183903333,"roi_percent_realised":10.870615940312529,"trader_address_label":"High Balance [0x8af74a]","roi_percent_unrealised":null,"still_holding_balance_ratio":0},{"price_usd":3293.558694559951,"nof_trades":18,"holding_usd":143709.23868000167,"pnl_usd_total":187828.28687362737,"holding_amount":43.63342269180435,"netflow_amount":-594.2051884879806,"trader_address":"0x924cafec4f967be5df085ad94d8d50574f9a2bb0","max_balance_held":1848.8849015086473,"pnl_usd_realised":186916.1205488611,"roi_percent_total":0.02721987703023339,"netflow_amount_usd":-2187088.1114165355,"pnl_usd_unrealised":912.1663247662534,"max_balance_held_usd":6089410.942604424,"roi_percent_realised":0.02708768684948621,"trader_address_label":"​​Yield Farmer [0x924caf]","roi_percent_unrealised":0.006387850322988854,"still_holding_balance_ratio":0.023599858842592355},{"price_usd":3293.558694559951,"nof_trades":99,"holding_usd":805653.5447961702,"pnl_usd_total":146442.07176317085,"holding_amount":244.61490427569646,"netflow_amount":244.61490427569646,"trader_address":"0x460c501889128d3e0fbc205834fab4a271494886","max_balance_held":256.77421008508105,"pnl_usd_realised":168586.58853568105,"roi_percent_total":0.011246954307162722,"netflow_amount_usd":659211.473033,"pnl_usd_unrealised":-22144.51677251019,"max_balance_held_usd":845700.9321644822,"roi_percent_realised":0.012947683921923999,"trader_address_label":"High Balance [0x460c50]","roi_percent_unrealised":-0.026751109721791625,"still_holding_balance_ratio":0.9526459226362505},{"price_usd":3293.558694559951,"nof_trades":3,"holding_usd":0,"pnl_usd_total":161875.2513061102,"holding_amount":0,"netflow_amount":-201.76129963848737,"trader_address":"0xd4f9c391c8559f02f007bd1a7b520847bc743514","max_balance_held":201.76129963848737,"pnl_usd_realised":161875.2513061102,"roi_percent_total":0.28321106408005664,"netflow_amount_usd":-733446.322626799,"pnl_usd_unrealised":0,"max_balance_held_usd":664512.6826500556,"roi_percent_realised":0.28321106408005664,"trader_address_label":"[0xd4f9c3]","roi_percent_unrealised":null,"still_holding_balance_ratio":0},{"price_usd":3293.558694559951,"nof_trades":14,"holding_usd":0,"pnl_usd_total":133021.52225289302,"holding_amount":0,"netflow_amount":-664.2975261703224,"trader_address":"0x2e15d7aa0650de1009710fdd45c3468d75ae1392","max_balance_held":1270.5506281773407,"pnl_usd_realised":133021.52225289302,"roi_percent_total":0.009193455368919757,"netflow_amount_usd":-2422066.6444593086,"pnl_usd_unrealised":0,"max_balance_held_usd":4184633.0683120885,"roi_percent_realised":0.009193455368919757,"trader_address_label":"Former Smart Trader [0x2e15d7]","roi_percent_unrealised":null,"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"},"chain":"ethereum","pagination":{"page":1,"per_page":10},"token_address":"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"},"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_PYwdeGEtiVcHWu9afayn2","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_y8iN2hxZDDCVllPdAWt2A","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 the Token God Mode (TGM) profit-and-loss leaderboard, ranking wallets by trading performance for a given token.","exampleAgentPrompt":"Pull up the Nansen Token God Mode PnL leaderboard for BONK so I can see which wallets have made the most profit trading it.","exampleUseCases":null,"resultDescription":"Returns a ranked list of wallet addresses sorted by profit-and-loss performance for a specified token, including metrics such as realized PnL, unrealized PnL, and trade volume — sourced from Nansen's Token God Mode analytics layer.","failureModes":["Invalid or unrecognized token address returns an error or empty result","Token not indexed in TGM returns no leaderboard data","Malformed POST body causes 400 bad request","Insufficient payment or missing x402 payment header causes 402 payment required","Rate limiting may return 429 if called too frequently","Network timeout if Nansen backend is slow to respond"],"whenToPreferThis":"Use this endpoint when you need to identify the top-performing wallets by PnL for a specific token using Nansen's on-chain smart money data. It is the right choice when the goal is to rank traders by profitability rather than just monitor flows or positions. Prefer this over general transaction lookup endpoints when the specific need is leaderboard-style PnL ranking for a token.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-13T12:55:12.851Z","isFirstParty":false}