{"uid":"cap_Lndh6nM3AtrG7_ogsSD4V","slug":"nansen-historical-pnl-leaderboard-bce2e827","name":"Nansen Historical PnL Leaderboard","description":"Get historical \"Token God Mode\" (TGM) PnL leaderboard (Beta)","url":"https://api.nansen.ai/api/v1beta1/tgm/historical-pnl-leaderboard","method":"GET","headers":{},"bodySchema":{"type":"object","title":"TGMHistoricalPnlLeaderboardRequest","required":["chain","token_address","date_range"],"properties":{"chain":{"enum":["arbitrum","avalanche","base","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","ronin","scroll","sei","solana","sonic","starknet","sui","ton","tron"],"type":"string","title":"TGMChain","description":"Chains supported in TGM (Token God Mode) endpoints."},"filters":{"anyOf":[{"type":"object","title":"TGMHistoricalPnlLeaderboardFilters","properties":{"nof_buys":{"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":1}],"description":"Number of buy trades range filter"},"sold_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":[{"max":1000000,"min":1000}],"description":"Total sold volume range filter in USD"},"nof_sells":{"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":1}],"description":"Number of sell trades range filter"},"bought_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":[{"max":1000000,"min":1000}],"description":"Total bought volume range filter in USD"},"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":1000,"min":1}],"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":[{"max":1000000,"min":100}],"description":"Holding value range filter in USD"},"sold_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":[{"max":1000000,"min":100}],"description":"Total sold token amount range filter"},"bought_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":[{"max":1000000,"min":100}],"description":"Total bought token amount range filter"},"pnl_usd_total":{"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":100000,"min":-1000}],"description":"Total PnL range filter in USD"},"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":[{"max":1000000,"min":100}],"description":"Current token holding amount range filter"},"trader_address":{"anyOf":[{"type":"array","items":{"type":"string"}}],"title":"Trader Address","examples":[["0x28c6c06298d514db089934071355e5743bf21d60"]],"description":"Filter to specific trader addresses (empty = all traders)"},"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":[{"max":1000000,"min":100}],"description":"Peak token balance ever 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":[{"max":100000,"min":-1000}],"description":"Realised PnL range filter in USD"},"roi_percent_total":{"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":500,"min":-50}],"description":"Total ROI percentage range filter"},"netflow_amount_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":[{"max":10000,"min":-10000}],"description":"Netflow 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":[{"max":100000,"min":-1000}],"description":"Unrealised 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":[{"max":1000000,"min":1000}],"description":"Peak token balance in USD ever held range filter"},"roi_percent_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":[{"max":500,"min":-50}],"description":"Realised ROI percentage range filter"},"roi_percent_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":[{"max":500,"min":-50}],"description":"Unrealised ROI percentage range 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":"Ratio of current holdings to max balance held"}},"description":"Filters for the historical PnL leaderboard endpoint.","additionalProperties":false}],"description":"Optional filters applied server-side"},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"SortOrder[TGMHistoricalPnlLeaderboardSortField]","required":["field","direction"],"properties":{"field":{"enum":["pnl_usd_total","roi_percent_total","pnl_usd_realised","roi_percent_realised","pnl_usd_unrealised","roi_percent_unrealised","holding_usd","holding_amount","nof_trades","still_holding_balance_ratio","netflow_amount_usd","max_balance_held","max_balance_held_usd","nof_buys","nof_sells","bought_amount","sold_amount","bought_usd","sold_usd"],"type":"string","title":"TGMHistoricalPnlLeaderboardSortField","description":"Sortable fields for the historical PnL leaderboard endpoint.\n\nValues match the view's order_by parameter exactly."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Order By","description":"Sort order. Defaults to pnl_usd_total DESC. Only the first element is used."},"date_range":{"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."},"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 contract address"},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","default":true,"examples":[true],"description":"When True, exclude blacklisted addresses from the results. Defaults to True."}},"description":"Request model for the historical PnL leaderboard endpoint.\n\nReturns per-trader PnL statistics for a token over a date range with\ntemporally-correct labels resolved at date_to. Uses label history tables\nto avoid forward-looking bias.\n\nSupports page-based pagination via per_page and page.","additionalProperties":false},"responseSchema":{"type":"object","title":"TGMHistoricalPnlLeaderboardResponse","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 historical 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 the historical PnL leaderboard endpoint."},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.25","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.25/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.25","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.25","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_shSiySfBal-zKeCrYEPVq","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.25","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns per-trader profit/loss statistics for a specific token over a historical date range, with labels resolved at the end date to avoid forward-looking bias.","exampleAgentPrompt":"Show me the top 25 traders by total PnL for the USDC token at address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Ethereum from January 1 2024 to March 31 2024, filtering for traders with at least 5 buys.","exampleUseCases":[{"title":"Q1 PEPE top trader rankings","prompt":"Who were the most profitable wallets trading PEPE on Ethereum during Q1 2024? Show me the top 20 traders ranked by total PnL, and filter out anyone with fewer than 3 buys so we're only looking at active participants."},{"title":"Historical smart money analysis","prompt":"I want to do a historical smart money deep dive on the ARB token at 0x912CE59144191C1204E64559FE8253a0e49E6548 on Arbitrum for the full year of 2023. Give me the top 50 traders by realized profit, paginated 25 per page, so I can compare who was consistently extracting value without any forward-looking label bias."},{"title":"Quarterly unrealized PnL snapshot","prompt":"At the end of Q2 2024 — so from April 1 to June 30 — which traders were sitting on the highest unrealized PnL for the SHIB token on Ethereum? I want to see their ROI percentages and max balance held too, filtering for wallets that sold at least some volume so I'm not just looking at bag holders who never interacted."}],"resultDescription":"A paginated list of trader addresses with their PnL metrics (realized, unrealized, total), ROI percentage, number of trades, buy/sell counts, holding amounts and USD values, netflow, and max balance held — all computed with labels resolved at the specified end date. Also includes pagination metadata (total records, current page, per-page count).","failureModes":["Invalid or unsupported chain name returns 422 validation error","Token address not found or not tracked returns empty data array","Date range with date_from after date_to returns validation error","Unsupported chain for historical data returns error or empty result","Invalid filter values (e.g. min > max) return 422 validation error","Missing required fields (chain, token_address, date_range) return 422","Exceeding API rate limits or invalid API key returns 401/429","Page number beyond available results returns empty data with valid pagination metadata"],"whenToPreferThis":"Use this endpoint when you need historical PnL rankings for a token over a specific past date range and require temporally-correct labels (no forward-looking bias). Prefer this over /tgm/pnl-leaderboard when you need date-bounded analysis, explicit pagination, or server-side filtering before pagination. Choose this for backtesting trader performance, historical smart money analysis, or quarterly reporting.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T12:43:38.050Z","isFirstParty":false}