Skip to main content

nautilus_trading/examples/strategies/orderbook_imbalance/
config.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Configuration for the order book imbalance strategy.
17
18use nautilus_core::datetime::secs_to_nanos;
19use nautilus_model::{
20    enums::{BookType, TimeInForce},
21    identifiers::{InstrumentId, StrategyId},
22    types::Quantity,
23};
24use rust_decimal::Decimal;
25
26use crate::strategy::StrategyConfig;
27
28/// Configuration for the current-book imbalance strategy.
29#[derive(Debug, Clone, bon::Builder)]
30#[cfg_attr(
31    feature = "python",
32    pyo3::pyclass(module = "nautilus_trader.trading", from_py_object)
33)]
34#[cfg_attr(
35    feature = "python",
36    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.trading")
37)]
38pub struct OrderBookImbalanceConfig {
39    /// Base strategy configuration.
40    #[builder(default = StrategyConfig {
41        strategy_id: Some(StrategyId::from("OrderBookImbalance-000")),
42        order_id_tag: Some("000".to_string()),
43        ..Default::default()
44    })]
45    pub base: StrategyConfig,
46    /// Instrument to subscribe to and trade.
47    pub instrument_id: InstrumentId,
48    /// Maximum order size, truncated to the instrument's size precision.
49    pub max_trade_size: Quantity,
50    /// The larger best size must exceed this threshold.
51    #[builder(default = Decimal::from(100))]
52    pub trigger_min_size: Decimal,
53    /// The smaller/larger best-size ratio must be below this threshold in (0, 1).
54    #[builder(default = Decimal::new(20, 2))]
55    pub trigger_imbalance_ratio: Decimal,
56    /// Minimum elapsed seconds between eligible signals.
57    #[builder(default = 1.0)]
58    pub min_seconds_between_triggers: f64,
59    /// Book representation used by the managed subscription.
60    #[builder(default = BookType::L2_MBP)]
61    pub book_type: BookType,
62    /// Immediate execution policy: FOK requires a full fill; IOC permits partial fills.
63    #[builder(default = TimeInForce::Fok)]
64    pub time_in_force: TimeInForce,
65    /// Snapshot logging interval in book updates, or zero to disable.
66    #[builder(default)]
67    pub log_interval: u64,
68    /// Reports signals without submitting, canceling, or closing orders, including on stop.
69    #[builder(default)]
70    pub dry_run: bool,
71}
72
73impl OrderBookImbalanceConfig {
74    pub(crate) fn validate(&self) -> anyhow::Result<()> {
75        anyhow::ensure!(
76            matches!(self.time_in_force, TimeInForce::Fok | TimeInForce::Ioc),
77            "time_in_force must be FOK or IOC"
78        );
79        anyhow::ensure!(
80            self.max_trade_size.is_positive(),
81            "max_trade_size must be positive"
82        );
83        anyhow::ensure!(
84            self.trigger_min_size >= Decimal::ZERO,
85            "trigger_min_size must be non-negative"
86        );
87        anyhow::ensure!(
88            self.trigger_imbalance_ratio > Decimal::ZERO
89                && self.trigger_imbalance_ratio < Decimal::ONE,
90            "trigger_imbalance_ratio must be in (0, 1)"
91        );
92        anyhow::ensure!(
93            self.min_seconds_between_triggers >= 0.0
94                && secs_to_nanos(self.min_seconds_between_triggers).is_ok(),
95            "min_seconds_between_triggers must be finite, non-negative, and representable in nanoseconds"
96        );
97        anyhow::ensure!(
98            !self.dry_run
99                || !(self.base.manage_stop
100                    || self.base.manage_gtd_expiry
101                    || self.base.manage_contingent_orders),
102            "dry_run requires manage_stop, manage_gtd_expiry, and manage_contingent_orders=false"
103        );
104        Ok(())
105    }
106}