Struct ConditionalBuilder 

pub struct ConditionalBuilder { /* private fields */ }

Builder for constructing Conditional orders with a fluent API.

This builder provides a type-safe way to construct conditional orders with proper validation of required fields and configuration constraints. It supports:

• Price-based triggers (rises above/falls below)
• Order-linked activation (bracket orders)
• Flexible quantity specifications
• Optional expiry configuration

It will also build a trailing-stop trigger or an OCO link, but the sequencer rejects both (125 and 129) — see Trigger and Conditional.

Required Fields

The following fields must be set before calling build():

• Trigger condition: rises_above() or falls_below()
• Trigger: Price level or trailing configuration
• Reference price: last_trade_price(), index_price(), or mark_price()

Examples

Basic stop-loss order:

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

let conditional = ConditionalBuilder::new()
    .falls_below()
    .trigger(Trigger::price("45000.00"))
    .last_trade_price()
    .build()
    .unwrap();

Stop with order-linked activation:

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

let conditional = ConditionalBuilder::new()
    .falls_below()
    .trigger(Trigger::price("45000.00"))
    .mark_price()
    .order_linked_activation_client_id("entry-order-123", "1.0")
    .absolute_quantity("1.0")
    .build()
    .unwrap();

Take-profit on half the position:

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

let take_profit = ConditionalBuilder::new()
    .rises_above()
    .trigger(Trigger::price("55000.00"))
    .last_trade_price()
    .percentage_of_position_at_trigger("0.5")
    .build()
    .unwrap();

Implementations

impl ConditionalBuilder

pub fn new() -> ConditionalBuilder

Creates a new ConditionalBuilder with all fields unset.

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new();

pub fn trigger_condition( self, condition: TriggerCondition, ) -> ConditionalBuilder

Sets the trigger condition directly.

Tip: Consider using rises_above() or falls_below() for better readability.

Arguments

• condition - The trigger condition to use

Example

use types::api::submit_order::ConditionalBuilder;
use types::common::TriggerCondition;

let builder = ConditionalBuilder::new()
    .trigger_condition(TriggerCondition::RisesAbove);

pub fn rises_above(self) -> ConditionalBuilder

Sets trigger condition to RisesAbove (for breakout/take-profit orders).

The order will trigger when the reference price rises above the trigger level.

Required field - Must be set before calling build().

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .rises_above();  // Trigger when price rises above target

pub fn falls_below(self) -> ConditionalBuilder

Sets trigger condition to FallsBelow (for stop-loss orders).

The order will trigger when the reference price falls below the trigger level.

Required field - Must be set before calling build().

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .falls_below();  // Trigger when price falls below stop level

pub fn trigger(self, trigger: Trigger) -> ConditionalBuilder

Sets the trigger mechanism (price or trailing stop).

Required field - Must be set before calling build().

Arguments

• trigger - Either a fixed price level or trailing stop configuration

Example

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

// Fixed price trigger
let builder = ConditionalBuilder::new()
    .trigger(Trigger::price("50000.00"));

// Trailing stop trigger
let builder = ConditionalBuilder::new()
    .trigger(Trigger::numeric_trailing_distance("500.00"));

pub fn reference_price( self, reference_price: ReferencePrice, ) -> ConditionalBuilder

Sets the reference price source directly.

Tip: Consider using last_trade_price(), index_price(), or mark_price() for better readability.

Required field - Must be set before calling build().

pub fn last_trade_price(self) -> ConditionalBuilder

Sets reference price to last trade price.

Uses the most recent executed trade price to evaluate the trigger condition.

Required field - Must be set before calling build().

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .last_trade_price();

pub fn index_price(self) -> ConditionalBuilder

Sets reference price to index price.

Uses the external index price to evaluate the trigger condition.

Required field - Must be set before calling build().

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .index_price();

pub fn mark_price(self) -> ConditionalBuilder

Sets reference price to mark price.

Uses the fair value mark price to evaluate the trigger condition.

Required field - Must be set before calling build().

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .mark_price();

pub fn expiry(self, expiry: ConditionalExpiry) -> ConditionalBuilder

Sets an optional expiry configuration.

When the expiry timestamp is reached, the conditional order will either trigger or cancel based on the expiry settings.

Arguments

• expiry - Expiry configuration with timestamp and action

Example

use types::api::submit_order::{ConditionalBuilder, ConditionalExpiry};

let builder = ConditionalBuilder::new()
    .expiry(ConditionalExpiry::trigger_at(1747313713));

pub fn quantity(self, quantity: Quantity) -> ConditionalBuilder

Sets the order quantity directly.

Tip: Consider using specific methods like absolute_quantity() or percentage_of_position_at_trigger().

pub fn absolute_quantity<S>(self, quantity: S) -> ConditionalBuilder

where S: Into<String>,

Sets an absolute quantity for the order.

Arguments

• quantity - Absolute quantity as a decimal string (e.g., “1.5”, “0.001”)

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .absolute_quantity("1.5");

pub fn percentage_of_position_at_trigger<S>( self, percentage: S, ) -> ConditionalBuilder

where S: Into<String>,

Sets quantity as a percentage of position at trigger time.

The quantity will be calculated based on the position size when the conditional order triggers (not when it’s submitted).

Arguments

• percentage - a fraction of the position in (0,1], as a decimal string ("0.5" is 50%). Anything zero, negative or greater than 1 is rejected with OrderPercentageOfPositionQuantityMustBeGreaterThanZeroAndLesserThanOne (139).

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .percentage_of_position_at_trigger("0.5");  // 50% of position

pub fn percentage_of_position_at_submission<S>( self, percentage: S, ) -> ConditionalBuilder

where S: Into<String>,

Sets quantity as a percentage of position at submission time.

The quantity will be calculated and locked based on the position size when the conditional order is submitted (not when it triggers).

Arguments

• percentage - Percentage as a decimal string (e.g., “50” for 50%)

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .percentage_of_position_at_submission("0.5");  // 50% of current position

pub fn order_link_quantity(self) -> ConditionalBuilder

Sets quantity to match the linked order’s full quantity.

Not supported. The sequencer rejects any conditional carrying this quantity with OrderLinkQuantityNotSupported (133), whether or not order linking is configured. Use absolute_quantity() or a percentage-of-position quantity.

Requires: Order linking must be configured via order_linked_activation_client_id() or order_linked_activation_order_id().

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .order_linked_activation_client_id("entry-order-123", "1.0")
    .order_link_quantity();  // Match the linked order's quantity

pub fn filled_order_link_quantity(self) -> ConditionalBuilder

Sets quantity to match the linked order’s filled quantity.

Not supported. The sequencer rejects any conditional carrying this quantity with OrderLinkQuantityNotSupported (133).

Requires: Order linking must be configured via order_linked_activation_client_id() or order_linked_activation_order_id().

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .order_linked_activation_client_id("entry-order-123", "1.0")
    .filled_order_link_quantity();  // Match filled portion only

pub fn order_linked_activation_client_id<S>( self, client_order_id: S, fill_quantity: S, ) -> ConditionalBuilder

where S: Into<String>,

Links this conditional order to activate when another order is filled.

This creates a bracket order relationship where this conditional order activates after the specified parent order reaches a fill threshold.

Note: Cannot be used with order_linked_activation_order_id().

Arguments

• client_order_id - Client-assigned ID of the parent order
• fill_quantity - Minimum fill quantity to activate (decimal string)

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .order_linked_activation_client_id("entry-order-123", "1.0");

pub fn order_linked_activation_order_id<S>( self, order_id: u128, fill_quantity: S, ) -> ConditionalBuilder

where S: Into<String>,

Links this conditional order to activate when another order is filled (by order ID).

This creates a bracket order relationship where this conditional order activates after the specified parent order reaches a fill threshold.

Note: Cannot be used with order_linked_activation_client_id().

Arguments

• order_id - Exchange-assigned ID of the parent order
• fill_quantity - Minimum fill quantity to activate (decimal string)

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .order_linked_activation_order_id(123456789, "1.0");

pub fn oco_link_client_id<S>(self, client_order_id: S) -> ConditionalBuilder

where S: Into<String>,

Links this order with another in an OCO (One-Cancels-Other) relationship.

Not supported. A conditional carrying an OCO link is rejected by the sequencer with OcoOrdersNotSupported (129); nothing cancels the other leg. Submit the two legs independently and cancel the loser yourself.

Note: Cannot be used with oco_link_order_id().

Arguments

• client_order_id - Client-assigned ID of the linked OCO order

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .oco_link_client_id("stop-loss-order-456");

pub fn oco_link_order_id(self, order_id: u128) -> ConditionalBuilder

Links this order with another in an OCO relationship (by order ID).

Not supported. A conditional carrying an OCO link is rejected by the sequencer with OcoOrdersNotSupported (129).

Note: Cannot be used with oco_link_client_id().

Arguments

• order_id - Exchange-assigned ID of the linked OCO order

Example

use types::api::submit_order::ConditionalBuilder;

let builder = ConditionalBuilder::new()
    .oco_link_order_id(987654321);

pub fn build(self) -> Result<Conditional, ConditionalBuilderError>

Builds the Conditional order, consuming the builder.

Returns

• Ok(Conditional) - Successfully built conditional order
• Err(ConditionalBuilderError) - Missing required fields or invalid configuration

Errors

Returns an error if:

• Any required field is missing (trigger_condition, trigger, reference_price)
• Order linking is used without fill quantity
• Both OCO client ID and order ID are specified
• Both activation client ID and order ID are specified

Example

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

let conditional = ConditionalBuilder::new()
    .falls_below()
    .trigger(Trigger::price("45000.00"))
    .last_trade_price()
    .build()
    .expect("Failed to build conditional");

Trait Implementations

impl Debug for ConditionalBuilder

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

Formats the value using the given formatter.

impl Default for ConditionalBuilder

fn default() -> ConditionalBuilder

Returns the “default value” for a type.