{"uid":"cap_ze-c0m9g0tutGYWemBHJk","slug":"api-nansen-ai-01e8659c","name":"Nansen Perpetual Positions Data","description":"Get Perpetual Positions Data","url":"https://api.nansen.ai/api/v1/profiler/perp-positions","method":"GET","headers":{},"bodySchema":{"type":"object","title":"PerpPositionsRequest","required":["address"],"properties":{"address":{"type":"string","title":"Address","examples":["0xa312114b5795dff9b8db50474dd57701aa78ad1e"],"maxLength":42,"minLength":42,"description":"User's Hyperliquid address in 42-character hexadecimal format"},"filters":{"anyOf":[{"type":"object","title":"PerpPositionsFilters","properties":{"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","examples":["BTC","ETH","SOL"],"description":"Filter by token symbol"},"position_type":{"anyOf":[{"type":"string"}],"title":"Position Type","examples":["oneWay"],"description":"Filter by position type"},"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":1000},{"max":100000},{"max":100000,"min":1000}],"description":"Filter by position value in USD"},"unrealized_pnl_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},{"max":0},{"max":1000,"min":-1000}],"description":"Filter by unrealized PnL in USD"}},"description":"Filters for perp positions endpoint.","additionalProperties":false}],"examples":[{"position_value_usd":{"min":1000},"unrealized_pnl_usd":{"max":0}}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"SortOrder[PerpPositionsSortField]","required":["field","direction"],"properties":{"field":{"enum":["leverage_value","position_value_usd","entry_price_usd","liquidation_price_usd","unrealized_pnl_usd","size","token_symbol","position_type"],"type":"string","title":"PerpPositionsSortField","description":"Enum for perp positions sort fields."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Order By","examples":[[{"field":"position_value_usd","direction":"DESC"}]],"description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"position_value_usd\", \"direction\": \"DESC\"}] - Sort by position value descending\n- [{\"field\": \"unrealized_pnl_usd\", \"direction\": \"ASC\"}] - Sort by unrealized PnL ascending\n\nIf not provided, positions are sorted by position value descending."}},"description":"Request model for Perp Positions endpoint.","additionalProperties":false},"responseSchema":{"type":"object","title":"PerpPositionsResponse","required":["data"],"properties":{"data":{"type":"object","title":"PerpPositionsData","properties":{"time":{"anyOf":[{"type":"integer"}],"title":"Time","examples":[1761283435707],"description":"Timestamp"},"withdrawable":{"anyOf":[{"type":"string"}],"title":"Withdrawable","examples":["2933647.2403759998"],"description":"Withdrawable USD"},"assetPositions":{"anyOf":[{"type":"array","items":{"type":"object","title":"AssetPosition","properties":{"position":{"anyOf":[{"$ref":"#/components/schemas/Position"}],"description":"Position data"},"position_type":{"anyOf":[{"type":"string"}],"title":"Position Type","examples":["oneWay"],"description":"Position type"}},"description":"Asset position wrapper.","additionalProperties":false}}],"title":"Assetpositions","description":"List of asset positions"},"crossMaintenanceMarginUsed":{"anyOf":[{"type":"string"}],"title":"Crossmaintenancemarginused","examples":["722948.2832910001"],"description":"Cross maintenance margin used USD"},"margin_summary_total_raw_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Total Raw Usd","examples":["13987445.0243870001"],"description":"Margin summary total raw USD"},"margin_summary_account_value_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Account Value Usd","examples":["4643143.4382309997"],"description":"Margin summary account value USD"},"cross_margin_summary_total_raw_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Total Raw Usd","examples":["13987445.0243870001"],"description":"Cross margin summary total raw USD"},"margin_summary_total_margin_used_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Total Margin Used Usd","examples":["1456365.231985"],"description":"Margin summary total margin used USD"},"cross_margin_summary_account_value_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Account Value Usd","examples":["4643143.4382309997"],"description":"Cross margin summary account value USD"},"cross_margin_summary_total_margin_used_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Total Margin Used Usd","examples":["1456365.231985"],"description":"Cross margin summary total margin used USD"},"margin_summary_total_net_liquidation_position_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Total Net Liquidation Position Usd","examples":["13339928.690684"],"description":"Margin summary total net liquidation position USD"},"cross_margin_summary_total_net_liquidation_position_on_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Total Net Liquidation Position On Usd","examples":["13339928.690684"],"description":"Cross margin summary total net liquidation position on USD"}},"description":"Data model for Hyperliquid clearinghouse state response.","additionalProperties":false}},"description":"Response model for perp positions endpoint.","additionalProperties":false},"example":{"request":{"input":{"body":{"address":"0x1234567890123456789012345678901234567890"},"type":"http","method":"POST","bodyType":"json"}},"response":{"data":{"timestamp":1780528957593,"asset_positions":[],"withdrawable_usd":"0.0","margin_summary_total_raw_usd":"0.0","margin_summary_account_value_usd":"0.0","cross_maintenance_margin_used_usd":"0.0","cross_margin_summary_total_raw_usd":"0.0","margin_summary_total_margin_used_usd":"0.0","cross_margin_summary_account_value_usd":"0.0","cross_margin_summary_total_margin_used_usd":"0.0","margin_summary_total_net_liquidation_position_usd":"0.0","cross_margin_summary_total_net_liquidation_position_on_usd":"0.0"}}},"exampleRequest":{"address":"0x1234567890123456789012345678901234567890"},"tags":["x402"],"displayCostAmount":"0.01","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.01/call","primary":{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"},{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_3UYTNoEEM4rYGXSdMP8O0","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_gSeinM_Td3dBKKdgLAxos","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Retrieves perpetual contract position data for a specified token or address via Nansen's on-chain analytics platform","exampleAgentPrompt":"Can you pull up the current perpetual positions for wallet 0xAbC123... on Nansen — I want to see what perp contracts they're holding, including size, side, and entry price?","exampleUseCases":[{"title":"Monitor smart money perp exposure","prompt":"Can you check what perpetual futures positions the wallet 0xDeFi456... is holding right now? I want to know their leverage levels, whether they're long or short, and how their unrealized PnL is looking across all open contracts."},{"title":"Check liquidation risk for trader","prompt":"I need to look up the perp positions for address 0xTrader789... on Hyperliquid — specifically the liquidation prices and margin levels so I can assess how close they are to getting liquidated on any of their positions."},{"title":"Track large ETH perp positions","prompt":"Can you pull the open perpetual contract positions for 0xWhale321... and show me their total exposure to ETH perps? I want to see the position size, entry price, and current mark price to understand how big their bet is."}],"resultDescription":"Returns a list of open perpetual contract positions associated with the queried address or token, including details such as position size, direction (long/short), entry price, leverage, and unrealized PnL as tracked by Nansen's on-chain data.","failureModes":["Invalid or unsupported wallet/token address returns 400 or empty result","Address with no perpetual positions returns empty array","Rate limiting or authentication failure returns 401/429","Network or provider outage returns 500","Unsupported chain or protocol returns no data"],"whenToPreferThis":"Use this endpoint when you need structured on-chain perpetual futures position data enriched with Nansen's wallet labels and smart money tagging. Prefer this over raw blockchain queries when you want aggregated, labeled position data rather than raw transaction logs, especially for Hyperliquid perp activity.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-13T12:44:36.029Z","isFirstParty":false}