Skip to content

Execution

Hyperliquid Cross vs Isolated Margin Accounting

Follow USDC between a cross pool and an isolated position, then check why raising leverage can leave withdrawal headroom unchanged.

Two ivory trays holding folded arches, with a lime tile hovering in the gap between them
Illustration for execution; examples in this article are educational.

Hyperliquid cross margin shares collateral within the pool defined by your account mode; isolated margin assigns collateral to one position. Adding isolated margin reduces the resources left for cross positions while total equity stays unchanged. A leverage update can reduce initial requirements without increasing withdrawal headroom because a separate transfer requirement still applies.

The ledger below uses Manual / Standard account abstraction, validator-operated USDC perpetuals and two unchanged long positions. It applies documentation checked on 29 October 2026. The amounts are hypothetical, with fees, funding, open orders and concurrent activity excluded. Its withdrawal figures are modeled checks that must be reconciled with current account responses before any action.

Check account abstraction before comparing margin modes

Hyperliquid has two different choices to identify: the account's abstraction mode and a position's cross or isolated setting. Record both. The general cross-versus-isolated guide explains the collateral boundary; the account abstraction determines where that boundary sits on Hyperliquid.

In Manual / Standard mode, spot and perpetual balances are separate, and each perpetual DEX has a separate balance. Cross margin operates within that DEX. Unified account instead uses one balance per collateral asset across the relevant cross positions and spot activity. Portfolio margin brings eligible assets into a broader portfolio calculation. The official documentation directs unified and portfolio API users to spot clearinghouse balances and holds; individual perpetual-DEX user states are not meaningful account-balance views for those modes. Hyperliquid account abstraction modes.

Consequently, a native-perps balance in the example cannot be added to a second DEX's balance and called one cross pool under Standard mode. Identify the DEX and collateral before aggregating anything. The HIP-3 versus native perpetuals guide develops that market-context check.

The market's settings matter too. Current metadata distinguishes strictIsolated, which prevents margin removal, from noCross, which permits isolated margin with removal enabled. The older onlyIsolated flag covers either restriction and is deprecated. A boolean alone cannot tell an application which removal rule applies. Perpetual metadata reference.

Keep equity, margin requirements and transfers separate

Equity measures the resources remaining after marked gains and losses. A margin requirement measures what must support an open position or proposed action. Moving collateral between the cross pool and an isolated position changes its location without producing trading profit.

Hyperliquid documents opening margin as position notional divided by selected leverage. Removing margin also has a transfer requirement: the remaining margin must meet the greater of initial margin and 10% of open notional. Withdrawals, spot transfers and isolated-margin transfers count as removals. Hyperliquid margining rules.

For this simplified cross pool, calculate a modeled transfer ceiling as cross equity minus the larger requirement, floored at zero. Check the isolated position separately when taking margin out of its allocation. These calculations apply the documented rule to the stated pools; they do not reproduce every live engine check or guarantee the API's withdrawable result.

This distinction also prevents double counting. Cross equity already contains the support available to its participating positions. Adding a position's displayed margin to that equity would count part of the same resources twice. Keep an equity column and a requirement column, then compare them.

A two-position Hyperliquid margin ledger

Assume the Standard native-perps account begins with 5,000 USDC and these positions. The example assumes the requested leverage and margin modes are permitted, including removal from ETH's isolated allocation.

The price inputs below are USDT per base unit. Hyperliquid's contract specification describes USDC collateral with USDT-denominated linear contracts and no USDC/USDT exchange-rate conversion. Accordingly, the example accounts for margin and PnL in USDC without an FX adjustment. Native contract specifications.

PositionQuantity and markOpen notionalMargin setting
BTC long0.1 BTC at 100,00010,000Cross, 10×
ETH long2 ETH at 2,5005,000Isolated, 5×

Entry prices equal the marks, so both positions initially have zero price PnL. Allocate 1,000 USDC to ETH, calculated as 5,000 divided by 5. That leaves 4,000 USDC of cross equity supporting BTC. BTC's initial requirement is 10,000 divided by 10, also 1,000 USDC.

The BTC cross transfer requirement is the larger of 1,000 and 10% of 10,000. Both equal 1,000. The modeled cross transfer ceiling is therefore 4,000 minus 1,000, or 3,000 USDC.

Hold quantities, marks and all excluded activity constant through the next steps. Every number in the following table is USDC; the final column is the simplified model's ceiling rather than a captured API response.

StateCross equityETH isolated equityTotal equityCross transfer ceiling
Initial snapshot4,0001,0005,0003,000
Add 500 to ETH margin3,5001,5005,0002,500
Raise BTC leverage to 20×3,5001,5005,0002,500
Return 300 from ETH margin3,8001,2005,0002,800
Withdraw 2,700 from cross1,1001,2002,300100

Adding 500 to ETH reduces cross equity by exactly 500. Total equity stays at 5,000. ETH receives more support, while BTC's shared pool has less. Reporting the addition as a deposit into the account would overstate total capital; it is an internal reallocation.

Why the 20× setting releases no extra withdrawal room here

At 20×, BTC's initial requirement falls from 1,000 to 500 USDC. Its notional remains 10,000, so the 10% transfer component remains 1,000. The larger requirement is still 1,000, leaving the same 2,500 ceiling against cross equity of 3,500.

The leverage setting changed, but the BTC quantity and its dollar response to a price move did not. A display that subtracts only the new 500 initial requirement would show 3,000 available and overstate this model's removable amount by 500. Keep the two requirements visible when explaining the discrepancy.

Return isolated margin before evaluating the withdrawal

Returning 300 from ETH leaves 1,200 in the isolated position. Its modeled removal minimum is the greater of its 1,000 initial requirement and 500, which is 10% of its notional. The remaining 1,200 clears that check. Cross equity rises to 3,800 and the modeled cross ceiling rises to 2,800.

A proposed 2,700 withdrawal exceeds the earlier 2,500 ceiling but fits the later 2,800 ceiling. In this construction, it leaves 1,100 in cross and 1,200 isolated: total equity falls from 5,000 to 2,300 because 2,700 leaves the account. The sequence matters. A planned margin return cannot fund an earlier withdrawal until that return is confirmed.

Distinguish a leverage update from a margin transfer

The exchange API exposes separate actions. updateLeverage takes the asset, isCross and an integer leverage. updateIsolatedMargin takes the signed integer ntli in millionths of USDC: one USDC corresponds to 1,000,000 units. Exchange update actions.

In the official Python SDK pinned at commit 2fdb18f, update_leverage resolves the market to an asset and constructs the first action. update_isolated_margin converts its amount through float_to_usd_int before constructing the second. The inspected source establishes client request construction; it does not expose the core margin engine. Pinned exchange methods, six-decimal conversion helper.

The hypothetical 500-USDC addition corresponds to ntli of 500,000,000; the 300-USDC removal corresponds to −300,000,000. Record the human amount, unit scale and final signed value together. The API decimal-precision guide explains how to preserve that numerical intent across parsing and serialization.

Do not infer a fixed margin transfer from a successful leverage-setting update. Read the resulting state. An unchanged quantity can acquire a different requirement or allocation, and a request acknowledgement alone cannot establish which balance became available.

Reconcile the readback before treating funds as withdrawable

For this Standard account, clearinghouseState provides positions, the overall marginSummary, crossMarginSummary, withdrawable and a timestamp. Its request includes the user and DEX. The Python SDK's user_state sends those fields directly. Perpetual account-summary response, pinned read method.

For the zero-PnL snapshots, compare the ledger's total and cross equity with the respective summaries' accountValue fields. Compare ETH's allocated equity with its reported marginUsed. These are reconciliation targets at the stated snapshot, not additional amounts to add to the summaries.

Use the actual master or subaccount address being reconciled. Hyperliquid warns that querying an agent wallet's address can return an empty result. Info endpoint identity rules.

Verification pointEvidence to keepDecision it supports
Account and market contextUser address, abstraction, DEX and collateralSelect the correct balance view
Position stateQuantity, entry, mark, PnL, margin type and allocationSeparate exposure from collateral movement
Margin updateAction result and a later matching stateCount only confirmed reallocations
Other obligationsOpen orders, fills, funding and ledger updatesExplain changes omitted by the simple example
Withdrawal checkCurrent reported availability and request resultReconcile the proposed amount with live rules

Take a before snapshot, make one authorized change, then obtain a later snapshot before relying on its effect. Compare total equity, cross equity and isolated allocation together. With unchanged marks and no costs or external transfers, an internal margin movement should reconcile as equal and opposite changes. If it does not, investigate intervening activity and timestamps before assigning a cause.

The equity-versus-withdrawable guide examines the broader availability question, including a pending order. This article's fixed-position arithmetic leaves those obligations out deliberately; the live review must put them back in.

Recheck after prices move

Extend the final ledger with a hypothetical BTC mark of 99,000 and ETH mark of 2,400. BTC loses 0.1 multiplied by 1,000, or 100 USDC. ETH loses 2 multiplied by 100, or 200 USDC. Cross equity becomes 1,000, isolated equity becomes 1,000, and total equity becomes 2,000. The earlier margin transfers have not erased either loss.

BTC's new notional is 9,900. At 20× its initial requirement is 495, while the transfer component is 990. The modeled cross transfer ceiling contracts from 100 to just 10 USDC. This is an availability calculation, not a liquidation forecast: Hyperliquid uses maintenance requirements and mark-price rules for liquidation. Liquidation mechanics.

A previously valid allocation plan therefore needs a fresh observation after market movement. Preserve the quantities, reconcile each pool's equity, recompute the relevant requirements and compare the proposed removal with current reported availability. That sequence tells you what changed and whether the next transfer still fits the account you actually have.

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.