hyperliquid-positions

Hyperliquid positions and margin

Reads here are for everyone (Risk Manager first); the write actions (updateLeverage, updateIsolatedMargin, closes) are Execution Trader only, on a ticket. Order mechanics are in hyperliquid-orders.

Concepts

• Cross margin (default): all cross positions share the account's margin, and unrealised PnL counts as margin; liquidation is account-wide. Isolated margin: the position has its own margin; only that margin is at risk, and you can add to or remove from it (some markets are strictIsolated and refuse removal; HIP-3 markets may be noCross).
• Leverage is set per market and per mode with updateLeverage; it caps position size against margin, it is not "how much you win". Max leverage is per market and tiered by notional (see margin tiers).
• Margin tiers: each perp has a margin table (meta.marginTables, matched to the asset via marginTableId) listing notional thresholds and the max leverage allowed above each. Bigger positions get less leverage.
• Maintenance margin is half of the initial margin at the max leverage of the applicable tier (so between 1.25% for a 40x market and 16.7% for a 3x market); liquidation happens when account (cross) or position (isolated) equity falls below maintenance margin, on mark price. Large positions are liquidated partially first; the cross liquidation price does not depend on your leverage setting.
• Liquidation price is reported by the exchange per position (liquidationPx); use that, do not recompute.
• Funding is exchanged every hour between longs and shorts at the market's funding rate; it changes equity while a position is open.
• Closing is an order in the opposite direction with reduceOnly. Full close at market: reduce-only IOC at a slippage-bounded price for the live position size.

Read positions and margin

ADDR=$HYPERLIQUID_ACCOUNT_ADDRESS
BASE=$([ "$HYPERLIQUID_NETWORK" = mainnet ] && echo https://api.hyperliquid.xyz || echo https://api.hyperliquid-testnet.xyz)
curl -sS -X POST $BASE/info -H 'Content-Type: application/json' -d "{\"type\":\"clearinghouseState\",\"user\":\"$ADDR\"}" | jq '{
  accountValue: .marginSummary.accountValue, totalMarginUsed: .marginSummary.totalMarginUsed,
  withdrawable, crossMaintenanceMarginUsed,
  positions: [.assetPositions[].position | {coin, szi, entryPx, positionValue, unrealizedPnl, liquidationPx, marginUsed,
    leverage: (.leverage.type + " " + (.leverage.value|tostring)), returnOnEquity, cumFunding: .cumFunding.sinceOpen}]}'