# 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.01/call, status unknown (last checked 2026-10-10). Retrieves real-time perpetual futures position data for a Hyperliquid wallet address, including PnL, leverage, margin, and liquidation details. ## Facts - Endpoint: POST https://api.nansen.ai/api/v1/profiler/perp-positions?utm_source=zero.xyz - Price: $0.01/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-c496f569 - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_wC2ISaJ52ng0XCGlXEugA 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-c496f569 -d '' ``` Example prompt: 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. ## When to prefer this 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. ## Known failure modes - 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 ## How this service works 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. **What it helps to answer:** 1. **What are the current perpetual positions for a specific user address?** 2. **What is the unrealized PnL and performance of each position?** 3. **What are the leverage levels and margin requirements for each position?** 4. **What are the liquidation prices and risk levels for each position?** ## Output 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. ## Request schema (JSON Schema) ```json { "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", … (truncated) ``` ## Response schema (JSON Schema) ```json { "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" }, "m … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-perp-positions-c496f569/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)