Hyperliquid
Hyperliquid Spot Orders, Perpetual Positions, and Account Balances
Updated on
Hyperliquid is a layer 1 blockchain whose onchain order books execute spot trades and perpetual contracts, derivatives without expiry. Spot fills exchange token balances, while perpetual fills change exposure backed by collateral. Submitting an order does not establish that either change occurred. The outcome depends on matching liquidity, execution conditions, and available funds or margin. Order status, individual fills, and the resulting account state explain what actually happened.
Matching on the onchain order book
HyperCore matches orders by price priority, then time priority among orders at the same price. A submitted order interacts with available orders on the opposite side of the book. Its price must respect the market’s tick size, and its quantity must respect the lot size. These increments constrain valid orders; they do not promise enough liquidity to complete them.
A limit price sets the worst acceptable execution price. A buy can execute at that price or lower, while a sell can execute at that price or higher. Available quantities determine whether matching completes the order or produces partial fills. Perpetual orders also face margin checks when placed and when resting orders match. Acceptance therefore does not reserve an unconditional future fill.
When does an order become a commitment?
A submitted, executable order authorizes matching, so the final opportunity to reconsider without execution risk precedes submission. A limit order can match immediately when its price crosses available liquidity. A resting order remains cancellable only while its remaining quantity has not executed. Closing the interface does not retract an order that already reached the chain.
Cancellation removes an unfilled remainder after the cancellation succeeds. It cannot reverse earlier fills. An offsetting trade introduces another execution price and any applicable fees. This distinction matters when a task requires reversibility: a draft remains editable, whereas a live order can change the account before a cancellation arrives.
Spot ownership and perpetual exposure
Spot and perpetual markets produce different account entries even when their market names refer to the same underlying asset.
Spot token balances
A spot purchase increases the purchased token balance and spends the market’s quote asset, with fees affecting the final amounts. A sale exchanges the held token for the quote asset. The acquired asset is the specific token listed in that spot market. A similar name does not establish another token’s identity, redemption rights, or compatibility with an external network.
Perpetual positions
A perpetual fill changes a derivatives position rather than delivering the underlying token. Buying can open or increase a long position, or reduce an existing short. Selling has the corresponding effect on a long or short position. A reduce-only instruction constrains execution to reducing exposure, preventing an order from opening the opposite position. Collateral supports the contract, while funding payments and price movements affect its economics.
Account modes and shared balances
The account mode determines whether spot funds and perpetual collateral appear separately or share a balance. Standard mode maintains separate spot and perpetual balances, with separate balances across perpetual DEXs. Unified accounts combine each asset’s spot balance with the balance supporting cross-margin positions collateralized in that asset. Portfolio margin combines eligible assets within a broader collateral portfolio. If an eligible account lacks the asset needed for an order, portfolio margin can automatically borrow it against eligible collateral, subject to borrowing limits and caps. The resulting debt accrues interest.
These arrangements change how a balance should be interpreted. A token total may also support outstanding derivatives exposure. For unified accounts and portfolio margin, the spot balance endpoint supplies the trading account balances and holds. Reading a separate perpetual account summary as another spendable balance can produce an incorrect total. Eligibility and collateral treatment remain specific to the selected account configuration.
Submission responses and execution status
An accepted request can contain a resting order, an execution result, or an order-specific error. The outer success response alone does not distinguish these outcomes. Resting and filled results include an order identifier for tracking; an error result instead explains why the order failed. Batched requests require attention to each individual result.
Open, filled, canceled, and rejected describe different states. An order that disappears from the open-order list could have filled or been canceled. Its identifier connects the status record with its execution history. A triggered status also records activation rather than proving that the resulting order completed.
A missing response leaves execution uncertain. Resubmission before checking the original order can create additional exposure.
Reconciling fills with account changes
Reconciliation connects executed quantities and fees with the correct account’s balances or positions over the same period.
Executed quantities and charges
Fill records identify the market, side, execution price, quantity, order identifier, and fee information. Multiple fills can belong to one order. Their combined quantity explains execution progress, while their prices and quantities determine the quantity-weighted average execution price. A quote or chart price cannot replace those records because it does not describe the actual matching that occurred.
Balances, positions, and other activity
Spot balance records distinguish total holdings from holds. Perpetual account data describes positions and margin, subject to the account-mode treatment of balances. Deposits, withdrawals, transfers, and funding can also change the account during the reconciliation period. Portfolio-margin accounts also require accounting for borrowing and interest paid or earned. Comparing snapshots without those entries can wrongly attribute every difference to the order. Streaming feeds separate fills, funding, and other ledger updates so their effects can be distinguished.
A partial spot fill before cancellation
In this hypothetical example, a reader wants to buy a selected spot token while retaining the ability to stop before execution. The account has sufficient available quote balance for a valid order. Let Q represent the requested token quantity and B the starting token balance. All account inputs and execution outcomes in this example are hypothetical.
The reader submits a good-till-canceled limit order after accepting that fills can now occur. The order initially rests, then executes quantity q, where q is smaller than Q. The remaining quantity is Q minus q. A cancellation subsequently succeeds before another fill occurs.
The cancellation stops the remainder; it leaves the completed purchase intact. Assuming no other activity, the final token balance is B plus q, less any fee charged in that token. Quote spending equals the sum of executed quantity multiplied by execution price across the fills, plus any fee charged in the quote asset.
The canceled status, accumulated fills, and updated balances establish the outcome: a partial purchase with no remaining live quantity. A larger q would increase the completed purchase. If the requirement instead demands reversibility after submission, this order cannot satisfy it. Reversing the acquired exposure requires a separate trade.
Trading fees and funding entries
Execution costs depend on the relevant fee schedule and whether a fill adds or removes liquidity. Spot and perpetual markets have separate schedules. Account fee tiers, applicable discounts, and market-specific arrangements can affect the charged amount. The fill’s actual fee and fee token provide the accounting entry; a general headline rate does not describe every trade.
Funding rates concern open perpetual positions and can generate payments without a new trade. The funding rate’s sign determines which side pays. These transfers belong alongside trade fees when explaining a balance change, although they arise through a different mechanism. A completed order therefore does not freeze the economics of a position that remains open.
Margin pressure after a completed trade
Perpetual positions remain subject to maintenance margin after their opening orders finish. Cross margin shares collateral among positions within the scope permitted by the account mode. Isolated margin assigns collateral to an individual position. Some markets impose additional restrictions, including isolated-only treatment or limits on removing margin.
Hyperliquid uses the mark price to assess liquidations. That price can differ from the latest order-book execution price. Falling account equity can trigger liquidation when maintenance requirements are no longer met. Under cross margin, changes elsewhere in the shared account can affect a position’s liquidation boundary. An estimated liquidation price therefore needs its account context, especially when funding or other positions change.
An order can be complete while the resulting position still carries liquidation exposure.
HyperCore, HyperEVM, and trading access
HyperCore runs the native trading order books, while HyperEVM provides the blockchain’s general-purpose smart contract environment. Both belong to Hyperliquid. A contract interaction and a native order are different operations, even when an application combines them. An application receipt therefore needs to identify the operation that actually occurred before it can establish a trading outcome.
Trading access includes wallet connections, supported email-based onboarding, and programmatic interfaces. The chosen access method does not change the distinction between an open order and a fill. Funding the trading account also remains distinct from purchasing an asset or opening a position. A successful incoming transfer establishes receipt of funds, rather than execution of a later trading instruction.
Entry-price displays and underlying accounting
Entry price and profit-and-loss displays summarize trading activity, while the underlying accounting rests on balances, margin, and trades. Adding to a perpetual position changes its displayed average entry price using size weighting. Reducing a position leaves the entry price of the remaining position unchanged. These display conventions help interpret performance without replacing the execution history.
A position value or unrealized profit figure can move as prices change despite unchanged position quantity. Conversely, a completed fill can change quantity even when a rounded portfolio display appears stable. For explaining performance, the summary is convenient. For establishing exactly what an order changed, the fills and corresponding account entries provide the more precise comparison.
Still wondering about Hyperliquid?
Do I need to query my API wallet address to retrieve my trading balances?
Account queries use the actual trading account address, rather than the API wallet that signs its actions. An approved API wallet can sign for a master account or subaccount, but querying that signing address can return empty results. The signing identity and the account holding the funds serve different purposes.
What happens when my order would match another order from the same address?
Self-trade prevention cancels the resting order when orders from the same address would match. That interaction creates no fill, deducts no trading fee, and does not appear in the trade feed. The cancellation therefore needs to be distinguished from an executed trade when interpreting order history.
Which input errors can prevent an order from being placed?
Invalid price increments, insufficient margin or spot balance, and an order below the applicable minimum can prevent placement. Execution constraints can also reject an instruction, such as a post-only order that would immediately match. The specific error identifies the unmet condition; changing unrelated settings does not address it.
Are my onchain trading records private?
HyperCore records orders, cancellations, trades, and liquidations publicly onchain. A wallet connection does not make that activity confidential. Public account records describe address activity, but those records alone do not necessarily establish who controls the address.
How can a reconnected data feed avoid counting old fills again?
A reconnected fill subscription can begin with a snapshot containing earlier activity. The streaming API marks snapshot messages separately from subsequent updates. Software that already processed those fills needs to reconcile them with its existing records rather than treat the snapshot as entirely new execution.