> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

![Hyperliquid Account Balance & Equity logo](https://cdn.b3.fun/hyperliquid-logo.png)
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

**Workflow node**

```json
{
  "type": "hyperliquid-get-account",
  "payload": {
    "address": "0x0000000000000000000000000000000000000000"
  },
  "children": []
}
```
  **Test with API**

```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"
  }
}'
```

**Use expressions for dynamic values**

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.