Hyperliquid Account Balance & Equity
Read a Hyperliquid account's balance and equity from its clearinghouse / user state: account value (total equity), available margin, and used margin (marginSummary), plus withdrawable balance. Also returns active perp positions (each with its own unrealized PnL), resting open orders, and HIP-4 outcome token holdings. Set `balanceOnly: true` for a cheap equity/balance read that skips position aggregation (positions, open orders and outcome holdings come back empty). Ideal for: live-equity position sizing, portfolio monitoring, risk and margin-health checks, and pre-trade balance gates.
Catalog action Hyperliquid
Read a Hyperliquid account's balance and equity from its clearinghouse / user state: account value (total equity), available margin, and used margin (marginSummary), plus withdrawable balance. Also returns active perp positions (each with its own unrealized PnL), resting open orders, and HIP-4 outcome token holdings. Set balanceOnly: true for a cheap equity/balance read that skips position aggregation (positions, open orders and outcome holdings come back empty). Ideal for: live-equity position sizing, portfolio monitoring, risk and margin-health checks, and pre-trade balance gates.
At a Glance
| Field | Value |
|---|---|
| Action ID | hyperliquid-get-account |
| Category | Hyperliquid |
| Connector | Not required |
| Requires gas | No |
| Funds movement | None declared |
| Tags | hyperliquid, perps, positions, portfolio, balance |
Payload Schema
| Field | Type | Required | Description |
|---|---|---|---|
address | string | Yes | Hyperliquid account address (0x...) to inspect. Hyperliquid account state is public, so any address can be queried — pass the wallet you want to read (e.g. the user's connected wallet, or an arbitrary account for read-only lookups). |
dex | string | No | HIP-3 DEX name for TradFi markets. Omit for standard crypto perps. xyz = trade.xyz (stocks, indices, commodities), flx = flx.finance, vntl = vntl.exchange |
balanceOnly | boolean | No | When true, fetch only the balance figures (accountValue, availableBalance, withdrawable, margin mode) and skip the open-orders / mark-price / position aggregation — the positions, openOrders and outcomePositions arrays are returned empty. Much cheaper against Hyperliquid rate limits; use for balance-gate checks where positions are not needed. |
Result Schema
| Field | Type | Required | Description |
|---|---|---|---|
accountValue | string | Yes | Total account value in USD. Mode-aware: for unified/portfolio-margin accounts this is the spot USDC balance (where the unified collateral lives); for default accounts it is the perps clearinghouse account value. |
totalMarginUsed | string | No | Total margin currently in use |
totalPositionValue | string | No | Total notional value of all positions |
availableBalance | string | No | Available balance for new positions. Mode-aware: unified/portfolio-margin = spot USDC total minus held (reserved) amount; default = accountValue minus margin in use. |
crossMaintenanceMarginUsed | string | No | Cross-margin maintenance margin used. Liquidation occurs when accountValue approaches this value. Margin health ratio = accountValue / crossMaintenanceMarginUsed (>2 healthy, ~1 = liquidation). |
withdrawable | string | No | Maximum amount that can be withdrawn without affecting positions. Mode-aware (unified accounts derive this from spot USDC total minus held; default uses the native Hyperliquid perps risk metric). |
abstraction | string | No | Account margin mode: 'unifiedAccount' / 'portfolioMargin' share a single USDC balance across spot and perps (collateral reported in spot); 'default' keeps spot and perps separate; 'disabled' behaves like 'default'. |
spotUsdc | object | No | Spot USDC balance. For unified/portfolio-margin accounts this is the source of perp collateral: 'total' is the full balance, 'hold' is the portion reserved for open positions/orders. |
positions | array | Yes | Active perpetual positions |
openOrders | array | Yes | Open orders on the book |
outcomePositions | array | No | HIP-4 outcome token positions (prediction market shares) |
Examples
json{ "type": "hyperliquid-get-account", "payload": { "address": "0x0000000000000000000000000000000000000000" }, "children": []}
bashcurl -X POST "https://api.b3os.org/v1/actions/hyperliquid-get-account/test" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inputs": { "address": "0x0000000000000000000000000000000000000000" }}'
Payload fields can use workflow expressions such as {{$trigger.body.amount}}, {{$nodes.fetch.result.price}}, and {{$props.asset}} when the value should come from a trigger, prior node, or reusable workflow prop.