hyperliquid-orders

Hyperliquid orders

Everything here ends in a signed request to /exchange. On this desk only the Execution Trader runs it, only on a ticket with a Risk PASS and the user's approval by id, and only once per approval (desk-execution-protocol). Reads used for reconciliation are in hyperliquid-account.

Concepts you must get right

• Asset index, not symbol. Perps use the index of the coin in meta.universe (BTC is 0 on mainnet, but never hardcode: read meta). Spot uses 10000 + index in spotMeta.universe. The Python SDK's Exchange accepts the coin name and resolves the index; the TS SDK wants the number.
• Price rounding. At most 5 significant figures, and at most 6 - szDecimals decimal places for perps (8 - szDecimals for spot). Integer prices are always valid. Wrong precision is rejected by the exchange.
• Size rounding. Round down to the market's szDecimals. Never round up.
• Minimum order value is 10 USD notional.
• Time in force: Gtc rests until filled or cancelled; Ioc fills what it can immediately and cancels the rest; Alo (add liquidity only) rests or is rejected if it would take.
• There is no market order. A market-style order is an Ioc limit at a price bounded by your slippage tolerance (buy: above mid; sell: below mid).
• reduceOnly orders can only reduce an existing position; use it for exits, stops and take-profits.
• cloid (client order id) is 0x + 32 hex characters (16 bytes). Unique per order. It lets you query and cancel an order even if the response was lost.
• Trigger orders (tp/sl): triggerPx is the mark price that arms the order; isMarket: true executes market-style once triggered, false places a limit at p. p is always required and acts as the worst-acceptable price after the trigger, so for market triggers set it beyond the trigger: a sell trigger's p below triggerPx, a buy trigger's p above it. A stop whose p equals its trigger can rest unfilled through a gap, so the desk defaults to a 5% bound for stop-losses (filling matters more than slippage) and 1% for take-profits; the app uses 10% for both. The ticket may override.
• Grouping: na (independent orders); normalTpsl (entry plus TP/SL as one-cancels-other tied to that entry: children are sized to the entry, placed only when it fills, cancelled if it is cancelled, and when one child fills the sibling is cancelled); positionTpsl (TP/SL tied to the position rather than to an order, shown as the position's own TP/SL, isPositionTpsl: true). Every TP/SL with an explicit size is fixed-size once placed; it does not resize when the position changes. The app's "entire position" TP/SL is a reduce-only trigger sent with size 0 under positionTpsl grouping (such orders show up live in frontendOpenOrders as sz: "0.0", isPositionTpsl: true); rehearse it on testnet before the desk relies on it.
• Responses: each order in an action gets a status: {"resting": {"oid": ...}}, {"filled": {"totalSz", "avgPx", "oid"}}, "waitingForTrigger", "waitingForFill", or {"error": "..."}. A top-level {"status": "err", "response": "..."} means the whole action was rejected.