Skip to content

Execution

Hyperliquid Equity vs Withdrawable Balance: Check the Gap

Check the account mode before comparing equity with withdrawable funds, then reconcile a 600-USDC removal across a pending order, cancellation and fill.

Ivory blocks inside a ceramic tray with three blocks outside a narrow lime-marked opening
Illustration for execution; examples in this article are educational.

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.

ObservationWhat it contributes to the reconciliationMistake to avoid
accountValue in the relevant margin summaryThe equity of that account or pool at the observationTreating the entire value as spare cash
Position notionalThe marked size of open exposureConfusing exposure with collateral owned
Position marginUsedSupport associated with the position under the applicable rulesAssuming this is the only transfer constraint
Reported withdrawableThe venue's current removable-amount observation for that scopeTreating an old observation as an approval
Open ordersInstructions that may change exposure before removalTreating unfilled size as an existing position
Other balances or claimsResources requiring their own scope and withdrawal rulesAdding 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 stateConfirmed cancel, no fillFull fill before removal
Account equity2,200 USDC2,200 USDC
BTC position size0.2 BTC0.3 BTC
Marked position notional12,000 USDT18,000 USDT
Modeled initial margin at 20×600 USDC900 USDC
Documented position transfer requirement1,200 USDC1,800 USDC
Position-only removal ceiling1,000 USDC400 USDC
Equity after a 600-USDC debit1,600 USDC1,600 USDC
Simplified position checkPasses, with 400 USDC above requirementFails, 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:

  1. Identify the pool. Record network, actual account address, abstraction mode, DEX and collateral asset. Select the balance source that belongs to that mode.
  2. 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.
  3. Resolve the intended order state. If the plan depends on canceling exposure, confirm both the remaining order and any fills. Hyperliquid's MissingOrder cancel 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.
  4. 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.
  5. 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.

Keep the context with the example.

Each worked example is illustrative, with its sources and assumptions in the article. Read our editorial standards for authorship, verification and corrections.