Hyper liquid - Order Records and Trade Fills
last updated
Hyper liquid order records connect trading instructions to execution through an order ID. To reconcile a trade, match that ID to its fills, total the executed size and compare it with the recorded order quantity. Read the final status alongside those quantities: cancellation can leave earlier executions intact. Matching also requires compatible account, market and time information, because an incomplete history or grouped export can make a valid trade appear inconsistent.
In short: An order can finish with an unfilled remainder, so reconcile its executed quantity against both the fill records and its final status.
Order IDs and Execution Fields
The order ID, oid, connects an order record with its associated fills. Preserve it exactly when moving records between an API response, spreadsheet and reconciliation tool. Keep the account and environment alongside it so imports do not mix unrelated datasets.
A fill records execution price in px, execution size in sz and its timestamp in time. The separate tid identifies a trade. These fields answer different questions: the order ID groups executions under an instruction, while trade information helps distinguish individual executions within that group.
The Starting Record and Placement Response
The starting record should preserve the submitted size, side, market identifier and price condition before subsequent updates change the displayed order. Record any client order ID and retain the placement response alongside the request.
A placement response can report a resting order, an immediate execution or an error. A resting response supplies an order ID; an execution response can include total size and average price. The outer response alone does not establish execution, so inspect the individual order result.
Keep later modifications separately. Comparing fills against an overwritten starting quantity can create a discrepancy in the local record even when the exchange processed each instruction correctly.
Compatible Market Identifiers
Market identity must agree across the submitted instruction and returned execution records before their quantities belong in the same calculation. Order actions use integer asset identifiers, while returned market fields use their documented representations.
Spot pair identifiers differ from token identifiers. Mainnet and testnet also have different asset mappings. Resolve identifiers against the relevant environment and market metadata instead of treating a displayed token name as a universal join key. Builder-deployed perpetual market names include a deployment prefix, which also belongs in the preserved identifier.
Compatibility includes units. A quantity column and a monetary value column cannot substitute for each other, even when their headings look similar.
Executed Size and Average Price
Executed size comes from adding the sizes of distinct fills belonging to the same order. An average execution price requires weighting each price by its corresponding size.
Quantity Reconciliation
For an unchanged order with complete history, compare its original quantity with executed quantity and any unfilled remainder. Preserve cancellation as the explanation for a terminated remainder. Do not convert canceled quantity into executed quantity merely to balance a report.
Express the relationship as original quantity = executed quantity + unfilled quantity. The unfilled quantity can remain open or cease to be available for execution after cancellation. Modifications require the relevant order records rather than an assumption that the initial quantity stayed fixed.
Size-Weighted Price
Calculate average execution price as the sum of each fill price multiplied by its size, divided by total executed size. A simple average of row prices gives equal weight to unequal executions and can misstate the result.
Keep full decimal precision during calculation and round only the displayed result. With no executed quantity, an average execution price is undefined. Fees belong in a separate cost calculation rather than inside the price average.
Partial Fills and Terminal Status
A partially executed order has completed some trading while leaving part of its requested quantity unfilled. The order’s time-in-force instruction determines whether that remainder can stay on the book.
An immediate-or-cancel order cancels its unfilled portion instead of leaving that portion resting on the order book. A good-til-canceled order can remain available until execution or cancellation. Post-only instructions prevent immediate matching when the order arrives. These differences explain why identical requested quantities need not produce identical execution totals.
Cancellation does not reverse an earlier fill.
A trigger event also differs from execution. A stop-limit instruction activates a limit order, whose price condition still governs matching. Treat the trigger as a change in eligibility to execute, then use fills to establish the quantity actually traded.
History Windows and Aggregation
Historical records need a defined time window and aggregation setting before totals from separate downloads can be compared meaningfully. Save those settings with each dataset.
Time Coverage
The userFillsByTime request uses millisecond timestamps and inclusive time boundaries. Its responses and retained history are bounded. An old execution missing from the returned records therefore does not establish that the order never traded. The separate historicalOrders request returns recent order records with their statuses.
Mark the earliest and latest execution times actually present. A requested date range and a complete returned range are different properties. Overlapping downloads also need duplicate handling before their quantities enter a combined total.
Grouped Execution Records
The aggregateByTime option combines eligible partial fills. Crossing-order executions against different resting orders can be combined; resting-order executions against different crossing orders aggregate only within the same block.
Compare datasets at the same aggregation level. Adding an aggregate row to the component rows it already represents counts execution twice. Row count alone is therefore a poor test of whether two exports contain equivalent trading activity.
Streaming Updates and Duplicate Records
The orderUpdates and userFills subscriptions describe different events: changes to orders and completed executions. A local record should preserve both without treating every order update as another trade.
The initial user-fill subscription snapshot carries isSnapshot: true.
Previously processed snapshot entries must not increase the executed total again. Preserve account context and the available execution identifiers when identifying repeated records; timestamps alone can group distinct fills together.
Connections can drop without advance notice. Reconnection snapshots and corresponding information requests support recovery of missed data, subject to available history. A collector should retain its last processed records so a recovered overlap does not become duplicate execution.
Execution Price and Account Changes
A reconciled execution total explains how much an order traded, while an account balance reflects additional activity. Keep those calculations separate when investigating a monetary mismatch.
Fill records include fee amounts and the token used to pay them. Funding payments and other ledger updates have separate data streams. Consequently, a balance change need not equal fill size multiplied by execution price. Funding rates matter when reconciling perpetual account cash flows, but they do not change the executed size assigned to an order.
Group monetary amounts by their units before adding them. A report that combines different fee tokens without an explicit conversion basis produces a number without a consistent meaning.
Missing Status and Unproven Execution
An unknownOid response means the status query did not locate the requested order. It does not establish whether trading occurred elsewhere in the available records. Preserve the unresolved result instead of converting it into a filled or canceled state.
A Missing Order ID in an Export
For an export missing its order ID, the immediate task is restoring the join between an instruction and its executions. The export must retain another compatible identifier before an exact lookup is possible.
If the export retains a client order ID, query orderStatus for the trading account using that identifier. A located order supplies its exchange order ID. Match the returned ID against the fill records, then compare quantities using the same market and time coverage.
Directly importing the incomplete export leaves the join unresolved. Retrieving the order record can restore it without submitting another trade. For either approach, confirm that the records identify the same order and market before comparing executed and requested quantities.
- If the client ID resolves, retain the returned order ID with the original export row.
- If the market identifiers disagree, resolve their mapping before combining quantities.
- If history is incomplete, mark the executed total as incomplete rather than forcing a match.
- If duplicate or aggregate rows overlap, remove double counting before comparing totals.
- If neither order ID nor client ID survives, retain the mismatch until an original record supplies an exact link.
A matching timestamp and similar price can narrow a search, but they do not prove an exact order-to-fill relationship.
The Boundary of a Completed Reconciliation
A completed reconciliation ties the preserved instruction to distinct executions and explains the remaining quantity through the order’s recorded state. Retain the matched rows, calculation inputs and history coverage so another calculation can reproduce the result.
The conclusion changes when a new fill arrives, a modification changes the relevant quantity or recovered history supplies a missing execution. Recalculate the affected order using the expanded record. If identifiers or historical coverage remain missing, keep that specific part unresolved; a balanced spreadsheet cannot replace the missing relationship.
Hyper liquid: frequently asked questions
Why Can a Successful HTTP Response Contain an Order Error?
A successful HTTP response can carry an application-level rejection. Inspect the returned order results rather than treating transport success as execution. Batched requests can also fail during pre-validation with one error covering the entire payload. Preserve that distinction when assigning results to submitted instructions.
Does a Failed Cancellation Prove an Order Filled?
A failed cancellation does not prove execution. A missing-order cancellation error can mean the order never existed, was already canceled or was already filled. Its fills and recorded status determine which explanation applies; the cancellation error alone cannot distinguish them.
How Should a Negative Fee Appear in a Reconciliation?
A negative fill fee represents a rebate. Preserve its sign when totaling execution costs rather than converting every fee entry into a positive charge. Keep the fee token attached to the amount so the total retains a consistent unit.
Should builderFee Be Added to the Fill Fee?
The reported fill fee already includes builderFee when that component is present. Adding it again double-counts the builder component. Preserve it separately for a cost breakdown while using the inclusive fee for the total.
How Do TWAP Slice Fills Relate to the Parent Order?
A time-weighted average price (TWAP) order divides trading into scheduled suborders. Its slice-fill records connect an individual fill with a twapId. Keep that parent identifier when reconciling the scheduled instruction, while retaining each fill’s own order ID. This preserves the relationship between the overall execution schedule and its component orders.
Is a Screenshot Enough to Resolve a Disputed Fill Total?
A screenshot is useful only to the extent it preserves the information needed for the comparison. Cropped identifiers, rounded quantities or hidden time filters can prevent exact reconciliation. Keep the underlying records alongside the image so the executed total can be reproduced without inferring missing digits or settings.