Hyper liquid Hyper liquid trade fills and balance reconciliation
Hyper liquid records executed trades as fills, which connect an order to changes in token balances or perpetual positions. Trace a trade by matching those fills to its order identifier, then account for fees and other balance movements. A partial fill confirms only the executed quantity; the order’s remaining status determines whether more execution can follow.
A balance comparison needs matching timestamps and the correct account view. Order acceptance, completed execution, and a reconciled balance answer different questions. Keeping them separate prevents a missing confirmation or an unfinished order from becoming an unnecessary repeat trade.
A canceled remainder leaves earlier fills intact, so completion depends on both executed quantity and the order’s final state.
Following a limit order through confirmation
For a limit order with a recorded size and price, good til canceled and immediate or cancel provide different outcomes for any unexecuted quantity. Both retain the limit price boundary. Available liquidity determines how much can match, while the selected duration rule determines whether the remainder can wait.
Before submission, record the relevant balance or position, available funds or margin, and outstanding orders. The requested price and size must meet the market’s requirements. The following options differ in execution behavior; none guarantees the requested quantity will trade.
| Limit order option | Constraint on execution and the remainder |
|---|---|
| Good til canceled (GTC) | Can execute immediately; an accepted remainder can rest until filled or canceled. |
| Immediate or cancel (IOC) | Executes available quantity immediately within the limit; cancels the unfilled remainder. |
| Add liquidity only (ALO) | Must enter as a resting order; an immediate match causes rejection instead. |
Waiting for a resting remainder preserves its existing limit, with no promise of another fill. Choosing IOC ends that order’s immediate execution attempt without leaving a resting remainder. Confirmation requires the executed quantity and final order state, followed by the corresponding balance or position change.
If the submission response is missing, stop new submissions while resolving that order’s status and fills. A lost response does not establish rejection. Continue reconciliation when the execution record is available; if its outcome remains unresolved, submitting the original size again risks additional exposure.
A starting balance with a matching timestamp
The starting record needs the account, market, timestamp, token quantities, and any existing position relevant to the trade. Preserve the account mode as well. Standard mode separates spot and perpetual balances, whereas unified accounts share a balance for each collateral asset. Portfolio margin uses eligible assets together. Comparing different account views can create an apparent discrepancy even when the underlying records agree. A displayed portfolio value also introduces price changes, so it cannot substitute for token quantities.
What does a partial fill mean for the remaining order?
A partial fill means some requested quantity traded, while the order’s remaining quantity requires a separate status check. For an unchanged order, executed size is the sum of its fill quantities. Subtracting that sum from the original size gives the unexecuted amount, but does not establish whether that amount remains open.
Cancellation prevents further execution of the canceled remainder; it leaves earlier fills intact. An order missing from the open-order list therefore needs its historical state and execution record. Replacement sizing based only on the original request can overlook an earlier partial execution. Modifications also require the corresponding order history rather than an assumption that the initial size still applies.
Matching spot fills to token movements
Spot reconciliation follows the quantities exchanged in each fill, with the fee applied to its recorded asset. A purchase increases the acquired token balance and spends the quote asset; a sale reverses those directions. Other activity during the same interval must remain separate from that trade.
For a group of fills, gross quote value equals the sum of each execution price multiplied by its executed size. The size-weighted average price divides that value by total executed size. An ordinary average of fill prices can give the wrong result when quantities differ. These calculations describe execution before fees. Reconcile each token separately, preserving the precision in the records until the final display.
Why can account value change without another fill?
Account value can change without another fill because an open perpetual position’s unrealized profit or loss moves with the mark price. Position size and displayed value therefore measure different things.
A fill changes exposure through its signed quantity. A buy can increase a long position, reduce a short position, or cross through zero. A sell has the opposite effects. The starting position determines which interpretation applies. When a fill closes part of a perpetual position, reconcile the realized trading profit or loss and fees as well as the change in position size.
Unrealized profit or loss on a perpetual position uses the mark price. An execution price describes a completed trade, while the mark price values continuing exposure. Comparing an earlier execution against a later account value combines a trade with subsequent market movement.
Margin adds another distinction. Collateral committed to positions affects what remains available, and cross margin shares collateral within the account mode’s supported scope. Isolated margin assigns collateral to an individual position. A smaller available amount therefore does not, by itself, measure a trading loss. The balance, position, and margin records must describe the same account configuration.
Fees belong to the asset charged
The fee amount and fee token in the execution record determine the balance adjustment for that fill. Preserve the sign: a negative fee represents a rebate. Combining fees denominated in different assets into one token total produces an invalid reconciliation.
A fill’s total fee already includes its builder fee when one applies. Adding the separate builder-fee field again would double count that charge. Fee schedules distinguish spot and perpetual trading, and account eligibility can change the applicable rate. Rebuilding an old fill using today’s displayed rate can therefore disagree with the amount actually charged.
Transfers and funding outside the fill history
Deposits, withdrawals, and transfers can change balances without appearing as trading fills. Funding payments also affect perpetual balances separately from execution. For portfolio margin accounts, track borrow liabilities and interest paid or earned alongside token balances. Reconciliation across an interval needs these movements alongside the trades, with incoming and outgoing amounts assigned their correct signs.
A funding rate describes how a payment is determined; the recorded payment supplies the account movement. A present rate cannot establish a past charge. Account mode also determines where shared balances appear. For unified accounts and portfolio margin, the spot clearinghouse balance record covers trading balances across spot and perpetuals. Treating an individual perpetual market’s account view as a separate cash balance can misstate the total.
Overlapping records and incomplete history
A live fill stream can begin with a snapshot of existing records before delivering new events. Adding the snapshot to an already imported history without checking overlap can count the same execution twice. Preserve identifiers and timestamps so repeated delivery does not become repeated trading volume.
Historical queries also have response and retention limits. A returned list may cover only part of the period needed for reconciliation. Retain exports when a longer record matters, and keep the requested interval distinct from the interval actually returned. A missing earlier record leaves the opening balance explanation incomplete; it does not establish that the corresponding trade never happened.
Order identifiers and the final reconciliation
The order identifier joins a submitted instruction to its status and associated fills. Individual trade records carry their own identifiers because one order can generate multiple executions. Client order identifiers, when supplied, provide another supported way to query order status. Keep these identifiers intact when exporting or combining records.
A reconciled trade has an accounted-for executed quantity, a known remainder state, and balance changes consistent with the surrounding activity. Any residual difference belongs to a specific account, asset, and interval. An unexplained balance movement is an unreliable basis for sizing another order.
Things people ask about Hyper liquid
Why does a cancel request report that an order was never placed, already canceled, or filled?
That response means the cancellation could not find an order it could cancel. The message groups several possible states together, so it does not identify which one occurred. In particular, it does not prove the order never traded. Its execution history remains relevant even when cancellation fails.
Can a reduce-only order fail even when its price reaches the market?
A reduce-only order can fail if it would increase the position instead of reducing it. Matching price alone does not satisfy that position constraint. Changes to the position can affect whether the order qualifies, so a rejection or cancellation must be interpreted against the position at that time.
What does marginCanceled mean in an order history?
The marginCanceled status means the order was canceled because there was insufficient margin to fill it. Margin checks occur when placing a perpetual order and again for a resting order during matching. Passing the initial check therefore does not establish that the account will satisfy a later check.
How can two fill exports show different row counts for the same order?
Fill aggregation can combine several executions into fewer records. When enabled, it combines partial fills from a crossing order matching multiple resting orders. Aggregation of a resting order’s fills from different crossing orders requires those fills to share a block. Row counts therefore need the same aggregation setting and time coverage before comparison.
Does an unchanged entry price mean a closing trade failed?
An unchanged entry price does not mean a closing trade failed. Closing perpetual trades leave the entry price unchanged, while opening trades update it using a size-weighted average. A reduction in position size can therefore accompany the same displayed entry price. Entry price alone cannot establish whether execution occurred.
Is a successful HTTP response proof that every order in a batch traded?
A successful HTTP response does not prove that every order traded. The response can contain an error for an individual order even when its outer status indicates success. Some validation failures reject the entire batch with one error. Resting, filled, and rejected outcomes require interpretation of the returned order results.
Which timestamp units do time-filtered fill queries use?
Time-filtered fill queries use milliseconds for their start and end timestamps. Both boundaries are inclusive. A seconds-based timestamp selects the wrong interval, while overlapping boundaries can return records already present in an earlier export. Preserve the original timestamps when converting them into readable dates or combining query results.