---
title: "Get Perpetual Positions Data"
method: POST
path: "/api/v1/profiler/perp-positions"
tags: ["Profiler"]
---

# Get Perpetual Positions Data

`POST /api/v1/profiler/perp-positions`

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?**

## Request body

- PerpPositionsRequest — Request model for Perp Positions endpoint.
  - `address` string, required — User's Hyperliquid address in 42-character hexadecimal format
  - `filters` PerpPositionsFilters — Filters for perp positions endpoint.
    - `token_symbol` string — Filter by token symbol
    - `position_value_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `position_type` string — Filter by position type
    - `unrealized_pnl_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
  - `order_by` SortOrderPerpPositionsSortField[] — Custom sort order to override the endpoint's default ordering. Examples: - [{"field": "position_value_usd", "direction": "DESC"}] - Sort by position value descending - [{"field": "unrealized_pnl_usd", "direction": "ASC"}] - Sort by unrealized PnL ascending If not provided, positions are sorted by position value descending.
    - `field` 'leverage_value' | 'position_value_usd' | 'entry_price_usd' | 'liquidation_price_usd' | 'unrealized_pnl_usd' | 'size' | 'token_symbol' | 'position_type', required — Enum for perp positions sort fields.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

Perpetual positions data for the user

- PerpPositionsResponse — Response model for perp positions endpoint.
  - `data` PerpPositionsData, required — Data model for Hyperliquid clearinghouse state response.
    - `assetPositions` AssetPosition[] — List of asset positions
      - `position` Position — Individual perpetual position.
        - `token_symbol` string — Asset symbol (e.g., BTC, ETH)
        - `size` string — Size
        - `position_value_usd` string — Position value USD
        - `entry_price_usd` string — Entry price USD
        - `liquidation_price_usd` string — Liquidation price USD
        - `leverage_value` integer — Leverage value
        - `leverage_type` string — Leverage type: 'cross' or 'isolated'
        - `leverage_raw_usd` string — Raw USD leverage
        - `margin_used_usd` string — Margin used USD
        - `max_leverage_value` integer — Maximum allowed leverage value
        - `return_on_equity` string — Return on equity
        - `unrealized_pnl_usd` string — Unrealized PnL USD
        - `cumulative_funding_all_time_usd` string — Cumulative funding all time USD
        - `cumulative_funding_since_change_usd` string — Cumulative funding since change USD
        - `cumulative_funding_since_open_usd` string — Cumulative funding since open USD
      - `position_type` string — Position type
    - `crossMaintenanceMarginUsed` string — Cross maintenance margin used USD
    - `cross_margin_summary_account_value_usd` string — Cross margin summary account value USD
    - `cross_margin_summary_total_margin_used_usd` string — Cross margin summary total margin used USD
    - `cross_margin_summary_total_net_liquidation_position_on_usd` string — Cross margin summary total net liquidation position on USD
    - `cross_margin_summary_total_raw_usd` string — Cross margin summary total raw USD
    - `margin_summary_account_value_usd` string — Margin summary account value USD
    - `margin_summary_total_margin_used_usd` string — Margin summary total margin used USD
    - `margin_summary_total_net_liquidation_position_usd` string — Margin summary total net liquidation position USD
    - `margin_summary_total_raw_usd` string — Margin summary total raw USD
    - `time` integer — Timestamp
    - `withdrawable` string — Withdrawable USD

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)