Overview
Conditional orders activate when the mark price crosses a specified trigger price. BULK supports six conditional order types, all triggered by the fair/mark price (not last traded price) and all reduce-only by default.Stop Order
Triggers when the mark price moves against your position. Used for stop-loss protection.- Trigger direction: Below for longs, above for shorts
- On trigger: Submits a reduce-only market order (if no limit price set) or a reduce-only GTC limit order at the specified limit price
- Reduce-only: Always. Cannot open new positions.
Take-Profit Order
Triggers when the mark price moves in favor of your position. Used to lock in gains.- Trigger direction: Above for longs, below for shorts
- On trigger: Same as Stop, either market or limit depending on whether a limit price is specified
Range Order
A two-leg conditional that places both a stop and a take-profit simultaneously with a single action. Internally creates two linked orders (OCO).- Lower trigger: Stop-loss level with optional limit price
- Upper trigger: Take-profit level with optional limit price
- When one leg triggers, the other is automatically cancelled (One-Cancels-Other)
Trigger Order
A general-purpose conditional that holds a set of arbitrary actions. When the mark price crosses the trigger threshold, all embedded actions are submitted to the executor.- Trigger direction:
Above(fires when price is at or above threshold) orBelow(fires when price is at or below threshold) - Actions: Any valid action list (limit orders, cancels, etc.)
- More flexible than Stop/TP since it is not restricted to reduce-only or a single instrument
Trailing Stop
A stop order that follows the market price. As the market moves in your favor, the stop level adjusts automatically. When the market reverses by the specified trail amount, the stop triggers.- trail_bps: Distance in basis points from the current price
- step_bps: Minimum price movement before the trail resets
- Internally implemented as a Stop order with a companion Trigger sentinel that resets the stop level on each step
On-Fill Orders
Conditional orders that attach to a parent order and activate only when the parent fills. Used to place Stop/TP orders that are linked to a specific entry.- Before parent fills: The On-Fill children are dormant, not on the conditional book
- Parent fully fills: All On-Fill children are activated and placed on the conditional book
- Parent cancelled before fill: Children are cancelled too
- Parent partially fills then cancelled by margin: Children are placed for the filled size
- Up to 32 On-Fill rounds per tick can fire (batched processing)
Conditional Book
All conditional orders live on a separate trigger book, not the main order book. The trigger book maintains two sorted maps:- Above book: Orders that fire when price reaches or exceeds the threshold
- Below book: Orders that fire when price reaches or falls below the threshold
Parameters
| Field | Description |
|---|---|
trigger_price | Price at which the order activates |
limit_price | Optional. If set, places a limit order on trigger. If zero/unset, places a market order. |
is_above | Trigger direction. true for above-threshold trigger, false for below-threshold trigger |
oco_order_id | Optional linked order ID for One-Cancels-Other behavior |
trail_bps | For trailing stops: trail distance in basis points |
step_bps | For trailing stops: minimum step size before trail resets |
Example: Limit Entry with TP/SL
Place a limit buy with attached take-profit and stop-loss using On-Fill:- Submit a limit buy for 1 BTC at 95,000
- Attach an On-Fill take-profit at trigger 105,000 (market)
- Attach an On-Fill stop-loss at trigger 90,000 with limit 89,500