---
title: "Open Positions"
method: GET
path: "/gateway/v1/hyperliquid/positions"
tags: ["Hyperliquid"]
---

# Open Positions

`GET /gateway/v1/hyperliquid/positions`

Returns a wallet's open perpetual positions with its cross-margin summary and derived risk (leverage, unrealized PnL, ROE, liquidation price, margin ratio, distance-to-liquidation).

`liquidation_price` (and `distance_to_liquidation`) can be null even on a leveraged position — Hyperliquid returns none for cross positions whose spot collateral backstops them; in that case use the account-level `margin_ratio` (the account liquidates as it approaches 1.0) for proximity. `account_value` here is perp clearinghouse equity, not total portfolio (see `/hyperliquid/account`). Positions are sorted by position value (largest first). `dex` scopes to a builder market; omit (or `main_dex`) for the native market.

## Query parameters

- `address` string, required — Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported.
- `dex` 'main_dex' | 'xyz' | 'flx' | 'vntl' | 'hyna' | 'km' | 'abcd' | 'cash' | 'para' | 'mkts' — Market scope: omit (or main_dex) for the native market, or a builder market — one of: xyz, flx, vntl, hyna, km, abcd, cash, para, mkts.

## Response `200`

OK

- DataObjectResponseHyperliquidPositions
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `data` HyperliquidPositions, required
    - `account_value` number, double, required — Perp clearinghouse equity, USD (cross-margin summary). NOT total portfolio — for total equity incl. spot/vault/staking use /hyperliquid/account (total_value_usd).
    - `address` string, required — Wallet address
    - `cross_maintenance_margin_used` number, double, required — Maintenance margin, USD
    - `margin_ratio` number, double, required — Maintenance margin / account equity (0-1); the account is liquidated as this approaches 1.0. Use it as the account-level liquidation-proximity signal when a position's liquidation_price is null.
    - `positions` HyperliquidPosition[], nullable, required — Open positions, sorted by position value (largest first)
      - `cum_funding` HyperliquidCumFunding, required
        - `all_time` number, double, required — Funding since the account opened, USD
        - `since_change` number, double, required — Funding since this position last changed, USD
        - `since_open` number, double, required — Funding since this position was opened, USD
      - `distance_to_liquidation` number, double — Fraction the mark must move to reach the liquidation price (e.g. 0.05 = 5%), always positive — a RELATIVE fraction, not an absolute price/USD distance. Omitted when there is no liquidation price.
      - `entry_price` number, double, required — Average entry price, USD
      - `leverage_type` string, required — cross or isolated
      - `leverage_value` integer, required — Leverage used
      - `liquidation_price` number, double — Liquidation price, USD. Omitted when Hyperliquid returns none upstream — common for cross positions whose spot collateral backstops them; fall back to the account-level margin_ratio for proximity.
      - `margin_used` number, double, required — Margin on this position, USD
      - `mark_price` number, double, required — Current mark price, USD (= position_value / |size|)
      - `max_leverage` integer, required — Max allowed leverage for this market
      - `position_value` number, double, required — Current value, USD
      - `return_on_equity` number, double, required — Return on equity (0.45 = 45%)
      - `side` string, required — long or short
      - `size` number, double, required — Position size; positive = long, negative = short
      - `symbol` string, required — Market id (BTC, kPEPE, xyz:GOLD)
      - `unrealized_pnl` number, double, required — Unrealized profit/loss, USD
    - `timestamp` integer, required — When this was captured (Unix seconds)
    - `total_margin_used` number, double, required — Margin currently in use, USD
    - `total_notional_pos` number, double, required — Total size of all positions, USD
    - `total_raw_usd` number, double, required — Raw USD balance
    - `withdrawable` number, double, required — Available to withdraw, USD
  - `meta` ObjectResponseMeta, required
    - `cached` boolean, required — Whether this response was served from cache
    - `credits_used` integer, required — Credits deducted for this request
    - `empty_reason` string — Hint explaining why the data array is empty, when applicable

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) · [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/asksurf/asksurf-public-rest-api/revisions/4153a9cb5145/schema)