nautilus_model/orders/
limit.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
16use std::{
17    fmt::Display,
18    ops::{Deref, DerefMut},
19};
20
21use indexmap::IndexMap;
22use nautilus_core::{
23    UUID4, UnixNanos,
24    correctness::{CorrectnessError, FAILED},
25};
26use rust_decimal::Decimal;
27use serde::{Deserialize, Serialize};
28use ustr::Ustr;
29
30use super::{Order, OrderAny, OrderCore, check_display_qty, check_time_in_force};
31use crate::{
32    enums::{
33        ContingencyType, LiquiditySide, OrderSide, OrderStatus, OrderType, PositionSide,
34        TimeInForce, TrailingOffsetType, TriggerType,
35    },
36    events::{OrderEventAny, OrderInitialized, OrderUpdated},
37    identifiers::{
38        AccountId, ClientOrderId, ExecAlgorithmId, InstrumentId, OrderListId, PositionId,
39        StrategyId, Symbol, TradeId, TraderId, Venue, VenueOrderId,
40    },
41    orders::OrderError,
42    types::{Currency, Money, Price, Quantity, quantity::check_positive_quantity},
43};
44
45#[derive(Clone, Debug, Serialize, Deserialize)]
46#[cfg_attr(
47    feature = "python",
48    pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.model", from_py_object)
49)]
50#[cfg_attr(
51    feature = "python",
52    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.model")
53)]
54pub struct LimitOrder {
55    core: OrderCore,
56    pub price: Price,
57    pub expire_time: Option<UnixNanos>,
58    pub is_post_only: bool,
59    pub display_qty: Option<Quantity>,
60    pub trigger_instrument_id: Option<InstrumentId>,
61}
62
63impl LimitOrder {
64    /// Creates a new [`LimitOrder`] instance.
65    ///
66    /// # Errors
67    ///
68    /// Returns an error if:
69    /// - The `quantity` is not positive.
70    /// - The `display_qty` (when provided) exceeds `quantity`.
71    /// - The `time_in_force` is GTD and the `expire_time` is `None` or zero.
72    #[expect(clippy::too_many_arguments)]
73    pub fn new_checked(
74        trader_id: TraderId,
75        strategy_id: StrategyId,
76        instrument_id: InstrumentId,
77        client_order_id: ClientOrderId,
78        order_side: OrderSide,
79        quantity: Quantity,
80        price: Price,
81        time_in_force: TimeInForce,
82        expire_time: Option<UnixNanos>,
83        post_only: bool,
84        reduce_only: bool,
85        quote_quantity: bool,
86        display_qty: Option<Quantity>,
87        emulation_trigger: Option<TriggerType>,
88        trigger_instrument_id: Option<InstrumentId>,
89        contingency_type: Option<ContingencyType>,
90        order_list_id: Option<OrderListId>,
91        linked_order_ids: Option<Vec<ClientOrderId>>,
92        parent_order_id: Option<ClientOrderId>,
93        exec_algorithm_id: Option<ExecAlgorithmId>,
94        exec_algorithm_params: Option<IndexMap<Ustr, Ustr>>,
95        exec_spawn_id: Option<ClientOrderId>,
96        tags: Option<Vec<Ustr>>,
97        init_id: UUID4,
98        ts_init: UnixNanos,
99    ) -> Result<Self, OrderError> {
100        check_positive_quantity(quantity, stringify!(quantity))?;
101        check_display_qty(display_qty, quantity)?;
102        check_time_in_force(time_in_force, expire_time)?;
103
104        let init_order = OrderInitialized::new(
105            trader_id,
106            strategy_id,
107            instrument_id,
108            client_order_id,
109            order_side,
110            OrderType::Limit,
111            quantity,
112            time_in_force,
113            post_only,
114            reduce_only,
115            quote_quantity,
116            false,
117            init_id,
118            ts_init, // ts_event timestamp identical to ts_init
119            ts_init,
120            Some(price),
121            None,
122            None,
123            None,
124            None,
125            None,
126            expire_time,
127            display_qty,
128            emulation_trigger,
129            trigger_instrument_id,
130            contingency_type,
131            order_list_id,
132            linked_order_ids,
133            parent_order_id,
134            exec_algorithm_id,
135            exec_algorithm_params,
136            exec_spawn_id,
137            tags,
138        );
139
140        Ok(Self {
141            core: OrderCore::new(init_order),
142            price,
143            expire_time,
144            is_post_only: post_only,
145            display_qty,
146            trigger_instrument_id,
147        })
148    }
149
150    /// Creates a new [`LimitOrder`] instance.
151    ///
152    /// # Panics
153    ///
154    /// Panics if any order validation fails (see [`LimitOrder::new_checked`]).
155    #[expect(clippy::too_many_arguments)]
156    #[must_use]
157    pub fn new(
158        trader_id: TraderId,
159        strategy_id: StrategyId,
160        instrument_id: InstrumentId,
161        client_order_id: ClientOrderId,
162        order_side: OrderSide,
163        quantity: Quantity,
164        price: Price,
165        time_in_force: TimeInForce,
166        expire_time: Option<UnixNanos>,
167        post_only: bool,
168        reduce_only: bool,
169        quote_quantity: bool,
170        display_qty: Option<Quantity>,
171        emulation_trigger: Option<TriggerType>,
172        trigger_instrument_id: Option<InstrumentId>,
173        contingency_type: Option<ContingencyType>,
174        order_list_id: Option<OrderListId>,
175        linked_order_ids: Option<Vec<ClientOrderId>>,
176        parent_order_id: Option<ClientOrderId>,
177        exec_algorithm_id: Option<ExecAlgorithmId>,
178        exec_algorithm_params: Option<IndexMap<Ustr, Ustr>>,
179        exec_spawn_id: Option<ClientOrderId>,
180        tags: Option<Vec<Ustr>>,
181        init_id: UUID4,
182        ts_init: UnixNanos,
183    ) -> Self {
184        Self::new_checked(
185            trader_id,
186            strategy_id,
187            instrument_id,
188            client_order_id,
189            order_side,
190            quantity,
191            price,
192            time_in_force,
193            expire_time,
194            post_only,
195            reduce_only,
196            quote_quantity,
197            display_qty,
198            emulation_trigger,
199            trigger_instrument_id,
200            contingency_type,
201            order_list_id,
202            linked_order_ids,
203            parent_order_id,
204            exec_algorithm_id,
205            exec_algorithm_params,
206            exec_spawn_id,
207            tags,
208            init_id,
209            ts_init,
210        )
211        .unwrap_or_else(|e| panic!("{FAILED}: {e}"))
212    }
213}
214
215impl Deref for LimitOrder {
216    type Target = OrderCore;
217
218    fn deref(&self) -> &Self::Target {
219        &self.core
220    }
221}
222
223impl DerefMut for LimitOrder {
224    fn deref_mut(&mut self) -> &mut Self::Target {
225        &mut self.core
226    }
227}
228
229impl PartialEq for LimitOrder {
230    fn eq(&self, other: &Self) -> bool {
231        self.client_order_id == other.client_order_id
232    }
233}
234
235impl Order for LimitOrder {
236    fn into_any(self) -> OrderAny {
237        OrderAny::Limit(self)
238    }
239
240    fn status(&self) -> OrderStatus {
241        self.status
242    }
243
244    fn trader_id(&self) -> TraderId {
245        self.trader_id
246    }
247
248    fn strategy_id(&self) -> StrategyId {
249        self.strategy_id
250    }
251
252    fn instrument_id(&self) -> InstrumentId {
253        self.instrument_id
254    }
255
256    fn symbol(&self) -> Symbol {
257        self.instrument_id.symbol
258    }
259
260    fn venue(&self) -> Venue {
261        self.instrument_id.venue
262    }
263
264    fn client_order_id(&self) -> ClientOrderId {
265        self.client_order_id
266    }
267
268    fn venue_order_id(&self) -> Option<VenueOrderId> {
269        self.venue_order_id
270    }
271
272    fn position_id(&self) -> Option<PositionId> {
273        self.position_id
274    }
275
276    fn account_id(&self) -> Option<AccountId> {
277        self.account_id
278    }
279
280    fn last_trade_id(&self) -> Option<TradeId> {
281        self.last_trade_id
282    }
283
284    fn order_side(&self) -> OrderSide {
285        self.side
286    }
287
288    fn order_type(&self) -> OrderType {
289        self.order_type
290    }
291
292    fn quantity(&self) -> Quantity {
293        self.quantity
294    }
295
296    fn time_in_force(&self) -> TimeInForce {
297        self.time_in_force
298    }
299
300    fn expire_time(&self) -> Option<UnixNanos> {
301        self.expire_time
302    }
303
304    fn price(&self) -> Option<Price> {
305        Some(self.price)
306    }
307
308    fn trigger_price(&self) -> Option<Price> {
309        None
310    }
311
312    fn trigger_type(&self) -> Option<TriggerType> {
313        None
314    }
315
316    fn liquidity_side(&self) -> Option<LiquiditySide> {
317        self.liquidity_side
318    }
319
320    fn is_post_only(&self) -> bool {
321        self.is_post_only
322    }
323
324    fn is_reduce_only(&self) -> bool {
325        self.is_reduce_only
326    }
327
328    fn is_quote_quantity(&self) -> bool {
329        self.is_quote_quantity
330    }
331
332    fn has_price(&self) -> bool {
333        true
334    }
335
336    fn display_qty(&self) -> Option<Quantity> {
337        self.display_qty
338    }
339
340    fn limit_offset(&self) -> Option<Decimal> {
341        None
342    }
343
344    fn trailing_offset(&self) -> Option<Decimal> {
345        None
346    }
347
348    fn trailing_offset_type(&self) -> Option<TrailingOffsetType> {
349        None
350    }
351
352    fn emulation_trigger(&self) -> Option<TriggerType> {
353        self.emulation_trigger
354    }
355
356    fn trigger_instrument_id(&self) -> Option<InstrumentId> {
357        self.trigger_instrument_id
358    }
359
360    fn contingency_type(&self) -> Option<ContingencyType> {
361        self.contingency_type
362    }
363
364    fn order_list_id(&self) -> Option<OrderListId> {
365        self.order_list_id
366    }
367
368    fn linked_order_ids(&self) -> Option<&[ClientOrderId]> {
369        self.linked_order_ids.as_deref()
370    }
371
372    fn parent_order_id(&self) -> Option<ClientOrderId> {
373        self.parent_order_id
374    }
375
376    fn exec_algorithm_id(&self) -> Option<ExecAlgorithmId> {
377        self.exec_algorithm_id
378    }
379
380    fn exec_algorithm_params(&self) -> Option<&IndexMap<Ustr, Ustr>> {
381        self.exec_algorithm_params.as_ref()
382    }
383
384    fn exec_spawn_id(&self) -> Option<ClientOrderId> {
385        self.exec_spawn_id
386    }
387
388    fn tags(&self) -> Option<&[Ustr]> {
389        self.tags.as_deref()
390    }
391
392    fn filled_qty(&self) -> Quantity {
393        self.filled_qty
394    }
395
396    fn leaves_qty(&self) -> Quantity {
397        self.leaves_qty
398    }
399
400    fn overfill_qty(&self) -> Quantity {
401        self.overfill_qty
402    }
403
404    fn avg_px(&self) -> Option<f64> {
405        self.avg_px
406    }
407
408    fn slippage(&self) -> Option<f64> {
409        self.slippage
410    }
411
412    fn init_id(&self) -> UUID4 {
413        self.init_id
414    }
415
416    fn ts_init(&self) -> UnixNanos {
417        self.ts_init
418    }
419
420    fn ts_submitted(&self) -> Option<UnixNanos> {
421        self.ts_submitted
422    }
423
424    fn ts_accepted(&self) -> Option<UnixNanos> {
425        self.ts_accepted
426    }
427
428    fn ts_closed(&self) -> Option<UnixNanos> {
429        self.ts_closed
430    }
431
432    fn ts_last(&self) -> UnixNanos {
433        self.ts_last
434    }
435
436    fn events(&self) -> Vec<&OrderEventAny> {
437        self.events.iter().collect()
438    }
439
440    fn venue_order_ids(&self) -> Vec<&VenueOrderId> {
441        self.venue_order_ids.iter().collect()
442    }
443
444    fn trade_ids(&self) -> Vec<&TradeId> {
445        self.trade_ids.iter().collect()
446    }
447
448    fn commissions(&self) -> &IndexMap<Currency, Money> {
449        &self.commissions
450    }
451
452    fn apply(&mut self, event: OrderEventAny) -> Result<(), OrderError> {
453        let is_order_filled = matches!(event, OrderEventAny::Filled(_));
454
455        self.core.apply(event.clone())?;
456
457        if let OrderEventAny::Updated(ref event) = event {
458            self.update(event);
459        }
460
461        if is_order_filled {
462            self.core.set_slippage(self.price);
463        }
464
465        Ok(())
466    }
467
468    fn update(&mut self, event: &OrderUpdated) {
469        assert!(
470            event.trigger_price.is_none(),
471            "{}",
472            OrderError::InvalidOrderEvent
473        );
474
475        if let Some(price) = event.price {
476            self.price = price;
477        }
478
479        self.quantity = event.quantity;
480        self.leaves_qty = self.quantity.saturating_sub(self.filled_qty);
481    }
482
483    fn is_triggered(&self) -> Option<bool> {
484        None
485    }
486
487    fn set_position_id(&mut self, position_id: Option<PositionId>) {
488        self.position_id = position_id;
489    }
490
491    fn set_quantity(&mut self, quantity: Quantity) {
492        self.quantity = quantity;
493    }
494
495    fn set_leaves_qty(&mut self, leaves_qty: Quantity) {
496        self.leaves_qty = leaves_qty;
497    }
498
499    fn set_emulation_trigger(&mut self, emulation_trigger: Option<TriggerType>) {
500        self.emulation_trigger = emulation_trigger;
501    }
502
503    fn set_is_quote_quantity(&mut self, is_quote_quantity: bool) {
504        self.is_quote_quantity = is_quote_quantity;
505    }
506
507    fn set_liquidity_side(&mut self, liquidity_side: LiquiditySide) {
508        self.liquidity_side = Some(liquidity_side);
509    }
510
511    fn would_reduce_only(&self, side: PositionSide, position_qty: Quantity) -> bool {
512        self.core.would_reduce_only(side, position_qty)
513    }
514
515    fn previous_status(&self) -> Option<OrderStatus> {
516        self.core.previous_status
517    }
518}
519
520impl Display for LimitOrder {
521    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
522        write!(
523            f,
524            "LimitOrder(\
525            {} {} {} {} @ {} {}, \
526            status={}, \
527            client_order_id={}, \
528            venue_order_id={}, \
529            position_id={}, \
530            exec_algorithm_id={}, \
531            exec_spawn_id={}, \
532            tags={:?}\
533            )",
534            self.side,
535            self.quantity.to_formatted_string(),
536            self.instrument_id,
537            self.order_type,
538            self.price,
539            self.time_in_force,
540            self.status,
541            self.client_order_id,
542            self.venue_order_id.map_or_else(
543                || "None".to_string(),
544                |venue_order_id| format!("{venue_order_id}")
545            ),
546            self.position_id.map_or_else(
547                || "None".to_string(),
548                |position_id| format!("{position_id}")
549            ),
550            self.exec_algorithm_id
551                .map_or_else(|| "None".to_string(), |id| format!("{id}")),
552            self.exec_spawn_id
553                .map_or_else(|| "None".to_string(), |id| format!("{id}")),
554            self.tags
555        )
556    }
557}
558
559impl TryFrom<OrderInitialized> for LimitOrder {
560    type Error = OrderError;
561
562    fn try_from(event: OrderInitialized) -> Result<Self, Self::Error> {
563        let price = event
564            .price
565            .ok_or_else(|| CorrectnessError::PredicateViolation {
566                message: "`price` is required for `LimitOrder` initialization".to_string(),
567            })?;
568        Self::new_checked(
569            event.trader_id,
570            event.strategy_id,
571            event.instrument_id,
572            event.client_order_id,
573            event.order_side,
574            event.quantity,
575            price,
576            event.time_in_force,
577            event.expire_time,
578            event.post_only,
579            event.reduce_only,
580            event.quote_quantity,
581            event.display_qty,
582            event.emulation_trigger,
583            event.trigger_instrument_id,
584            event.contingency_type,
585            event.order_list_id,
586            event.linked_order_ids,
587            event.parent_order_id,
588            event.exec_algorithm_id,
589            event.exec_algorithm_params,
590            event.exec_spawn_id,
591            event.tags,
592            event.event_id,
593            event.ts_event,
594        )
595    }
596}
597
598#[cfg(test)]
599mod tests {
600    use nautilus_core::UnixNanos;
601    use rstest::rstest;
602
603    use crate::{
604        enums::{OrderSide, OrderType, TimeInForce},
605        events::{OrderEventAny, OrderUpdated},
606        identifiers::InstrumentId,
607        instruments::{CurrencyPair, stubs::*},
608        orders::{Order, OrderTestBuilder, stubs::TestOrderStubs},
609        types::{Price, Quantity},
610    };
611
612    #[rstest]
613    fn test_initialize(audusd_sim: CurrencyPair) {
614        let order = OrderTestBuilder::new(OrderType::Limit)
615            .instrument_id(audusd_sim.id)
616            .side(OrderSide::Buy)
617            .price(Price::from("0.68000"))
618            .quantity(Quantity::from(1))
619            .build();
620
621        assert_eq!(order.time_in_force(), TimeInForce::Gtc);
622
623        assert_eq!(order.filled_qty(), Quantity::from(0));
624        assert_eq!(order.leaves_qty(), Quantity::from(1));
625
626        assert_eq!(order.display_qty(), None);
627        assert_eq!(order.trigger_instrument_id(), None);
628        assert_eq!(order.order_list_id(), None);
629    }
630
631    #[rstest]
632    fn test_display(audusd_sim: CurrencyPair) {
633        let order = OrderTestBuilder::new(OrderType::Limit)
634            .instrument_id(audusd_sim.id)
635            .side(OrderSide::Buy)
636            .price(Price::from("1.00000"))
637            .quantity(Quantity::from(100_000))
638            .build();
639
640        assert_eq!(
641            order.to_string(),
642            "LimitOrder(BUY 100_000 AUD/USD.SIM LIMIT @ 1.00000 GTC, \
643            status=INITIALIZED, client_order_id=O-19700101-000000-001-001-1, \
644            venue_order_id=None, position_id=None, exec_algorithm_id=None, \
645            exec_spawn_id=None, tags=None)"
646        );
647    }
648
649    #[rstest]
650    #[should_panic(
651        expected = "Condition failed: invalid `Quantity` for 'quantity' not positive, was 0"
652    )]
653    fn test_positive_quantity_condition(audusd_sim: CurrencyPair) {
654        let _ = OrderTestBuilder::new(OrderType::Limit)
655            .instrument_id(audusd_sim.id)
656            .side(OrderSide::Buy)
657            .price(Price::from("0.8"))
658            .quantity(Quantity::from(0))
659            .build();
660    }
661
662    #[rstest]
663    #[should_panic(expected = "Condition failed: `expire_time` is required for `GTD` order")]
664    fn test_correct_expiration_with_time_in_force_gtd(audusd_sim: CurrencyPair) {
665        let _ = OrderTestBuilder::new(OrderType::Limit)
666            .instrument_id(audusd_sim.id)
667            .side(OrderSide::Buy)
668            .price(Price::from("0.8"))
669            .quantity(Quantity::from(1))
670            .time_in_force(TimeInForce::Gtd)
671            .build();
672    }
673
674    #[rstest]
675    fn test_limit_order_creation() {
676        let order = OrderTestBuilder::new(OrderType::Limit)
677            .instrument_id(InstrumentId::from("BTC-USDT.BINANCE"))
678            .quantity(Quantity::from(10))
679            .price(Price::new(100.0, 2))
680            .side(OrderSide::Buy)
681            .time_in_force(TimeInForce::Gtc)
682            .build();
683
684        assert_eq!(order.price(), Some(Price::new(100.0, 2)));
685        assert_eq!(order.quantity(), Quantity::from(10));
686        assert_eq!(order.time_in_force(), TimeInForce::Gtc);
687        assert_eq!(order.order_side(), OrderSide::Buy);
688    }
689
690    #[rstest]
691    fn test_limit_order_with_expire_time() {
692        let expire_time = UnixNanos::from(1_700_000_000_000_000);
693        let order = OrderTestBuilder::new(OrderType::Limit)
694            .instrument_id(InstrumentId::from("BTC-USDT.BINANCE"))
695            .quantity(Quantity::from(10))
696            .price(Price::new(100.0, 2))
697            .time_in_force(TimeInForce::Gtd)
698            .expire_time(expire_time)
699            .build();
700
701        assert_eq!(order.expire_time(), Some(expire_time));
702        assert_eq!(order.time_in_force(), TimeInForce::Gtd);
703    }
704
705    #[rstest]
706    #[should_panic(expected = "Condition failed: `expire_time` is required for `GTD` order")]
707    fn test_limit_order_missing_expire_time() {
708        let _ = OrderTestBuilder::new(OrderType::Limit)
709            .instrument_id(InstrumentId::from("BTC-USDT.BINANCE"))
710            .quantity(Quantity::from(10))
711            .price(Price::new(100.0, 2))
712            .time_in_force(TimeInForce::Gtd)
713            .build();
714    }
715
716    #[rstest]
717    fn test_limit_order_post_only() {
718        let order = OrderTestBuilder::new(OrderType::Limit)
719            .instrument_id(InstrumentId::from("BTC-USDT.BINANCE"))
720            .quantity(Quantity::from(10))
721            .price(Price::new(100.0, 2))
722            .post_only(true)
723            .build();
724
725        assert!(order.is_post_only());
726    }
727
728    #[rstest]
729    fn test_limit_order_display_quantity() {
730        let display_qty = Quantity::from(5);
731        let order = OrderTestBuilder::new(OrderType::Limit)
732            .instrument_id(InstrumentId::from("BTC-USDT.BINANCE"))
733            .quantity(Quantity::from(10))
734            .price(Price::new(100.0, 2))
735            .display_qty(display_qty)
736            .build();
737
738        assert_eq!(order.display_qty(), Some(display_qty));
739    }
740
741    #[rstest]
742    fn test_limit_order_update() {
743        let order = OrderTestBuilder::new(OrderType::Limit)
744            .instrument_id(InstrumentId::from("BTC-USDT.BINANCE"))
745            .quantity(Quantity::from(10))
746            .price(Price::new(100.0, 2))
747            .build();
748
749        let mut accepted_order = TestOrderStubs::make_accepted_order(&order);
750
751        let updated_price = Price::new(105.0, 2);
752        let updated_quantity = Quantity::from(5);
753
754        let event = OrderUpdated {
755            client_order_id: accepted_order.client_order_id(),
756            strategy_id: accepted_order.strategy_id(),
757            price: Some(updated_price),
758            quantity: updated_quantity,
759            ..Default::default()
760        };
761
762        accepted_order.apply(OrderEventAny::Updated(event)).unwrap();
763
764        assert_eq!(accepted_order.quantity(), updated_quantity);
765        assert_eq!(accepted_order.price(), Some(updated_price));
766    }
767
768    #[rstest]
769    fn test_limit_order_expire_time() {
770        let expire_time = UnixNanos::from(1_700_000_000_000_000);
771        let order = OrderTestBuilder::new(OrderType::Limit)
772            .instrument_id(InstrumentId::from("BTC-USDT.BINANCE"))
773            .quantity(Quantity::from(10))
774            .price(Price::new(100.0, 2))
775            .time_in_force(TimeInForce::Gtd)
776            .expire_time(expire_time)
777            .build();
778
779        assert_eq!(order.expire_time(), Some(expire_time));
780    }
781}
nautilus_model/orders/limit.rs

nautilus_model/orders/
limit.rs
