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

addressstringrequired

Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported.

dexenum<string>

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.

Available options:main_dexxyzflxvntlhynakmabcdcashparamkts

Open Positions

const options = {method: 'GET'};

fetch('https://api.asksurf.ai/gateway/v1/hyperliquid/positions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/DataObjectResponseHyperliquidPositions.json",
  "data": {
    "account_value": 123,
    "address": "<string>",
    "cross_maintenance_margin_used": 123,
    "margin_ratio": 123,
    "positions": [
      {
        "cum_funding": {
          "all_time": 123,
          "since_change": 123,
          "since_open": 123
        },
        "distance_to_liquidation": 123,
        "entry_price": 123,
        "leverage_type": "<string>",
        "leverage_value": 123,
        "liquidation_price": 123,
        "margin_used": 123,
        "mark_price": 123,
        "max_leverage": 123,
        "position_value": 123,
        "return_on_equity": 123,
        "side": "<string>",
        "size": 123,
        "symbol": "<string>",
        "unrealized_pnl": 123
      }
    ],
    "timestamp": 123,
    "total_margin_used": 123,
    "total_notional_pos": 123,
    "total_raw_usd": 123,
    "withdrawable": 123
  },
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>"
  }
}