Struct Conditional 

pub struct Conditional {
    pub trigger_condition: TriggerCondition,
    pub trigger: Trigger,
    pub reference_price: ReferencePrice,
    pub expiry: Option<ConditionalExpiry>,
    pub quantity: Option<Quantity>,
    pub order_linked_activation_client_order_id: Option<String>,
    pub order_linked_activation_order_id: Option<u128>,
    pub order_linked_activation_fill_quantity: Option<String>,
    pub oco_order_link_client_order_id: Option<String>,
    pub oco_order_link_order_id: Option<u128>,
}

Comprehensive conditional order specification with advanced trading features.

This struct defines all parameters for sophisticated conditional orders, including trigger conditions, price references, expiration rules, quantity specifications, order linking, and OCO (One-Cancels-Other) relationships.

Core Components

Trigger System

• trigger_condition: When to activate (RisesAbove/FallsBelow)
• trigger: What price level or trailing mechanism to use
• reference_price: Which price feed to monitor (LastTrade/Index/Mark)

Advanced Features

• expiry: Optional time-based expiration with trigger/cancel actions
• quantity: Flexible quantity specification (absolute, percentage, or linked)
• Order linking for parent-child relationships
• OCO linking for mutually exclusive orders

Field Aliases

Most fields support compact aliases for efficient serialization:

• trigger_condition → "t"
• reference_price → "rp"
• order_linked_activation_client_order_id → "olcid"
• order_linked_activation_order_id → "oloid"
• order_linked_activation_fill_quantity → "olq"
• oco_order_link_client_order_id → "ococid"
• oco_order_link_order_id → "ocooid"

Order Linking

Parent-Child Activation

Links this conditional order to a parent order, activating when the parent reaches a specified fill threshold. Use either:

• order_linked_activation_client_order_id + order_linked_activation_fill_quantity
• order_linked_activation_order_id + order_linked_activation_fill_quantity

OCO (One-Cancels-Other) Relationships — not supported

oco_order_link_client_order_id and oco_order_link_order_id are reserved wire vocabulary. Setting either makes the sequencer reject the whole transaction with OcoOrdersNotSupported (129); nothing links the two legs.

Examples

Simple stop-loss order

use types::api::submit_order::{Conditional, Quantity, Trigger};
use types::common::{ReferencePrice, TriggerCondition};

// a conditional carries its own size; `quantity: None` is rejected with
// ConditionalOrderMustHaveQuantity (136)
let stop_loss = Conditional {
    trigger_condition: TriggerCondition::FallsBelow,
    trigger: Trigger::Price("45000.00".to_string()),
    reference_price: ReferencePrice::LastTrade,
    expiry: None,
    quantity: Some(Quantity::PercentageOfPositionAtTrigger("1.0".to_string())),
    order_linked_activation_client_order_id: None,
    order_linked_activation_order_id: None,
    order_linked_activation_fill_quantity: None,
    oco_order_link_client_order_id: None,
    oco_order_link_order_id: None,
};

Stop with an expiry that cancels it

use types::api::submit_order::{Conditional, Trigger, ConditionalExpiry};

let stop = Conditional::builder()
    .falls_below()
    .trigger(Trigger::price("45000.00"))
    .mark_price()
    .absolute_quantity("0.5")
    .expiry(ConditionalExpiry::cancel_at(1_800_000_000_000))
    .build()
    .expect("Failed to build conditional");

Parent-child order linking

use types::api::submit_order::{Conditional, Trigger};

let child_order = Conditional::builder()
    .falls_below()
    .trigger(Trigger::price("47000.00"))
    .index_price()
    .absolute_quantity("0.5")
    .order_linked_activation_client_id("parent-order-123", "0.5")
    .build()
    .expect("Failed to build conditional");

OCO bracket orders — not supported

oco_link_client_id / oco_link_order_id build a Conditional the sequencer always rejects (OcoOrdersNotSupported, 129). Submit the take-profit and the stop as two independent conditional orders.

JSON Examples

Basic stop-loss:

{
  "trigger_condition": "FallsBelow",
  "trigger_price": "45000.00",
  "reference_price": "LastTrade"
}

Stop with expiry, using aliases (e is epoch milliseconds):

{
  "t": "FallsBelow",
  "tp": "45000.00",
  "rp": "Mark",
  "e": 1800000000000,
  "et": false,
  "qppat": "0.25"
}

Order-linked activation (parent referenced by client order id):

{
  "trigger_condition": "RisesAbove",
  "trigger_price": "55000.00",
  "reference_price": "LastTrade",
  "quantity": "0.5",
  "order_linked_activation_client_order_id": "entry-001",
  "order_linked_activation_fill_quantity": "0.5"
}

Validation Rules

1. Trigger: trigger_condition, trigger and reference_price are all required; the trigger must be Price (a trailing distance is rejected, 125)
2. Quantity: required (136), and must be Absolute or a percentage in (0,1]; OrderLink / FilledOrderLink are rejected (133)
3. Expiry: if present, in the future and no later than MAX_EXPIRY_TIMESTAMP_MS (106 / 150)
4. Activation: exactly one of the two parent ids, plus a valid order_linked_activation_fill_quantity (145 / 146 / 147 / 148)
5. OCO: any OCO link is rejected (129)

Fields

trigger_condition: TriggerCondition

Specifies the direction of the price condition that will trigger this order.

This determines whether the order triggers when the reference price rises above or falls below the specified trigger level.

Values

• RisesAbove: Triggers when reference price goes above the trigger level
• FallsBelow: Triggers when reference price goes below the trigger level

Common Use Cases

• Stop-loss orders: FallsBelow to sell when price drops
• Buy-stop orders: RisesAbove to buy when price breaks resistance
• Take-profit orders: RisesAbove to sell when target price is reached

trigger: Trigger

The specific trigger mechanism (price level or trailing distance).

This field is flattened into the JSON structure, meaning its fields appear at the root level rather than nested. See the Trigger enum documentation for detailed information about each trigger type.

reference_price: ReferencePrice

The price feed to monitor for trigger evaluation.

Specifies which price (last trade, index, or mark) should be compared against the trigger condition to determine when to activate the order.

Selection Guidelines

• LastTrade: For traditional spot market orders
• Index: For manipulation-resistant triggers
• Mark: For margin and derivatives trading

expiry: Option<ConditionalExpiry>

Optional expiration specification for the conditional order.

If provided, this defines when the conditional order should expire and whether it should trigger or cancel on expiration. The fields are flattened into the JSON structure.

Behavior

• If None: Order persists until triggered or manually canceled
• If Some: Order will expire according to the expiry specification

quantity: Option<Quantity>

Optional custom quantity specification for the conditional order.

If provided, this overrides the default quantity behavior with advanced quantity calculation methods. The fields are flattened into the JSON structure.

Behavior

• If None: Uses the main order’s quantity specification
• If Some: Uses the conditional-specific quantity calculation

order_linked_activation_client_order_id: Option<String>

Client-defined order ID for parent order in order linking scenarios.

When specified, this conditional order will be linked to the parent order identified by this client order ID. The conditional order will activate when the parent order reaches the fill threshold specified in order_linked_activation_fill_quantity.

Constraints

• Cannot be used with order_linked_activation_order_id
• Requires order_linked_activation_fill_quantity to be specified
• The referenced order must exist and be valid

Use Cases

• Bracket orders where stop-loss activates after entry order fills
• Scaling strategies with multiple conditional orders per parent
• Risk management systems with automatic hedging

order_linked_activation_order_id: Option<u128>

System-assigned order ID for parent order in order linking scenarios.

Alternative to order_linked_activation_client_order_id for linking to a parent order using the system-assigned order ID instead of client ID.

Constraints

• Cannot be used with order_linked_activation_client_order_id
• Requires order_linked_activation_fill_quantity to be specified
• The referenced order must exist and be valid

order_linked_activation_fill_quantity: Option<String>

Minimum fill quantity threshold for parent order activation.

Specifies how much of the parent order must be filled before this conditional order becomes active. This allows for sophisticated parent-child order relationships with fine-grained control.

Required When

• Either order_linked_activation_client_order_id or order_linked_activation_order_id is specified

Format

• Must be a positive decimal string
• Should be less than or equal to parent order’s total quantity
• Precision should match market requirements

Examples

• "0.5": Activate when parent order has 0.5 units filled
• "100": Activate when parent order has 100 units filled
• "0.0001": Activate immediately on any parent order fill

oco_order_link_client_order_id: Option<String>

Client order ID for OCO (One-Cancels-Other) relationship.

When specified, this conditional order will be linked in an OCO relationship with the order identified by this client order ID. When either order executes, the other will be automatically canceled.

Constraints

• Cannot be used with oco_order_link_order_id
• The referenced order must exist
• Creates a bidirectional cancellation relationship

Use Cases

• Bracket orders with take-profit and stop-loss
• Either-or execution strategies
• Risk management with multiple exit strategies

oco_order_link_order_id: Option<u128>

System order ID for OCO (One-Cancels-Other) relationship.

Alternative to oco_order_link_client_order_id for creating OCO relationships using system-assigned order IDs instead of client order IDs.

Constraints

• Cannot be used with oco_order_link_client_order_id
• The referenced order must exist
• Creates a bidirectional cancellation relationship

Implementations

impl Conditional

pub fn builder() -> ConditionalBuilder

Create a new ConditionalBuilder

Trait Implementations

impl Clone for Conditional

fn clone(&self) -> Conditional

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Conditional

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Conditional

fn deserialize<__D>( __deserializer: __D, ) -> Result<Conditional, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Conditional

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.