Hyperliquid account equity includes current unrealized position PnL within its accounting scope. Withdrawable balance is the amount the venue currently reports as removable. Positions can still require margin, and account modes change where balances are recorded. Reconcile the actual account address, mode, DEX, open orders and timestamp before treating equity as money you can withdraw.
A profitable position can increase equity while much of that equity still supports exposure. A dashboard can also combine claims that belong to different accounts or balance systems. To explain a gap, first identify what each number measures. Then examine the proposed withdrawal against the account state that will exist when it is processed.
Start with the account mode
This guide uses Hyperliquid documentation checked on 29 October 2026. Its worked example is deliberately limited to Manual / Standard account abstraction, the original validator-operated USDC perpetuals DEX, and cross margin. Account abstraction is the setting that determines how balances interact. This example does not add spot holdings, another DEX's balance or vault equity to that pool.
That boundary matters because current Hyperliquid documentation describes several modes. Standard keeps separate spot, perp and DEX balances. Unified account combines an asset's balance across its eligible uses; Portfolio margin uses portfolio accounting across eligible collateral. The documentation instructs API users in Unified or Portfolio mode to read balances and holds from spot clearinghouse state, rather than treating individual perp DEX user states as meaningful balance sources. Hyperliquid account abstraction modes.
Record the mode before choosing a balance field. A calculation copied from a Standard-mode account can produce a tidy but misleading answer for a Unified account. The Hyperliquid cross-versus-isolated accounting guide examines the separate question of which positions share support within the applicable account boundary.
For the general meaning of those margin labels, start with cross versus isolated margin. Here the question is narrower: how much of a particular pool can leave while its remaining obligations are still met?
Read equity, position margin and withdrawable separately
For Standard-mode perpetuals, the clearinghouseState response reports positions, margin summaries, a timestamp and withdrawable. Its dex selector defaults to the empty string for the original perp DEX. The same API documentation explicitly directs Unified and Portfolio balance readers to spot balances instead. Perpetuals account-summary reference.
| Observation | What it contributes to the reconciliation | Mistake to avoid |
|---|---|---|
accountValue in the relevant margin summary | The equity of that account or pool at the observation | Treating the entire value as spare cash |
| Position notional | The marked size of open exposure | Confusing exposure with collateral owned |
Position marginUsed | Support associated with the position under the applicable rules | Assuming this is the only transfer constraint |
Reported withdrawable | The venue's current removable-amount observation for that scope | Treating an old observation as an approval |
| Open orders | Instructions that may change exposure before removal | Treating unfilled size as an existing position |
| Other balances or claims | Resources requiring their own scope and withdrawal rules | Adding them to a Standard perp pool automatically |
In this all-cross example, the equity observation belongs to crossMarginSummary.accountValue. Do not substitute a broader total when isolated allocations or other balances are present.
Use the actual master or subaccount address when querying account data. Hyperliquid warns that using an agent wallet address can return an empty result. Keep signing identity out of this read-identity decision. Info endpoint account-address guidance.
The official Python SDK makes the read boundaries visible: user_state forwards an address and DEX to clearinghouseState; open orders and spot state use separate requests. Those wrappers help identify what was queried. They do not reveal the complete margin engine or establish that several requests observed one atomic snapshot. Pinned SDK implementation.
Why equity minus opening margin can overstate headroom
Hyperliquid documents opening margin as position size multiplied by mark price, divided by selected leverage. It separately states a transfer margin requirement equal to the larger of initial margin and 10% of open position notional. Transfers include withdrawals and movements to spot or out of isolated margin. Margining and transfer requirements.
For the native BTC contract used below, prices are denominated in USDT while margin and PnL are accounted for in USDC, with no USDC/USDT exchange-rate conversion. The same numerical notional feeds the margin check. Native contract specifications.
For a deliberately simplified position-only check, define:
E: equity of the scoped cross pool.N: total marked notional of its open positions.I: their applicable initial margin requirement.R: the documented transfer requirement,max(I, 0.10 × N).
Then max(0, E − R) is the removal ceiling implied by those position inputs. It is useful for explaining a failed candidate. It is not a replacement formula for the live API's withdrawable field, particularly while orders or other obligations remain unresolved.
The distinction becomes visible at a leverage setting above 10×: the 10% term can exceed opening margin. Subtracting only position margin therefore skips a documented condition. Conversely, passing a transfer check does not measure a sensible loss budget or sufficient protection against the next price move.
A checked example: the same 600-USDC request, two outcomes
The following is an original hypothetical example, not an API response, current BTC price or report of an executed withdrawal. Assume Standard mode, the original USDC perp DEX, one cross position and an allowed 20× setting. Keep the mark fixed and omit fees, funding, transfer costs, tier changes and other ledger activity to isolate the arithmetic.
An existing long holds 0.2 BTC at an entry of 59,000 USDT per BTC. At the hypothetical mark of 60,000 USDT per BTC, unrealized price PnL is:
0.2 × (60,000 − 59,000) = 200 USDC
This uses Hyperliquid's documented mark-based PnL convention. Its documentation also distinguishes convenient entry/PnL displays from the underlying margin-and-trade accounting. Entry price and PnL.
For this teaching ledger, begin with 2,000 USDC of collateral value before that current price PnL. Equity is therefore 2,200 USDC. This bridge is not a definition of the API's totalRawUsd field.
The existing position's notional is 12,000 USDT. At 20×, its modeled initial requirement is 600 USDC. The documented transfer check retains the larger of 600 and 1,200, leaving a position-only removal ceiling of 1,000 USDC. Simply subtracting initial margin from equity would instead suggest 1,600 USDC.
Now add a resting, non-reduce-only buy order for another 0.1 BTC. The owner wants to remove 600 USDC of collateral. That amount denotes the modeled account debit; it is not a promise that a destination receives 600 after real withdrawal costs.
While the order remains open
The 0.1 BTC is still an instruction, so it is not yet part of the existing position's 12,000-USDT notional. It nevertheless matters to a withdrawal plan because execution would enlarge the position. Query its remaining size and status alongside a fresh balance observation.
Do not invent a universal reservation by multiplying every open order by the same leverage factor. Order direction, remaining quantity and reduction behavior need their actual treatment. This example makes no claim about the exact amount the engine reserves while that order rests. Its 1,000-USDC figure remains a position-only ceiling, not a reported withdrawable amount.
After cancellation or a fill
Consider two mutually exclusive continuations. In the cancellation path, confirm the order was canceled without any fill. In the fill path, assume the entire 0.1 BTC executes at the unchanged 60,000 mark before the proposed removal. The new size becomes 0.3 BTC; zero execution costs are an explicit simplification. Combined entry notional is 17,800 USDT against 18,000 USDT of marked value, so the contract's price PnL remains 200 USDC.
| Reconciled state | Confirmed cancel, no fill | Full fill before removal |
|---|---|---|
| Account equity | 2,200 USDC | 2,200 USDC |
| BTC position size | 0.2 BTC | 0.3 BTC |
| Marked position notional | 12,000 USDT | 18,000 USDT |
| Modeled initial margin at 20× | 600 USDC | 900 USDC |
| Documented position transfer requirement | 1,200 USDC | 1,800 USDC |
| Position-only removal ceiling | 1,000 USDC | 400 USDC |
| Equity after a 600-USDC debit | 1,600 USDC | 1,600 USDC |
| Simplified position check | Passes, with 400 USDC above requirement | Fails, 200 USDC below requirement |
The fill changes the requirement without changing marked equity in this frozen-price, zero-cost construction. The proposed 600-USDC removal therefore changes from passing to failing the simplified check. A positive PnL display would not catch that change.
Even the cancellation path still requires a fresh venue-reported amount and the actual total withdrawal debit. The arithmetic establishes only that the selected position requirement is met under the stated assumptions.
Validate a withdrawal against a reconciled state
Use a short decision record whenever another process can trade the account:
- Identify the pool. Record network, actual account address, abstraction mode, DEX and collateral asset. Select the balance source that belongs to that mode.
- Capture current evidence. Save the returned balance timestamp and the receipt times of position and order reads. Preserve original decimal strings. The API decimal-precision guide explains why display rounding should stay outside accounting.
- Resolve the intended order state. If the plan depends on canceling exposure, confirm both the remaining order and any fills. Hyperliquid's
MissingOrdercancel error can mean an order was never placed, was already canceled or filled. It cannot prove the no-fill path. Order and cancel error definitions. - Recheck the candidate. Compare the actual proposed debit with fresh reported withdrawability and applicable requirements. Leave an explicitly chosen operating buffer for changing prices and charges; this example does not prescribe its size.
- Reconcile the outcome. Check the account ledger after the action and verify the destination credit separately. An interrupted request or an unchanged browser display leaves the outcome unresolved.
If the available sources disagree, identify the first differing boundary: address, account mode, DEX, timestamp, position size or order outcome. Increasing the proposed amount to match a larger dashboard total does not resolve that disagreement.
Keep account removal separate from destination receipt
Hyperliquid describes withdraw3 as initiating a withdrawal flow in which validators send the request to the bridge contract. That is a different event from observing account headroom. Check the selected chain, destination, amount and current costs before signing; verify completion through the resulting records. Withdrawal request reference.
A vault interest needs another ledger before this account-level check even begins. Use the HLP-versus-user-vault withdrawal comparison to examine the claim and its withdrawal conditions. Once funds are credited to an account, reconcile that account's own equity, exposure and removable amount again. The useful number is the one supported by the account state at the time of the intended action.
