Orders, Fills, and Cancellations

Create a parent order with POST /v1/orders. Trade8 evaluates the request, routes eligible child orders, and reports each fill with its exchange and fee. Track the parent through the orders channel and executions through fills.

Order Types

Type	Required Price Fields	Behavior
`market`	None	Executes available size within the routing slippage boundary
`limit`	`limit_price`	Buys at or below the limit; sells at or above it
`stop_market`	Trigger fields	Submits a market order after the stop condition
`stop_limit`	Trigger fields and `limit_price`	Submits a limit order after the stop condition
`take_profit_market`	Trigger fields	Submits a market order after the profit condition
`take_profit_limit`	Trigger fields and `limit_price`	Submits a limit order after the profit condition

Trigger fields are trigger_price, trigger_source (mark, last, or index), and trigger_venue. The trigger exchange must expose the selected instrument and settlement asset. Buy stops trigger at or above the price; sell stops at or below. Buy take-profit orders trigger at or below; sell take-profit orders at or above.

When trigger data is stale, evaluation pauses until a fresh value arrives. A gap can cause the first fresh price to cross the trigger. Execution then follows the order’s routing and price constraints.

Time-in-Force and Trading Controls

GTC: keep a limit order open until filled, cancelled, or expired by exchange policy. Default for limit variants.
IOC: execute available size, then cancel the remainder. Required for market variants.
FOK: execute the full size immediately on one exchange or cancel. Use direct routing to a capable exchange.
Post-only: ordinary GTC limit orders only. A child that would take liquidity is rejected by the exchange.
Reduce-only: each fill can only reduce exposure on the destination exchange. Route exits to the exchange that holds the position.
Self-trade prevention: cancel_newest, cancel_oldest, or cancel_both. The default is cancel_newest within the account.

Omitted post_only and reduce_only default to false. Exchange capabilities and risk rules are checked before routing. A child rejection can coexist with fills on another exchange; read the parent quantities and child records together.

Lifecycle States

State	Meaning
`pending`	Request is undergoing validation and routing
`accepted`	Order is open for execution
`trigger_pending`	Conditional order is waiting for its trigger
`partially_filled`	Some quantity has executed; an open remainder exists
`filled`	All requested quantity has executed
`cancelled`	Cancellation is complete for the open remainder
`rejected`	The order has ended after a validation or execution rejection
`expired`	The unfilled remainder has expired

A timeout leaves the client with an unknown outcome. Reconcile by order ID or client order ID. unknown is a client recovery condition, not a persisted order status.

Quantities and Revisions

For every order:

requested_quantity = filled_quantity + remaining_quantity + cancelled_quantity

cancelled_quantity includes quantity retired by rejection or expiry. A terminal order has zero remaining quantity. average_fill_price is the quantity-weighted average of executed fills, or null before the first fill.

{
  "order_id": "ord_example_01",
  "status": "partially_filled",
  "requested_quantity": "0.100",
  "filled_quantity": "0.060",
  "remaining_quantity": "0.040",
  "cancelled_quantity": "0.000",
  "average_fill_price": "77000.00",
  "revision": 2
}

This is an excerpt of the full order record. Apply only newer revisions when reconciling REST and WebSocket results. Store fills by fill_id so reconnects preserve accurate totals.

Inspect the Exchange Split

The example parent routes 0.060 BTC to Binance and 0.040 BTC to Bybit. Read /v1/orders/{order_id}/children for exchange IDs and child state. Read /v1/orders/{order_id}/fills for executions and fees.

At 77,000 USDT, a Binance maker fill of 0.060 BTC with an illustrative fee rate of 0.0001 costs 0.462 USDT. Keep the fee’s asset next to its value.

Amend or Cancel

An amendment supplies the last observed expected_revision, plus a new total quantity, price, or both. Total quantity includes existing fills. A concurrent fill can return REVISION_CONFLICT; read the order again before deciding what to change. Price changes can reset exchange queue priority.

A cancellation acknowledges the cancellation request. Fills may arrive while exchange acknowledgements are pending. Continue processing events until the order is terminal, then reconcile its final fills and quantities.

Stop-Loss Example on Hyperliquid

This sell stop reduces a long BTC position on Hyperliquid. It triggers when Hyperliquid’s mark price reaches or falls below 73,000 USDC.

{
  "account_id": "acct_example_main",
  "client_order_id": "btc-stop-0001",
  "instrument": "BTC-PERP",
  "settlement_asset": "USDC",
  "side": "sell",
  "type": "stop_market",
  "quantity": "0.100",
  "trigger_price": "73000",
  "trigger_source": "mark",
  "trigger_venue": "hyperliquid",
  "time_in_force": "IOC",
  "reduce_only": true,
  "routing": "direct",
  "venue_policy": { "allowed": ["hyperliquid"], "max_slippage_bps": "25" }
}

The slippage boundary can leave a remainder unfilled during a gap. Monitor the resulting position and terminal quantities. For a take-profit exit, use take_profit_market or take_profit_limit with its own client ID. If your strategy pairs a stop and profit order, cancel the sibling when one completes and keep both reduce-only.