RFC: Bracket Orders (OCO + OTO over STOP_LIMIT / TAKE_PROFIT_LIMIT)

Date: 2026-07-20 Status: Draft — for review Author: (you) Related: Stop-Loss / Take-Profit orders (docs/rfc/stop-loss-take-profit.md), Post-only reprice (A-4076), Order-chain lifecycle (docs/rfc/order-chain-lifecycle.md)

TL;DR. Build bracket orders on top of the conditional-order machine from the Stop-Loss / Take-Profit RFC. A bracket is an entry order plus an attached take-profit (TAKE_PROFIT_LIMIT) and stop-loss (STOP_LIMIT) pair that protect the resulting position. Two new primitives compose it: OCO (one-cancels-other — TP and SL are linked; a fill/cancel of one cancels the other) and OTO (one-triggers-other — the protective pair stays dormant until the entry fills, then arms sized to the actual fill). No new order types, no new trigger engine — this RFC adds a link group abstraction, quantity synchronization, and the group lifecycle. Wire changes are the link_id / link_kind fields the base RFC left as forward-compat open question #5.

Background

The base RFC (Stop-Loss / Take-Profit) explicitly lists OCO / bracket orders as a non-goal, but was written to not preclude them:

Its wire open question #5 asks whether a link_id should be added now "(cheap) so brackets don't need a later wire break."
Its state model already carries Untriggered conditionals with a durable store, idempotent single-fire, restart reload, and reject-at-trigger observability — the exact primitives a bracket's protective legs need.
STOP_LIMIT and TAKE_PROFIT_LIMIT already fire in opposite trigger directions for the same side, which is precisely the TP/SL pairing a bracket wants around a position.

What is still missing for brackets is coordination between orders:

No linkage. Each order today is independent. Nothing expresses "these two conditionals belong together" or "cancel that one when this one fills."
No conditional entry → protection handoff. A bracket's protective legs must not rest on the book (or in the trigger engine) until the entry actually establishes a position, and they must be sized to the fill, not the requested quantity, because the entry may partially fill.
No group-level lifecycle or cancel semantics. Cancel-one-cancels-all, partial-fill quantity propagation, and restart reload of a half-executed bracket have no representation in the base state model.

This RFC adds exactly those three things and nothing else.

Goals

Bracket order: one entry (Limit or Market) + an attached TAKE_PROFIT_LIMIT and STOP_LIMIT protecting the filled position.
OCO primitive: a link group in which the fill (or cancel) of one member automatically cancels the sibling(s).
OTO primitive: child orders that stay dormant (Suspended) until a parent fills, then arm — for a bracket, TP+SL arm on entry fill, sized to the cumulative filled quantity.
Partial-fill correctness: protective legs track the actual position as the entry fills in pieces; over-cancel / over-fill of the protection is impossible.
Reuse everything: same two order types, same AX-side trigger engine, same durable store, same margin path. Brackets are orchestration, not new execution.
Additive, back-compat wire — a client that never sends link_id is unaffected; the base RFC's single-conditional flow is a bracket group of size 1.

Non-Goals

New conditional order types. Reuses STOP_LIMIT / TAKE_PROFIT_LIMIT from the base RFC. No trailing, no stop-market (those remain the base RFC's future work; a bracket inherits them for free once they land).
Arbitrary DAGs of links. v1 supports two link shapes only — a flat OCO set and a one-parent → OCO-child-set OTO (i.e. the bracket). No multi-level trees, no cross-account or cross-symbol groups.
Server-side bracket templating / strategy orders (e.g. scale-in ladders). The client sends the concrete legs; AX coordinates them.
Netting brackets against pre-existing positions. A bracket protects the position its own entry creates; it does not attach to or reconcile with a position already on the book. (Open question.)

Design

The two primitives

Everything decomposes into two link relationships. A bracket is their composition.

Primitive	Meaning	Members
OCO (one-cancels-other)	Sibling set; any member reaching a terminal fill or cancel cancels the rest	the TP leg + the SL leg
OTO (one-triggers-other)	Parent → child set; children are `Suspended` until parent fills, then armed	entry (parent) → {TP, SL} (OCO child set)

        bracket = OTO( entry → OCO( take_profit, stop_loss ) )

   entry fills ──────────► arm TP & SL, each sized to entry.filled_qty
   TP fills  ──► cancel SL  (OCO)
   SL fires+fills ──► cancel TP  (OCO)

The base RFC's lone conditional is the degenerate case: an OCO/OTO group of one member, link_id = None.

Wire changes (SDK, additive)

Realizes base-RFC open question #5. PlaceOrderRequest (rs/sdk/src/protocol/order_gateway.rs:162) gains two optional fields on top of the base RFC's order_type / trigger_price / trigger_method:

/// Link group id. Orders sharing a link_id are coordinated as a group.
/// Absent ⇒ standalone order (base-RFC behavior, size-1 group).
#[serde(rename = "lid", skip_serializing_if = "Option::is_none")]
pub link_id: Option<LinkId>,
/// This order's role within its link group. Absent ⇒ Standalone.
#[serde(rename = "lk", default)]
pub link_kind: LinkKind,          // Standalone | OcoMember | OtoParent | OtoChild

/// Role of an order inside a link group.
pub enum LinkKind {
    Standalone,
    /// Member of an OCO set: a terminal fill/cancel cancels its siblings.
    OcoMember,
    /// Parent of an OTO relationship: on fill, arms its suspended children.
    OtoParent,
    /// Child of an OTO relationship: Suspended until the parent fills.
    OtoChild,
}

Client-assigned link_id, single request. A bracket is placed as one PlaceBracketRequest carrying the entry plus the two protective legs, so the group is atomic on the wire and partially-accepted brackets can't exist:

pub struct PlaceBracketRequest {
    pub entry: PlaceOrderRequest,            // link_kind = OtoParent
    pub take_profit: PlaceOrderRequest,      // link_kind = OtoChild + OcoMember
    pub stop_loss: PlaceOrderRequest,        // link_kind = OtoChild + OcoMember
    // link_id defaulted/overwritten server-side; all three share it.
}

The generic link_id / link_kind on PlaceOrderRequest remain available for a bare OCO pair (two resting orders, no entry) without a bracket wrapper, but the bracket wrapper is the blessed path so validation lives in one place.

Downstream additive changes (all extend, don't break, the base RFC's model):

OrderState (rs/sdk/src/types/trading.rs:362): add Suspended ("SUSPENDED") — an OTO child accepted and durable but not yet armed (not even evaluating its trigger). Distinct from the base RFC's Untriggered, which means armed and watching its trigger. Bracket child lifecycle is Suspended → Untriggered → (Triggered → …) for the SL/TP legs.
Order / OrderDetails: add link_id, link_kind.
OrderGatewayEvent: add Armed (suspended → untriggered/working, i.e. the OTO handoff fired) and LinkedCancel (this order was canceled because a sibling terminated, carrying the sibling's id) so a client can distinguish an OCO auto-cancel from a user cancel.
OrderRejectReason (rs/sdk/src/types/trading.rs:517): add InvalidBracket (legs inconsistent — see validation) and LinkGroupNotFound (a link_id referencing an unknown/closed group).

Bracket validation (at placement)

The entry side determines the mandatory geometry of the protective legs. For a Buy entry (opening/adding a long), both protective legs are Sell and:

stop_loss.trigger  <  entry.reference  <  take_profit.trigger

For a Sell entry (short), both legs are Buy and the inequalities flip. Reject with InvalidBracket if: leg sides don't oppose the entry; a protective trigger is on the wrong side of the entry reference; TP and SL sit on the same side of the reference; or leg quantities don't match the entry quantity (they are sized from the fill, so the request-time quantity must equal the entry quantity — see below). This is a pure, synchronous check; no book state needed.

OTO arming and fill-sized protection (the crux)

The protective legs must protect the position that actually gets established, which the entry may build up in partial fills. Rule:

Entry rests / works normally (Untriggered never applies to the entry; it's a plain Limit/Market). TP and SL sit in Suspended in the durable store — not subscribed to the trigger feed, consuming no evaluation work.
On each entry fill event (partial or full), the engine arms/updates both children to the entry's cumulative filled quantity (Order.filled_quantity). First fill: Suspended → Untriggered at that qty. Subsequent fills: amend the armed legs' quantity upward to the new cumulative fill (a quantity replace on a resting conditional — no re-trigger).
On entry terminal with zero fill (fully canceled / rejected / expired): the suspended children are canceled (LinkedCancel) — nothing to protect.
On entry terminal after partial fill (e.g. DoneForDay with 3 of 10 filled): children are armed/left at the filled 3, not the requested 10. The unfilled remainder simply never existed as a position.

This makes the protection exactly position-sized at all times and removes the classic bracket bug where a partially-filled entry leaves an over-sized stop that, when it fires, flips you net short instead of flat.

OCO cancel semantics

The TP and SL legs form an OCO set. The first of them to reach a terminal fill or a user cancel causes the engine to cancel the sibling with LinkedCancel. Concretely, when the SL fires and its follow-on limit fills (fully or partially closing the position), the TP is canceled; symmetrically for TP. Two correctness hazards, handled explicitly:

Simultaneous fire / race. Both legs could satisfy their predicates on the same tick (a violent gap that is both past the stop and — briefly — past the TP, or fills arriving concurrently). The link group holds a single atomic resolving flag (per the base RFC's untriggered→triggering flip, lifted to the group): the first leg to win the flip proceeds; the loser is canceled. At most one protective leg ever reaches the book per unit of position.
Partial protective fill. If the SL's follow-on limit only partially fills (gap-through, thin book), the position is only partly closed. The OCO does not cancel the TP outright; instead the TP's quantity is reduced to the still-open position and it keeps resting. Full close of either leg cancels the sibling. (Quantity sync is the same amend primitive as OTO arming, run in the closing direction.)

Where this lives

Same home as the base RFC: a resident coordinator in order-gateway (and its btnl-order-gateway twin), extending the base RFC's trigger task rather than a new service. The link group is state the gateway already is the natural owner of — it sees entry fills (session order state), owns the trigger engine that arms children, and holds the authorized submit path for follow-on orders. No second service, no new auth hop, consistent with base-RFC decision #3.

Durable store

Extends the base RFC's conditional_orders durable store with group linkage. Leaning Postgres (base-RFC open question) — a new link_groups row plus a link_id / link_kind / link_role_state column set on the conditional/order rows. What must survive restart mid-bracket:

A half-executed bracket (entry filled 4 of 10, TP+SL armed at 4, one more entry fill in flight) reloads with children re-armed to the persisted cumulative fill, then the engine re-derives current fill from session state on reload and reconciles (a fill that landed during downtime bumps the armed qty).
A group whose entry terminated while down: children reconciled to canceled or armed-at-partial per the rules above on reload.
The OCO resolving flag is persisted so a crash between "SL filled" and "cancel TP" replays the cancel idempotently rather than leaving an orphan TP.

Lifecycle & correctness

Per the repo rule for anything tied to session state / order lifecycle / risk controls, these paths are in-scope for tests before rollout (superset of the base RFC's list, adding the group-coordination cases):

Restart/crash mid-bracket at each stage: entry unfilled, entry partially filled + children armed, one protective leg fired but follow-on not yet acked, OCO cancel of sibling in flight. Each reloads to a consistent group state and re-reconciles against session order state.
Idempotent group transitions. Arming, quantity amends, and OCO cancels each fire at most once via the persisted per-group resolving / armed flags — a double tick or a replayed reload cannot double-arm, double-cancel, or double-size.
Partial fills everywhere: partial entry fill → child qty tracks up; partial protective fill → sibling qty tracks down; entry partial then canceled remainder → children sized to the partial. No path leaves protection mis-sized vs. the live position.
Client disconnect / COD. Follows base-RFC decision #7 (persist untriggered by default). A suspended OTO child likewise persists across disconnect; the whole group is one unit for COD purposes — COD (if opted in) cancels the entire bracket, never one leg, so you never disconnect into an unprotected fill or an orphaned stop.
Margin. Estimated at bracket placement across the group (base-RFC decision #5), not reserved while suspended/untriggered; each follow-on limit runs the normal margin check at trigger, reject-at-trigger observable. Because the protective legs are reduce-only against the entry's own position, the group's incremental margin over the entry alone is ~zero — validated, not assumed.
Reject-at-trigger of a protective leg is the one place a bracket can "fail to protect" (same as base RFC); surfaced as a rejected-order event plus a group-level warning so it's not lost among the group's other events.
Stale/gapped data & halts. Inherited unchanged from the base RFC — suspended children don't evaluate at all; armed children obey the base RFC's stale-feed and halt rules.

GUI

Bracket ticket: extend the order form with a bracket mode — entry price/qty/side plus a take-profit and stop-loss trigger input, with live validation of the SL < ref < TP geometry against the current mark.
Blotter: render the group as a parent row with two child rows, showing Suspended → Armed → Untriggered → filled/canceled transitions, and mark an OCO auto-cancel distinctly (LinkedCancel) from a user cancel.
Group cancel: a single "cancel bracket" action that cancels all live members as one unit.

Rollout

This RFC + SDK wire types (link_id, link_kind, LinkKind, OrderState::Suspended, Armed / LinkedCancel events, PlaceBracketRequest, new reject reasons) — additive, back-compat, no behavior yet. Depends on the base Stop-Loss / Take-Profit RFC shipping first (its order types + trigger engine + durable store are prerequisites).
OCO primitive in order-gateway: link group state, sibling-cancel on terminal, resolving flag, restart reload. Behind a flag. (Bare OCO pairs are testable before brackets exist.)
OTO + fill-sized arming: suspended children, arm-on-fill, cumulative-fill quantity amend, entry-terminal reconciliation.
Bracket wrapper + validation (PlaceBracketRequest, geometry checks) and group-level margin.
GUI: bracket ticket, grouped blotter rows, group cancel.
AIEx/Bitnomial edition: same coordinator in btnl-order-gateway.
(Future) attach-to-existing-position brackets; scale-in / multi-level groups; bracket over stop-market entries once the base RFC's market variants land.

Alternatives considered

Client-side bracket emulation (three independent orders, client watches fills). Rejected: the fill→arm and OCO-cancel loop over the network is racy and breaks entirely if the client disconnects — exactly when protection matters (mirrors base-RFC decision #7). Coordination must be server-side and durable.
Native venue OCO/bracket passthrough. Same rejection as the base RFC's native-stop analysis: EP3/BTP native bracket support is divergent/unconfirmed and take-profit direction has no clean native type; would yield two implementations. Kept as a future per-edition optimization once the AX-side engine is proven.
Reserve full margin for the protective legs while suspended. Rejected: the legs are reduce-only against the entry's own position, so reserving would double-count and strand capital; estimate-not-reserve (base decision #5) holds.
Size protective legs to the requested entry quantity, cancel overhang if the entry underfills. Rejected: leaves a window where an over-sized stop can flip the position net short/long on a fire before the overhang is trimmed. Fill-sized arming closes the window structurally.
A general link-DAG engine (arbitrary OCO/OTO trees). Rejected for v1 as over-built; the flat-OCO + single-parent-OTO shapes cover brackets and bare OCO with far less state and far fewer race surfaces.

Decisions

#	Decision	Rationale
1	Two primitives — OCO (sibling-cancel) + OTO (parent-arms-children); bracket = their composition	Minimal surface; brackets fall out of two reusable rules
2	Reuse base-RFC `STOP_LIMIT` / `TAKE_PROFIT_LIMIT` + trigger engine; no new execution	Brackets are orchestration, not a new order machine
3	Protective legs sized to cumulative entry fill, amended per fill	Protection always position-sized; kills the over-sized-stop flip bug
4	OTO children rest in new `Suspended` state, not evaluating triggers, until parent fills	No wasted engine/feed work; clear distinct state from `Untriggered`
5	Bracket placed as one atomic `PlaceBracketRequest`; server assigns shared `link_id`	No partially-accepted brackets; validation in one place
6	Coordinator lives in order-gateway (+ btnl twin), extends base trigger task	Owns fills + trigger engine + submit path; no new service/auth hop
7	Group is one unit for cancel & COD; never cancel a lone leg	Never disconnect into an unprotected fill or orphaned stop
8	Partial protective fill trims the sibling's qty, doesn't cancel it	Keeps protecting the still-open remainder
9	Per-group atomic `resolving`/`armed` flags, persisted	At-most-once arm/cancel/size across ticks and restarts
10	Wire additive; absent `link_id` ⇒ standalone (base-RFC behavior)	Zero-change back-compat; base RFC is a size-1 group

Open questions

Attach-to-existing-position brackets. v1 protects only the position its own entry creates. Do we need a bracket that attaches to a pre-existing position (no entry leg, TP+SL sized to current net)? Cheap-ish extension (OCO pair, qty from position feed) but pulls in position/netting reconciliation — defer or include?
OCO trim vs. cancel on partial protective fill (#8). Confirm with trading that a partially-filled stop should keep a trimmed take-profit resting rather than flattening the whole group.
Entry as Market. A market entry fills ~instantly, collapsing OTO to a near-synchronous arm. Any need to hold the market entry until marks are fresh (base-RFC stale-feed rule) before arming, or is immediate arming fine?
Group-level rate/quantity limits. A bracket is up to 3 orders + 2 durable conditionals per group. Does MaxOpenOrdersExceeded count the group as 1 or 3, and do suspended children count against open-order caps at all? (Extends base-RFC open question on conditional caps.)
Cross-symbol / cross-account linkage. Explicitly out of scope for v1 — confirm no near-term client demand before hard-coding the same-symbol/same-account invariant into the group model.
clord_id scheme for group members. Deterministic per-leg ids (base-RFC crash-dedup) must also encode group membership for reload — settle the id format (e.g. {link_id}.{leg}) so reload can reconstruct the group without a join.