{"uid":"cap_YiLK3pV8Rpmmq7rH9rdWc","slug":"nansen-perp-positions-63b14962","name":"Nansen Perp Positions","description":"Retrieve current perpetual positions for a specific token on Hyperliquid. Shows active positions with detailed metrics including entry price, mark price, leverage, PnL, and liquidation price.\n\n**Key Features:**\n- Hyperliquid perpetual contracts only (no chain field needed)\n- Real-time position tracking with live PnL calculations\n- Leverage and margin information\n- Smart money filtering capabilities\n- Support for both Long and Short positions\n\n**What it helps to answer:**\n\n1. **What are the current perp positions for a specific token?**\n2. **Which addresses have the largest positions by value?**\n3. **What are the unrealized gains/losses on current positions?**\n4. **What leverage levels are traders using?**\n5. **Which smart money wallets are holding positions?**","url":"https://api.nansen.ai/api/v1/tgm/perp-positions?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"TGMPerpPositionsRequest","required":["token_symbol"],"properties":{"filters":{"anyOf":[{"type":"object","title":"TGMPerpPositionsFilters","properties":{"side":{"anyOf":[{"enum":["Long","Short"],"type":"string","title":"PositionSide","description":"Shared enum for position side direction."},{"type":"array","items":{"enum":["Long","Short"],"type":"string","title":"PositionSide","description":"Shared enum for position side direction."}},{"type":"null"}],"title":"Side","examples":["Long",["Short","Long"]],"description":"Position side filter (Long or Short)"},"address":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"Trader address filter"},"upnl_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":-1000}],"description":"Unrealized PnL range filter in USD"},"entry_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":[{"max":60000,"min":50000}],"description":"Entry price range filter"},"funding_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":-1000}],"description":"Funding range filter in USD"},"address_label":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Address Label","examples":["Smart Money","%Fund%"],"description":"Trader label filter"},"position_size":{"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":1.5}],"description":"Position size range filter (token amount)"},"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":10000}],"description":"Position value range filter in USD"},"exclude_smart_money_labels":{"anyOf":[{"type":"array","items":{"enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"type":"string","title":"LabelType","description":"Filter by entity label type."}}],"title":"Exclude Smart Money Labels","examples":[["Smart HL Perps Trader"],["Fund"]],"description":"Exclude smart money labels for traders"},"include_smart_money_labels":{"anyOf":[{"type":"array","items":{"enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"type":"string","title":"LabelType","description":"Filter by entity label type."}}],"title":"Include Smart Money Labels","examples":[["Smart HL Perps Trader"],["Fund"]],"description":"Include smart money labels for traders"}},"description":"Filters for TGM perp positions endpoint.\n\nThese filters control which perp positions are included in the analysis.","additionalProperties":false}],"examples":[{"side":["Long"],"upnl_usd":{"min":0},"position_value_usd":{"min":10000},"include_smart_money_labels":["Smart HL Perps Trader","Fund"]}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"TGMPerpPositionsSortOrder","required":["field","direction"],"properties":{"field":{"enum":["address","address_label","side","position_value_usd","position_size","size_base","leverage","entry_price","mark_price","liquidation_price","funding_usd","upnl_usd"],"type":"string","title":"TGMPerpPositionsSortField","description":"Enum for sortable fields in TGM perp positions."},"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.\n\nExamples:\n- [{\"field\": \"position_value_usd\", \"direction\": \"DESC\"}] - Sort by position value USD descending\n- [{\"field\": \"upnl_usd\", \"direction\": \"ASC\"}] - Sort by unrealized PnL ascending\n- [{\"field\": \"leverage\", \"direction\": \"DESC\"}] - Sort by leverage descending\n- [{\"field\": \"size_base\", \"direction\": \"DESC\"}] - Sort by absolute position size descending, longs and shorts together\n\n`position_size` is signed (a short is negative), so a sort on it ranks every long above every short. `size_base` sorts both sides by the size of the position."},"label_type":{"enum":["smart_money","all_traders","whale","public_figure"],"type":"string","title":"TGMPerpPositionsLabel","description":"TGM perp positions label types."},"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":"Token symbol"}},"description":"Request model for TGM perp positions endpoint.\n\nThis endpoint provides perp positions data for a specific token.","additionalProperties":false},"responseSchema":{"type":"object","title":"TGMPerpPositionsResponse","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","title":"TGMPerpPosition","required":["leverage"],"properties":{"side":{"anyOf":[{"enum":["Long","Short"],"type":"string","title":"PositionSide","description":"Shared enum for position side direction."}],"examples":["Long"],"description":"Position direction (Long/Short)"},"address":{"anyOf":[{"type":"string"}],"title":"Address","examples":["0x1234567890123456789012345678901234567890"],"description":"The wallet address of the trader."},"leverage":{"type":"string","title":"Leverage","examples":["5X"],"description":"The leverage applied to the position."},"upnl_usd":{"anyOf":[{"type":"number"}],"title":"Upnl Usd","examples":[500],"description":"Unrealized profit/loss including funding."},"mark_price":{"anyOf":[{"type":"number"}],"title":"Mark Price","examples":[50500],"description":"The current mark price of the asset."},"entry_price":{"anyOf":[{"type":"number"}],"title":"Entry Price","examples":[50000],"description":"Average price where the position was opened."},"funding_usd":{"anyOf":[{"type":"number"}],"title":"Funding Usd","examples":[10.5],"description":"Net funding paid (-) or received (+) since entry."},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","examples":["Smart Money"],"description":"Wallet or labeled entity holding the position."},"leverage_type":{"anyOf":[{"type":"string"}],"title":"Leverage Type","examples":["cross"],"description":"The type of leverage used, e.g., cross or isolated."},"position_size":{"anyOf":[{"type":"number"}],"title":"Position Size","examples":[1.5],"description":"The position size (token amount)."},"liquidation_price":{"anyOf":[{"type":"number"}],"title":"Liquidation Price","examples":[45000],"description":"The price at which the position would be liquidated."},"position_value_usd":{"anyOf":[{"type":"number"}],"title":"Position Value Usd","examples":[50000],"description":"USD notional size of the position."}},"description":"Individual TGM perp position record.\n\nRepresents a single perp position."},"title":"Data","description":"List of TGM perp position 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 positions endpoint.\n\nContains a list of perp position 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_zb8nhYEoX0DL0T07e2et8","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":"Retrieve current perpetual futures positions for a specific token on Hyperliquid, with entry/mark/liquidation prices, leverage, and unrealized PnL.","exampleAgentPrompt":"Pull up all current perp positions for BTC on Hyperliquid — I want to see the long positions held by smart money wallets, sorted by largest position value, including their entry price, leverage, liquidation price, and unrealized PnL.","exampleUseCases":null,"resultDescription":"A paginated list of active perpetual positions for the queried token, each record containing the trader's wallet address, address label (e.g. 'Smart Money'), position side (Long/Short), leverage and leverage type (cross/isolated), entry price, current mark price, liquidation price, position size in tokens, position value in USD, unrealized PnL in USD, and cumulative funding PnL.","failureModes":["Missing required token_symbol returns 422 validation error","Invalid address format in filter returns 400 bad request","Token not traded on Hyperliquid returns empty data array","Unsupported side enum value returns validation error","Pagination parameters out of range return empty results or error","Rate limiting or quota exceeded returns 429 or payment error"],"whenToPreferThis":"Use this endpoint when you need real-time snapshots of who holds open perpetual positions for a specific token on Hyperliquid, especially when you want smart money labels, leverage details, and liquidation prices in a single response. Prefer this over general trade history endpoints when the focus is on current open positions rather than historical trades.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-10T18:42:41.601Z","isFirstParty":false,"canonicalSlug":"nansen-perp-positions-c496f569"}