Add contingent orders: OCO, OTO, OUO and brackets

[Martin-Molinero]

Description

Adds contingent orders: sets of independent orders whose lifecycle is related.

• One Cancels Other (OCO/OCA): the first fill of a member, even partial, cancels the rest.
• One Triggers Other (OTO): children are held until their parent, all its legs for a combo, completely fills. They're canceled if the parent is canceled or invalid.
• One Updates Other (OUO): a partial fill reduces the remaining quantity of the siblings proportionally.
• Any composition of them, like brackets (OTOCO). Combo orders can be members.

Algorithm API. Existing order methods are unchanged and go through the same submit path.

• OrderFactory (self.order_factory) creates SubmitOrderRequests. They're composed with Triggers, Bracket, OneCancelsOther and OneUpdatesOther, then submitted with Order(...).
• BracketOrder, OneCancelsOtherOrder, OneUpdatesOtherOrder and OneTriggersOtherOrder are helpers for the common shapes.

entry = self.order_factory.limit_order(spy, 100, 500)
entry.triggers(self.order_factory.one_cancels_other(
    self.order_factory.limit_order(spy, -100, 510),
    self.order_factory.stop_market_order(spy, -100, 495)))
tickets = self.order(entry)
# or
tickets = self.bracket_order(spy, 100, take_profit_price=510, stop_loss_price=495, limit_price=500)

Order model.

• Order.Contingency (OrderContingency) holds the set shared by its orders, with per-order links: contingency id, type, and role (parent, child, or none for siblings).
• OrderContingency owns the composition (Trigger/Relate). The brokerages also use it to rebuild the contingencies of their open orders.
• OrderContingency.IsWaitingForTrigger tells whether a child is still held.
• JSON serialization is backwards compatible.

Transaction handler.

• A set is submitted atomically once all its orders arrive.
• Held children skip the buying power check; they're validated when released. This matches the brokerages; see the live testing below.
• OCO/OUO siblings count once in GetOpenOrdersRemainingQuantity and in the cash buying power model.
• Brokerage updates for triggered or resized orders are applied. A fill of a held order also marks it triggered, as a safety net.

Backtesting.

• ContingentOrderProcessor drives the lifecycle: holding children, triggering on a complete fill, cancelling siblings, resizing OUO siblings and cascading cancels.
• A triggered order needs new data before it can fill.
• On same-bar ties the stop loss wins (pessimistic).
• A trailing stop child starts trailing when triggered.

Brokerage models.

• IB, Charles Schwab, TradeStation, Alpaca and Binance validate what each brokerage supports. The rest reject contingent orders.
• The base Brokerage exposes ContingentOrderCache and OnContingentOrdersTriggered for the plugins.

Related Issue

Brokerage plugin support, to be merged after this one:

• Add contingent orders support: attached orders and OCA groups Lean.Brokerages.InteractiveBrokers#265
• QuantConnect/Lean.Brokerages.CharlesSchwab#116
• Add contingent orders support: order groups and order sends order Lean.Brokerages.TradeStation#109
• Add contingent orders support: bracket, oco and oto order classes Lean.Brokerages.Alpaca#83
• Add contingent orders support: OCO, OTO and OTOCO order lists Lean.Brokerages.Binance#85

Motivation and Context

Brackets, OCO and OTO are standard order types the supported brokerages offer natively. Until now algorithms had to emulate them with order events, which isn't atomic and leaves naked positions when a fill and a cancel race.

Requires Documentation Change

Yes: the new order types and APIs (OrderFactory, Order, BracketOrder, OneCancelsOtherOrder, OneUpdatesOtherOrder, OneTriggersOtherOrder) and what each brokerage supports.

How Has This Been Tested?

• Unit tests:
  • AlgorithmOrderFactoryTests
  • ContingentOrdersTransactionHandlerTests, including the remaining open quantity aggregation
  • ContingentOrderTests, ContingentOrderProcessorTests
  • ContingentOrdersBrokerageModelTests
• Regression algorithms, C# and Python:
  • BracketOrder, BracketOrderLimitEntry
  • OneCancelsOtherOrder, OneCancelsOtherOrderCashAccount, OneTriggersOtherOrder, OneUpdatesOtherOrder
  • ContingentOrderCancel, ContingentOrderUpdate, ContingentComboOrder, ContingentTrailingStopOrder
• The full regression suite passes. The broad unit test sweep passes except LiveOptionChainProviderReturnsFutureOptionData, which also fails on master (CME endpoint error).
• Live end to end on an Interactive Brokers paper account:
  • brackets with the take profit or the stop loss filling
  • OTO with a cancelled parent
  • OCO/OUO exits
  • chains
  • updates of held and working orders
  • forex, futures and multi-symbol OCO
  • option combo OTO
  • held children beyond the account buying power, which IB accepts and holds

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• Refactor (non-breaking change which improves implementation)
• Performance (non-breaking change which improves performance. Please add associated performance test and results)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Non-functional change (xml comments/documentation/etc)

Checklist:

• My code follows the code style of this project.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.
• My branch follows the naming convention bug-<issue#>-<description> or feature-<issue#>-<description>

🤖 Generated with Claude Code