{"uid":"cap_FvvJciogmfRlZE0HfwPwW","slug":"nansen-pnl-leaderboard-ccf8cde4","name":"Nansen PnL Leaderboard","description":"Rank traders by their profit/loss performance for a specific token. 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 token.\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/pnl-leaderboard?utm_source=zero.xyz","method":"POST","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","arc","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic","sui"],"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":"TGMPnlLeaderboardSortOrder","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 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 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":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_KhjDsfkHn4JpEGPR-cwaA","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 token on a given chain and date range, including ROI percentages and trading patterns.","exampleAgentPrompt":"Show me the top traders ranked by PnL for the token at 0x28c6c06298d514db089934071355e5743bf21d60 on Ethereum between January 1 2025 and January 31 2025, including both realized and unrealized profits.","exampleUseCases":[{"title":"Identify smart money positions in new tokens","prompt":"Find the most profitable wallets trading this new Solana token over the last 30 days. I want to see which smart money addresses have the biggest unrealized gains so I can understand what the smart investors are holding."},{"title":"Compare trader performance across DeFi protocols","prompt":"Show me the top 20 traders by total PnL for USDC on both Ethereum and Arbitrum this month. I'm trying to see if the same profitable wallets are active across different chains or if different traders dominate each ecosystem."},{"title":"Track realized vs unrealized profits by trader","prompt":"Pull the leaderboard of traders for this base layer token on Base chain for the last quarter. Break down which traders have locked in the most realized profits versus which ones are sitting on the biggest unrealized gains right now."}],"resultDescription":"A paginated list of traders ranked by their profit/loss for the specified token, each entry including realized PnL (USD), unrealized PnL (USD), total PnL (USD), ROI percentage, number of trades, current holding amount and USD value, netflow, max balance held, token price at the end date, and optional entity labels (e.g. smart money, exchange).","failureModes":["Invalid or unsupported chain returns validation error","Token address not found or no trading activity for the given date range returns empty data array","Malformed date range (e.g. 'from' after 'to') returns 400 error","Missing required fields (chain, token_address, date) returns 422 unprocessable entity","Exceeding filter bounds or invalid numeric range returns 400 error","Rate limit or payment failure returns 402 or 429 error"],"whenToPreferThis":"Use this endpoint when you need to identify and rank individual traders by their profitability (realized + unrealized PnL) for a specific token on a supported chain. It is ideal for smart money analysis, token holder performance benchmarking, and identifying top-performing wallets. Prefer this over general token holder or trade history endpoints when the goal is comparative PnL ranking and ROI analysis across traders.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-09T18:49:27.634Z","isFirstParty":false,"canonicalSlug":"nansen-pnl-leaderboard-ccf8cde4"}