{"uid":"cap_wC2ISaJ52ng0XCGlXEugA","slug":"nansen-perp-positions-c496f569","name":"Nansen Perp Positions","description":"Get perpetual positions data for a user by calling the Hyperliquid API directly. This endpoint provides real-time position information including entry price, mark price, PnL, leverage, and other position details.\n\n**What it helps to answer:**\n\n1. **What are the current perpetual positions for a specific user address?**\n2. **What is the unrealized PnL and performance of each position?**\n3. **What are the leverage levels and margin requirements for each position?**\n4. **What are the liquidation prices and risk levels for each position?**","url":"https://api.nansen.ai/api/v1/profiler/perp-positions?utm_source=zero.xyz","method":"POST","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":"PerpPositionsSortOrder","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":null,"exampleRequest":null,"tags":["blockchain","smart-money","wallet","tokens","defi","analytics","profiler","dex","pnl","onchain","prediction-market","data"],"displayCostAmount":"0.01","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.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"}]},"paymentMethods":[{"uid":"pm_JHYyn-Jgno3RUDIVeVqxr","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","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":"Retrieves real-time perpetual futures position data for a Hyperliquid wallet address, including PnL, leverage, margin, and liquidation details.","exampleAgentPrompt":"Pull up the current perpetual positions on Hyperliquid for wallet 0xa312114b5795dff9b8db50474dd57701aa78ad1e — I want to see the unrealized PnL, leverage, and liquidation prices for each position, and filter to only show positions in BTC or ETH.","exampleUseCases":null,"resultDescription":"Returns a structured object containing all open perpetual positions for the address, including per-position entry price, mark price, unrealized PnL in USD, leverage, liquidation price, position size and value, margin used, position type, plus account-level summaries like total account value, withdrawable balance, and cross maintenance margin used.","failureModes":["Invalid address format (not 42-character hex) returns validation error","Address with no Hyperliquid perp positions returns empty assetPositions array","Hyperliquid API unavailability causes upstream timeout","Filter combination returns no matching positions","Payment of $0.01 USDC not provided results in 402 response"],"whenToPreferThis":"Use this endpoint when you need real-time perpetual futures position data for a specific Hyperliquid wallet address, especially for smart money tracking, risk assessment, or DeFi analytics. Prefer this over generic blockchain explorers when you need structured position-level detail including PnL, leverage, and margin data specifically from Hyperliquid's perp DEX.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-10T18:42:59.070Z","isFirstParty":false,"canonicalSlug":"nansen-perp-positions-c496f569"}