# Nansen Perp Positions > Nansen Perp Positions is a paid API for AI agents from Nansen at api.nansen.ai, paid per call via MPP, $0.05/call, status unknown (last checked 2026-10-10). Retrieve current perpetual futures positions for a specific token on Hyperliquid, with entry/mark/liquidation prices, leverage, and unrealized PnL. ## Facts - Endpoint: POST https://api.nansen.ai/api/v1/tgm/perp-positions?utm_source=zero.xyz - Price: $0.05/call - Payment: MPP - Status: unknown - Last checked: 2026-10-10 - Activations on Zero: 0 - Provider: Nansen - Docs: https://docs.nansen.ai - Website: https://nansen.ai - Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data - Canonical page: https://www.zero.xyz/c/nansen-perp-positions-63b14962 - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_YiLK3pV8Rpmmq7rH9rdWc Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently. ## How to call it through Zero Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`): ```sh zero fetch --capability nansen-perp-positions-63b14962 -d '' ``` Example prompt: 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. ## When to prefer this 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. ## Known failure modes - 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 ## How this service works 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. **Key Features:** - Hyperliquid perpetual contracts only (no chain field needed) - Real-time position tracking with live PnL calculations - Leverage and margin information - Smart money filtering capabilities - Support for both Long and Short positions **What it helps to answer:** 1. **What are the current perp positions for a specific token?** 2. **Which addresses have the largest positions by value?** 3. **What are the unrealized gains/losses on current positions?** 4. **What leverage levels are traders using?** 5. **Which smart money wallets are holding positions?** ## Output 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. ## Request schema (JSON Schema) ```json { "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 } ], "de … (truncated) ``` ## Response schema (JSON Schema) ```json { "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 is … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-perp-positions-63b14962/health.json - [Zero catalog index](https://www.zero.xyz/llms.txt) - [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)