Hyperliquid Get Account

Get Hyperliquid account summary including perp positions, open orders, margin status, and HIP-4 outcome token positions. Returns account value, active positions with PnL, resting orders, and outcome market holdings. Ideal for: portfolio monitoring, risk assessment, cross-venue comparison, and pre-trade checks.

Catalog action Hyperliquid

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": []}

bash
curl -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.

Was this page helpful?