Skip to main content

nautilus_common/messages/data/
subscribe.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::num::NonZeroUsize;
17
18use nautilus_core::{
19    Params, UUID4, UnixNanos,
20    correctness::{CorrectnessResult, check_positive_u64},
21};
22use nautilus_model::{
23    data::{BarType, DataType, option_chain::StrikeRange},
24    enums::BookType,
25    identifiers::{ClientId, InstrumentId, OptionSeriesId, Venue},
26};
27use serde::{Deserialize, Serialize};
28
29use super::{
30    IntoBarTypes, IntoInstrumentIds, check_client_id_or_venue,
31    identifiers::{
32        deserialize_bar_types, deserialize_instrument_ids, single_bar_type, single_instrument_id,
33    },
34};
35
36#[derive(Clone, Debug, Serialize, Deserialize)]
37#[cfg_attr(
38    feature = "python",
39    pyo3::pyclass(module = "nautilus_trader.live", frozen)
40)]
41#[cfg_attr(
42    feature = "python",
43    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
44)]
45pub struct SubscribeCustomData {
46    pub client_id: Option<ClientId>,
47    pub venue: Option<Venue>,
48    pub data_type: DataType,
49    pub command_id: UUID4,
50    pub ts_init: UnixNanos,
51    pub correlation_id: Option<UUID4>,
52    pub params: Option<Params>,
53}
54
55impl SubscribeCustomData {
56    /// Creates a new [`SubscribeCustomData`] instance.
57    pub fn new(
58        client_id: Option<ClientId>,
59        venue: Option<Venue>,
60        data_type: DataType,
61        command_id: UUID4,
62        ts_init: UnixNanos,
63        correlation_id: Option<UUID4>,
64        params: Option<Params>,
65    ) -> Self {
66        check_client_id_or_venue(&client_id, &venue);
67        Self {
68            client_id,
69            venue,
70            data_type,
71            command_id,
72            ts_init,
73            correlation_id,
74            params,
75        }
76    }
77}
78
79#[derive(Clone, Debug, Serialize, Deserialize)]
80#[cfg_attr(
81    feature = "python",
82    pyo3::pyclass(module = "nautilus_trader.live", frozen)
83)]
84#[cfg_attr(
85    feature = "python",
86    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
87)]
88pub struct SubscribeInstrument {
89    #[serde(deserialize_with = "deserialize_instrument_ids")]
90    pub instrument_ids: Vec<InstrumentId>,
91    pub client_id: Option<ClientId>,
92    pub venue: Option<Venue>,
93    pub command_id: UUID4,
94    pub ts_init: UnixNanos,
95    pub correlation_id: Option<UUID4>,
96    pub params: Option<Params>,
97}
98
99impl SubscribeInstrument {
100    /// Creates a new [`SubscribeInstrument`] instance.
101    ///
102    /// Duplicate IDs are removed in first-occurrence order.
103    ///
104    /// # Panics
105    ///
106    /// Panics if:
107    /// - The identifier list is empty.
108    /// - Both client and venue are absent.
109    pub fn new(
110        instrument_ids: impl IntoInstrumentIds,
111        client_id: Option<ClientId>,
112        venue: Option<Venue>,
113        command_id: UUID4,
114        ts_init: UnixNanos,
115        correlation_id: Option<UUID4>,
116        params: Option<Params>,
117    ) -> Self {
118        let instrument_ids = instrument_ids
119            .into_instrument_ids()
120            .expect("invalid instrument identifier list");
121        check_client_id_or_venue(&client_id, &venue);
122        Self {
123            instrument_ids,
124            client_id,
125            venue,
126            command_id,
127            ts_init,
128            correlation_id,
129            params,
130        }
131    }
132
133    /// Creates a command for the supplied IDs with the same routing and identity.
134    ///
135    /// # Panics
136    ///
137    /// Panics if the identifier list is empty.
138    #[must_use]
139    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
140        let instrument_ids = instrument_ids
141            .into_instrument_ids()
142            .expect("invalid instrument identifier list");
143
144        Self {
145            instrument_ids,
146            client_id: self.client_id,
147            venue: self.venue,
148            command_id: self.command_id,
149            ts_init: self.ts_init,
150            correlation_id: self.correlation_id,
151            params: self.params.clone(),
152        }
153    }
154
155    /// Returns the instrument ID for a single-instrument adapter path.
156    ///
157    /// # Errors
158    ///
159    /// Returns an error if the command does not contain exactly one instrument.
160    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
161        single_instrument_id(&self.instrument_ids, "subscription")
162    }
163}
164
165#[derive(Clone, Debug, Serialize, Deserialize)]
166#[cfg_attr(
167    feature = "python",
168    pyo3::pyclass(module = "nautilus_trader.live", frozen)
169)]
170#[cfg_attr(
171    feature = "python",
172    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
173)]
174pub struct SubscribeInstruments {
175    pub client_id: Option<ClientId>,
176    pub venue: Venue,
177    pub command_id: UUID4,
178    pub ts_init: UnixNanos,
179    pub correlation_id: Option<UUID4>,
180    pub params: Option<Params>,
181}
182
183impl SubscribeInstruments {
184    /// Creates a new [`SubscribeInstruments`] instance.
185    pub fn new(
186        client_id: Option<ClientId>,
187        venue: Venue,
188        command_id: UUID4,
189        ts_init: UnixNanos,
190        correlation_id: Option<UUID4>,
191        params: Option<Params>,
192    ) -> Self {
193        Self {
194            client_id,
195            venue,
196            command_id,
197            ts_init,
198            correlation_id,
199            params,
200        }
201    }
202}
203
204#[derive(Clone, Debug, Serialize, Deserialize)]
205#[cfg_attr(
206    feature = "python",
207    pyo3::pyclass(module = "nautilus_trader.live", frozen)
208)]
209#[cfg_attr(
210    feature = "python",
211    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
212)]
213pub struct SubscribeBookDeltas {
214    #[serde(deserialize_with = "deserialize_instrument_ids")]
215    pub instrument_ids: Vec<InstrumentId>,
216    pub book_type: BookType,
217    pub client_id: Option<ClientId>,
218    pub venue: Option<Venue>,
219    pub command_id: UUID4,
220    pub ts_init: UnixNanos,
221    pub depth: Option<NonZeroUsize>,
222    pub managed: bool,
223    pub correlation_id: Option<UUID4>,
224    pub params: Option<Params>,
225}
226
227impl SubscribeBookDeltas {
228    /// Creates a new [`SubscribeBookDeltas`] instance.
229    ///
230    /// Duplicate IDs are removed in first-occurrence order.
231    ///
232    /// # Panics
233    ///
234    /// Panics if:
235    /// - The identifier list is empty.
236    /// - Both client and venue are absent.
237    #[expect(clippy::too_many_arguments)]
238    pub fn new(
239        instrument_ids: impl IntoInstrumentIds,
240        book_type: BookType,
241        client_id: Option<ClientId>,
242        venue: Option<Venue>,
243        command_id: UUID4,
244        ts_init: UnixNanos,
245        depth: Option<NonZeroUsize>,
246        managed: bool,
247        correlation_id: Option<UUID4>,
248        params: Option<Params>,
249    ) -> Self {
250        let instrument_ids = instrument_ids
251            .into_instrument_ids()
252            .expect("invalid instrument identifier list");
253        check_client_id_or_venue(&client_id, &venue);
254        Self {
255            instrument_ids,
256            book_type,
257            client_id,
258            venue,
259            command_id,
260            ts_init,
261            depth,
262            managed,
263            correlation_id,
264            params,
265        }
266    }
267
268    /// Creates a command for the supplied IDs with the same routing and identity.
269    ///
270    /// # Panics
271    ///
272    /// Panics if the identifier list is empty.
273    #[must_use]
274    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
275        let instrument_ids = instrument_ids
276            .into_instrument_ids()
277            .expect("invalid instrument identifier list");
278
279        Self {
280            instrument_ids,
281            book_type: self.book_type,
282            client_id: self.client_id,
283            venue: self.venue,
284            command_id: self.command_id,
285            ts_init: self.ts_init,
286            depth: self.depth,
287            managed: self.managed,
288            correlation_id: self.correlation_id,
289            params: self.params.clone(),
290        }
291    }
292
293    /// Returns the instrument ID for a single-instrument adapter path.
294    ///
295    /// # Errors
296    ///
297    /// Returns an error if the command does not contain exactly one instrument.
298    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
299        single_instrument_id(&self.instrument_ids, "subscription")
300    }
301}
302
303#[derive(Clone, Debug, Serialize, Deserialize)]
304#[cfg_attr(
305    feature = "python",
306    pyo3::pyclass(module = "nautilus_trader.live", frozen)
307)]
308#[cfg_attr(
309    feature = "python",
310    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
311)]
312pub struct SubscribeBookDepth {
313    #[serde(deserialize_with = "deserialize_instrument_ids")]
314    pub instrument_ids: Vec<InstrumentId>,
315    pub book_type: BookType,
316    pub client_id: Option<ClientId>,
317    pub venue: Option<Venue>,
318    pub command_id: UUID4,
319    pub ts_init: UnixNanos,
320    pub depth: Option<NonZeroUsize>,
321    pub managed: bool,
322    pub correlation_id: Option<UUID4>,
323    pub params: Option<Params>,
324}
325
326impl SubscribeBookDepth {
327    /// Creates a new [`SubscribeBookDepth`] instance.
328    ///
329    /// Duplicate IDs are removed in first-occurrence order.
330    ///
331    /// # Panics
332    ///
333    /// Panics if:
334    /// - The identifier list is empty.
335    /// - Both client and venue are absent.
336    #[expect(clippy::too_many_arguments)]
337    pub fn new(
338        instrument_ids: impl IntoInstrumentIds,
339        book_type: BookType,
340        client_id: Option<ClientId>,
341        venue: Option<Venue>,
342        command_id: UUID4,
343        ts_init: UnixNanos,
344        depth: Option<NonZeroUsize>,
345        managed: bool,
346        correlation_id: Option<UUID4>,
347        params: Option<Params>,
348    ) -> Self {
349        let instrument_ids = instrument_ids
350            .into_instrument_ids()
351            .expect("invalid instrument identifier list");
352        check_client_id_or_venue(&client_id, &venue);
353        Self {
354            instrument_ids,
355            book_type,
356            client_id,
357            venue,
358            command_id,
359            ts_init,
360            depth,
361            managed,
362            correlation_id,
363            params,
364        }
365    }
366
367    /// Creates a command for the supplied IDs with the same routing and identity.
368    ///
369    /// # Panics
370    ///
371    /// Panics if the identifier list is empty.
372    #[must_use]
373    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
374        let instrument_ids = instrument_ids
375            .into_instrument_ids()
376            .expect("invalid instrument identifier list");
377
378        Self {
379            instrument_ids,
380            book_type: self.book_type,
381            client_id: self.client_id,
382            venue: self.venue,
383            command_id: self.command_id,
384            ts_init: self.ts_init,
385            depth: self.depth,
386            managed: self.managed,
387            correlation_id: self.correlation_id,
388            params: self.params.clone(),
389        }
390    }
391
392    /// Returns the instrument ID for a single-instrument adapter path.
393    ///
394    /// # Errors
395    ///
396    /// Returns an error if the command does not contain exactly one instrument.
397    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
398        single_instrument_id(&self.instrument_ids, "subscription")
399    }
400}
401
402#[derive(Clone, Debug, Serialize, Deserialize)]
403pub struct SubscribeBookSnapshots {
404    #[serde(deserialize_with = "deserialize_instrument_ids")]
405    pub instrument_ids: Vec<InstrumentId>,
406    pub book_type: BookType,
407    pub client_id: Option<ClientId>,
408    pub venue: Option<Venue>,
409    pub command_id: UUID4,
410    pub ts_init: UnixNanos,
411    pub depth: Option<NonZeroUsize>,
412    pub interval_ms: NonZeroUsize,
413    pub correlation_id: Option<UUID4>,
414    pub params: Option<Params>,
415}
416
417impl SubscribeBookSnapshots {
418    /// Creates a new [`SubscribeBookSnapshots`] instance.
419    ///
420    /// Duplicate IDs are removed in first-occurrence order.
421    ///
422    /// # Panics
423    ///
424    /// Panics if:
425    /// - The identifier list is empty.
426    /// - Both client and venue are absent.
427    #[expect(clippy::too_many_arguments)]
428    pub fn new(
429        instrument_ids: impl IntoInstrumentIds,
430        book_type: BookType,
431        client_id: Option<ClientId>,
432        venue: Option<Venue>,
433        command_id: UUID4,
434        ts_init: UnixNanos,
435        depth: Option<NonZeroUsize>,
436        interval_ms: NonZeroUsize,
437        correlation_id: Option<UUID4>,
438        params: Option<Params>,
439    ) -> Self {
440        let instrument_ids = instrument_ids
441            .into_instrument_ids()
442            .expect("invalid instrument identifier list");
443        check_client_id_or_venue(&client_id, &venue);
444        Self {
445            instrument_ids,
446            book_type,
447            client_id,
448            venue,
449            command_id,
450            ts_init,
451            depth,
452            interval_ms,
453            correlation_id,
454            params,
455        }
456    }
457
458    /// Creates a command for the supplied IDs with the same routing and identity.
459    ///
460    /// # Panics
461    ///
462    /// Panics if the identifier list is empty.
463    #[must_use]
464    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
465        let instrument_ids = instrument_ids
466            .into_instrument_ids()
467            .expect("invalid instrument identifier list");
468
469        Self {
470            instrument_ids,
471            book_type: self.book_type,
472            client_id: self.client_id,
473            venue: self.venue,
474            command_id: self.command_id,
475            ts_init: self.ts_init,
476            depth: self.depth,
477            interval_ms: self.interval_ms,
478            correlation_id: self.correlation_id,
479            params: self.params.clone(),
480        }
481    }
482
483    /// Returns the instrument ID for a single-instrument adapter path.
484    ///
485    /// # Errors
486    ///
487    /// Returns an error if the command does not contain exactly one instrument.
488    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
489        single_instrument_id(&self.instrument_ids, "subscription")
490    }
491}
492
493#[derive(Clone, Debug, Serialize, Deserialize)]
494#[cfg_attr(
495    feature = "python",
496    pyo3::pyclass(module = "nautilus_trader.live", frozen)
497)]
498#[cfg_attr(
499    feature = "python",
500    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
501)]
502pub struct SubscribeQuotes {
503    #[serde(deserialize_with = "deserialize_instrument_ids")]
504    pub instrument_ids: Vec<InstrumentId>,
505    pub client_id: Option<ClientId>,
506    pub venue: Option<Venue>,
507    pub command_id: UUID4,
508    pub ts_init: UnixNanos,
509    pub correlation_id: Option<UUID4>,
510    pub params: Option<Params>,
511}
512
513impl SubscribeQuotes {
514    /// Creates a new [`SubscribeQuotes`] instance.
515    ///
516    /// Duplicate IDs are removed in first-occurrence order.
517    ///
518    /// # Panics
519    ///
520    /// Panics if:
521    /// - The identifier list is empty.
522    /// - Both client and venue are absent.
523    pub fn new(
524        instrument_ids: impl IntoInstrumentIds,
525        client_id: Option<ClientId>,
526        venue: Option<Venue>,
527        command_id: UUID4,
528        ts_init: UnixNanos,
529        correlation_id: Option<UUID4>,
530        params: Option<Params>,
531    ) -> Self {
532        let instrument_ids = instrument_ids
533            .into_instrument_ids()
534            .expect("invalid instrument identifier list");
535        check_client_id_or_venue(&client_id, &venue);
536        Self {
537            instrument_ids,
538            client_id,
539            venue,
540            command_id,
541            ts_init,
542            correlation_id,
543            params,
544        }
545    }
546
547    /// Creates a command for the supplied IDs with the same routing and identity.
548    ///
549    /// # Panics
550    ///
551    /// Panics if the identifier list is empty.
552    #[must_use]
553    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
554        let instrument_ids = instrument_ids
555            .into_instrument_ids()
556            .expect("invalid instrument identifier list");
557
558        Self {
559            instrument_ids,
560            client_id: self.client_id,
561            venue: self.venue,
562            command_id: self.command_id,
563            ts_init: self.ts_init,
564            correlation_id: self.correlation_id,
565            params: self.params.clone(),
566        }
567    }
568
569    /// Returns the instrument ID for a single-instrument adapter path.
570    ///
571    /// # Errors
572    ///
573    /// Returns an error if the command does not contain exactly one instrument.
574    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
575        single_instrument_id(&self.instrument_ids, "subscription")
576    }
577}
578
579/// Reports synchronous acceptance during a failed subscribe or unsubscribe operation.
580///
581/// `instrument_ids_accepted` and `bar_types_accepted` identify accepted members of the dispatched
582/// command. Bar operations use full bar types. Unsubscribe acceptance means successful release;
583/// venue acknowledgements arrive asynchronously.
584#[derive(Debug, thiserror::Error)]
585#[error("{source}")]
586#[non_exhaustive]
587pub struct SubscriptionError {
588    pub instrument_ids_accepted: Vec<InstrumentId>,
589    pub bar_types_accepted: Vec<BarType>,
590    #[source]
591    pub source: anyhow::Error,
592}
593
594impl SubscriptionError {
595    /// Creates an error with the exact accepted instrument members.
596    #[must_use]
597    pub fn instruments(instrument_ids_accepted: Vec<InstrumentId>, source: anyhow::Error) -> Self {
598        Self {
599            instrument_ids_accepted,
600            bar_types_accepted: Vec::new(),
601            source,
602        }
603    }
604
605    /// Creates an error with the exact accepted full bar types.
606    #[must_use]
607    pub fn bars(bar_types_accepted: Vec<BarType>, source: anyhow::Error) -> Self {
608        Self {
609            instrument_ids_accepted: Vec::new(),
610            bar_types_accepted,
611            source,
612        }
613    }
614}
615
616#[derive(Clone, Debug, Serialize, Deserialize)]
617#[cfg_attr(
618    feature = "python",
619    pyo3::pyclass(module = "nautilus_trader.live", frozen)
620)]
621#[cfg_attr(
622    feature = "python",
623    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
624)]
625pub struct SubscribeTrades {
626    #[serde(deserialize_with = "deserialize_instrument_ids")]
627    pub instrument_ids: Vec<InstrumentId>,
628    pub client_id: Option<ClientId>,
629    pub venue: Option<Venue>,
630    pub command_id: UUID4,
631    pub ts_init: UnixNanos,
632    pub correlation_id: Option<UUID4>,
633    pub params: Option<Params>,
634}
635
636impl SubscribeTrades {
637    /// Creates a new [`SubscribeTrades`] instance.
638    ///
639    /// Duplicate IDs are removed in first-occurrence order.
640    ///
641    /// # Panics
642    ///
643    /// Panics if:
644    /// - The identifier list is empty.
645    /// - Both client and venue are absent.
646    pub fn new(
647        instrument_ids: impl IntoInstrumentIds,
648        client_id: Option<ClientId>,
649        venue: Option<Venue>,
650        command_id: UUID4,
651        ts_init: UnixNanos,
652        correlation_id: Option<UUID4>,
653        params: Option<Params>,
654    ) -> Self {
655        let instrument_ids = instrument_ids
656            .into_instrument_ids()
657            .expect("invalid instrument identifier list");
658        check_client_id_or_venue(&client_id, &venue);
659        Self {
660            instrument_ids,
661            client_id,
662            venue,
663            command_id,
664            ts_init,
665            correlation_id,
666            params,
667        }
668    }
669
670    /// Creates a command for the supplied IDs with the same routing and identity.
671    ///
672    /// # Panics
673    ///
674    /// Panics if the identifier list is empty.
675    #[must_use]
676    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
677        let instrument_ids = instrument_ids
678            .into_instrument_ids()
679            .expect("invalid instrument identifier list");
680
681        Self {
682            instrument_ids,
683            client_id: self.client_id,
684            venue: self.venue,
685            command_id: self.command_id,
686            ts_init: self.ts_init,
687            correlation_id: self.correlation_id,
688            params: self.params.clone(),
689        }
690    }
691
692    /// Returns the instrument ID for a single-instrument adapter path.
693    ///
694    /// # Errors
695    ///
696    /// Returns an error if the command does not contain exactly one instrument.
697    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
698        single_instrument_id(&self.instrument_ids, "subscription")
699    }
700}
701
702#[derive(Clone, Debug, Serialize, Deserialize)]
703#[cfg_attr(
704    feature = "python",
705    pyo3::pyclass(module = "nautilus_trader.live", frozen)
706)]
707#[cfg_attr(
708    feature = "python",
709    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
710)]
711pub struct SubscribeBars {
712    #[serde(deserialize_with = "deserialize_bar_types")]
713    pub bar_types: Vec<BarType>,
714    pub client_id: Option<ClientId>,
715    pub venue: Option<Venue>,
716    pub command_id: UUID4,
717    pub ts_init: UnixNanos,
718    pub correlation_id: Option<UUID4>,
719    pub params: Option<Params>,
720}
721
722impl SubscribeBars {
723    /// Creates a new [`SubscribeBars`] instance.
724    ///
725    /// Duplicate bar types are removed in first-occurrence order.
726    ///
727    /// # Panics
728    ///
729    /// Panics if:
730    /// - The bar type list is empty.
731    /// - Both client and venue are absent.
732    pub fn new(
733        bar_types: impl IntoBarTypes,
734        client_id: Option<ClientId>,
735        venue: Option<Venue>,
736        command_id: UUID4,
737        ts_init: UnixNanos,
738        correlation_id: Option<UUID4>,
739        params: Option<Params>,
740    ) -> Self {
741        let bar_types = bar_types.into_bar_types().expect("invalid bar type list");
742        check_client_id_or_venue(&client_id, &venue);
743        Self {
744            bar_types,
745            client_id,
746            venue,
747            command_id,
748            ts_init,
749            correlation_id,
750            params,
751        }
752    }
753
754    /// Creates a command for the supplied bar types with the same routing and identity.
755    ///
756    /// # Panics
757    ///
758    /// Panics if the bar type list is empty.
759    #[must_use]
760    pub fn with_bar_types(&self, bar_types: impl IntoBarTypes) -> Self {
761        let bar_types = bar_types.into_bar_types().expect("invalid bar type list");
762
763        Self {
764            bar_types,
765            client_id: self.client_id,
766            venue: self.venue,
767            command_id: self.command_id,
768            ts_init: self.ts_init,
769            correlation_id: self.correlation_id,
770            params: self.params.clone(),
771        }
772    }
773
774    /// Returns the bar type for a single-bar-type adapter path.
775    ///
776    /// # Errors
777    ///
778    /// Returns an error if the command does not contain exactly one bar type.
779    pub fn single_bar_type(&self) -> anyhow::Result<BarType> {
780        single_bar_type(&self.bar_types, "subscription")
781    }
782}
783
784#[derive(Clone, Debug, Serialize, Deserialize)]
785#[cfg_attr(
786    feature = "python",
787    pyo3::pyclass(module = "nautilus_trader.live", frozen)
788)]
789#[cfg_attr(
790    feature = "python",
791    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
792)]
793pub struct SubscribeMarkPrices {
794    #[serde(deserialize_with = "deserialize_instrument_ids")]
795    pub instrument_ids: Vec<InstrumentId>,
796    pub client_id: Option<ClientId>,
797    pub venue: Option<Venue>,
798    pub command_id: UUID4,
799    pub ts_init: UnixNanos,
800    pub correlation_id: Option<UUID4>,
801    pub params: Option<Params>,
802}
803
804impl SubscribeMarkPrices {
805    /// Creates a new [`SubscribeMarkPrices`] instance.
806    ///
807    /// Duplicate IDs are removed in first-occurrence order.
808    ///
809    /// # Panics
810    ///
811    /// Panics if:
812    /// - The identifier list is empty.
813    /// - Both client and venue are absent.
814    pub fn new(
815        instrument_ids: impl IntoInstrumentIds,
816        client_id: Option<ClientId>,
817        venue: Option<Venue>,
818        command_id: UUID4,
819        ts_init: UnixNanos,
820        correlation_id: Option<UUID4>,
821        params: Option<Params>,
822    ) -> Self {
823        let instrument_ids = instrument_ids
824            .into_instrument_ids()
825            .expect("invalid instrument identifier list");
826        check_client_id_or_venue(&client_id, &venue);
827        Self {
828            instrument_ids,
829            client_id,
830            venue,
831            command_id,
832            ts_init,
833            correlation_id,
834            params,
835        }
836    }
837
838    /// Creates a command for the supplied IDs with the same routing and identity.
839    ///
840    /// # Panics
841    ///
842    /// Panics if the identifier list is empty.
843    #[must_use]
844    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
845        let instrument_ids = instrument_ids
846            .into_instrument_ids()
847            .expect("invalid instrument identifier list");
848
849        Self {
850            instrument_ids,
851            client_id: self.client_id,
852            venue: self.venue,
853            command_id: self.command_id,
854            ts_init: self.ts_init,
855            correlation_id: self.correlation_id,
856            params: self.params.clone(),
857        }
858    }
859
860    /// Returns the instrument ID for a single-instrument adapter path.
861    ///
862    /// # Errors
863    ///
864    /// Returns an error if the command does not contain exactly one instrument.
865    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
866        single_instrument_id(&self.instrument_ids, "subscription")
867    }
868}
869
870#[derive(Clone, Debug, Serialize, Deserialize)]
871#[cfg_attr(
872    feature = "python",
873    pyo3::pyclass(module = "nautilus_trader.live", frozen)
874)]
875#[cfg_attr(
876    feature = "python",
877    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
878)]
879pub struct SubscribeIndexPrices {
880    #[serde(deserialize_with = "deserialize_instrument_ids")]
881    pub instrument_ids: Vec<InstrumentId>,
882    pub client_id: Option<ClientId>,
883    pub venue: Option<Venue>,
884    pub command_id: UUID4,
885    pub ts_init: UnixNanos,
886    pub correlation_id: Option<UUID4>,
887    pub params: Option<Params>,
888}
889
890impl SubscribeIndexPrices {
891    /// Creates a new [`SubscribeIndexPrices`] instance.
892    ///
893    /// Duplicate IDs are removed in first-occurrence order.
894    ///
895    /// # Panics
896    ///
897    /// Panics if:
898    /// - The identifier list is empty.
899    /// - Both client and venue are absent.
900    pub fn new(
901        instrument_ids: impl IntoInstrumentIds,
902        client_id: Option<ClientId>,
903        venue: Option<Venue>,
904        command_id: UUID4,
905        ts_init: UnixNanos,
906        correlation_id: Option<UUID4>,
907        params: Option<Params>,
908    ) -> Self {
909        let instrument_ids = instrument_ids
910            .into_instrument_ids()
911            .expect("invalid instrument identifier list");
912        check_client_id_or_venue(&client_id, &venue);
913        Self {
914            instrument_ids,
915            client_id,
916            venue,
917            command_id,
918            ts_init,
919            correlation_id,
920            params,
921        }
922    }
923
924    /// Creates a command for the supplied IDs with the same routing and identity.
925    ///
926    /// # Panics
927    ///
928    /// Panics if the identifier list is empty.
929    #[must_use]
930    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
931        let instrument_ids = instrument_ids
932            .into_instrument_ids()
933            .expect("invalid instrument identifier list");
934
935        Self {
936            instrument_ids,
937            client_id: self.client_id,
938            venue: self.venue,
939            command_id: self.command_id,
940            ts_init: self.ts_init,
941            correlation_id: self.correlation_id,
942            params: self.params.clone(),
943        }
944    }
945
946    /// Returns the instrument ID for a single-instrument adapter path.
947    ///
948    /// # Errors
949    ///
950    /// Returns an error if the command does not contain exactly one instrument.
951    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
952        single_instrument_id(&self.instrument_ids, "subscription")
953    }
954}
955
956#[derive(Clone, Debug, Serialize, Deserialize)]
957#[cfg_attr(
958    feature = "python",
959    pyo3::pyclass(module = "nautilus_trader.live", frozen)
960)]
961#[cfg_attr(
962    feature = "python",
963    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
964)]
965pub struct SubscribeFundingRates {
966    #[serde(deserialize_with = "deserialize_instrument_ids")]
967    pub instrument_ids: Vec<InstrumentId>,
968    pub client_id: Option<ClientId>,
969    pub venue: Option<Venue>,
970    pub command_id: UUID4,
971    pub ts_init: UnixNanos,
972    pub correlation_id: Option<UUID4>,
973    pub params: Option<Params>,
974}
975
976impl SubscribeFundingRates {
977    /// Creates a new [`SubscribeFundingRates`] instance.
978    ///
979    /// Duplicate IDs are removed in first-occurrence order.
980    ///
981    /// # Panics
982    ///
983    /// Panics if:
984    /// - The identifier list is empty.
985    /// - Both client and venue are absent.
986    pub fn new(
987        instrument_ids: impl IntoInstrumentIds,
988        client_id: Option<ClientId>,
989        venue: Option<Venue>,
990        command_id: UUID4,
991        ts_init: UnixNanos,
992        correlation_id: Option<UUID4>,
993        params: Option<Params>,
994    ) -> Self {
995        let instrument_ids = instrument_ids
996            .into_instrument_ids()
997            .expect("invalid instrument identifier list");
998        check_client_id_or_venue(&client_id, &venue);
999        Self {
1000            instrument_ids,
1001            client_id,
1002            venue,
1003            command_id,
1004            ts_init,
1005            correlation_id,
1006            params,
1007        }
1008    }
1009
1010    /// Creates a command for the supplied IDs with the same routing and identity.
1011    ///
1012    /// # Panics
1013    ///
1014    /// Panics if the identifier list is empty.
1015    #[must_use]
1016    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
1017        let instrument_ids = instrument_ids
1018            .into_instrument_ids()
1019            .expect("invalid instrument identifier list");
1020
1021        Self {
1022            instrument_ids,
1023            client_id: self.client_id,
1024            venue: self.venue,
1025            command_id: self.command_id,
1026            ts_init: self.ts_init,
1027            correlation_id: self.correlation_id,
1028            params: self.params.clone(),
1029        }
1030    }
1031
1032    /// Returns the instrument ID for a single-instrument adapter path.
1033    ///
1034    /// # Errors
1035    ///
1036    /// Returns an error if the command does not contain exactly one instrument.
1037    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
1038        single_instrument_id(&self.instrument_ids, "subscription")
1039    }
1040}
1041
1042#[derive(Clone, Debug, Serialize, Deserialize)]
1043#[cfg_attr(
1044    feature = "python",
1045    pyo3::pyclass(module = "nautilus_trader.live", frozen)
1046)]
1047#[cfg_attr(
1048    feature = "python",
1049    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
1050)]
1051pub struct SubscribeInstrumentStatus {
1052    #[serde(deserialize_with = "deserialize_instrument_ids")]
1053    pub instrument_ids: Vec<InstrumentId>,
1054    pub client_id: Option<ClientId>,
1055    pub venue: Option<Venue>,
1056    pub command_id: UUID4,
1057    pub ts_init: UnixNanos,
1058    pub correlation_id: Option<UUID4>,
1059    pub params: Option<Params>,
1060}
1061
1062impl SubscribeInstrumentStatus {
1063    /// Creates a new [`SubscribeInstrumentStatus`] instance.
1064    ///
1065    /// Duplicate IDs are removed in first-occurrence order.
1066    ///
1067    /// # Panics
1068    ///
1069    /// Panics if:
1070    /// - The identifier list is empty.
1071    /// - Both client and venue are absent.
1072    pub fn new(
1073        instrument_ids: impl IntoInstrumentIds,
1074        client_id: Option<ClientId>,
1075        venue: Option<Venue>,
1076        command_id: UUID4,
1077        ts_init: UnixNanos,
1078        correlation_id: Option<UUID4>,
1079        params: Option<Params>,
1080    ) -> Self {
1081        let instrument_ids = instrument_ids
1082            .into_instrument_ids()
1083            .expect("invalid instrument identifier list");
1084        check_client_id_or_venue(&client_id, &venue);
1085        Self {
1086            instrument_ids,
1087            client_id,
1088            venue,
1089            command_id,
1090            ts_init,
1091            correlation_id,
1092            params,
1093        }
1094    }
1095
1096    /// Creates a command for the supplied IDs with the same routing and identity.
1097    ///
1098    /// # Panics
1099    ///
1100    /// Panics if the identifier list is empty.
1101    #[must_use]
1102    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
1103        let instrument_ids = instrument_ids
1104            .into_instrument_ids()
1105            .expect("invalid instrument identifier list");
1106
1107        Self {
1108            instrument_ids,
1109            client_id: self.client_id,
1110            venue: self.venue,
1111            command_id: self.command_id,
1112            ts_init: self.ts_init,
1113            correlation_id: self.correlation_id,
1114            params: self.params.clone(),
1115        }
1116    }
1117
1118    /// Returns the instrument ID for a single-instrument adapter path.
1119    ///
1120    /// # Errors
1121    ///
1122    /// Returns an error if the command does not contain exactly one instrument.
1123    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
1124        single_instrument_id(&self.instrument_ids, "subscription")
1125    }
1126}
1127
1128#[derive(Clone, Debug, Serialize, Deserialize)]
1129#[cfg_attr(
1130    feature = "python",
1131    pyo3::pyclass(module = "nautilus_trader.live", frozen)
1132)]
1133#[cfg_attr(
1134    feature = "python",
1135    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
1136)]
1137pub struct SubscribeOptionGreeks {
1138    #[serde(deserialize_with = "deserialize_instrument_ids")]
1139    pub instrument_ids: Vec<InstrumentId>,
1140    pub client_id: Option<ClientId>,
1141    pub venue: Option<Venue>,
1142    pub command_id: UUID4,
1143    pub ts_init: UnixNanos,
1144    pub correlation_id: Option<UUID4>,
1145    pub params: Option<Params>,
1146}
1147
1148impl SubscribeOptionGreeks {
1149    /// Creates a new [`SubscribeOptionGreeks`] instance.
1150    ///
1151    /// Duplicate IDs are removed in first-occurrence order.
1152    ///
1153    /// # Panics
1154    ///
1155    /// Panics if:
1156    /// - The identifier list is empty.
1157    /// - Both client and venue are absent.
1158    pub fn new(
1159        instrument_ids: impl IntoInstrumentIds,
1160        client_id: Option<ClientId>,
1161        venue: Option<Venue>,
1162        command_id: UUID4,
1163        ts_init: UnixNanos,
1164        correlation_id: Option<UUID4>,
1165        params: Option<Params>,
1166    ) -> Self {
1167        let instrument_ids = instrument_ids
1168            .into_instrument_ids()
1169            .expect("invalid instrument identifier list");
1170        check_client_id_or_venue(&client_id, &venue);
1171        Self {
1172            instrument_ids,
1173            client_id,
1174            venue,
1175            command_id,
1176            ts_init,
1177            correlation_id,
1178            params,
1179        }
1180    }
1181
1182    /// Creates a command for the supplied IDs with the same routing and identity.
1183    ///
1184    /// # Panics
1185    ///
1186    /// Panics if the identifier list is empty.
1187    #[must_use]
1188    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
1189        let instrument_ids = instrument_ids
1190            .into_instrument_ids()
1191            .expect("invalid instrument identifier list");
1192
1193        Self {
1194            instrument_ids,
1195            client_id: self.client_id,
1196            venue: self.venue,
1197            command_id: self.command_id,
1198            ts_init: self.ts_init,
1199            correlation_id: self.correlation_id,
1200            params: self.params.clone(),
1201        }
1202    }
1203
1204    /// Returns the instrument ID for a single-instrument adapter path.
1205    ///
1206    /// # Errors
1207    ///
1208    /// Returns an error if the command does not contain exactly one instrument.
1209    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
1210        single_instrument_id(&self.instrument_ids, "subscription")
1211    }
1212}
1213
1214#[derive(Clone, Debug, Serialize, Deserialize)]
1215#[cfg_attr(
1216    feature = "python",
1217    pyo3::pyclass(module = "nautilus_trader.live", frozen)
1218)]
1219#[cfg_attr(
1220    feature = "python",
1221    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.live")
1222)]
1223pub struct SubscribeInstrumentClose {
1224    #[serde(deserialize_with = "deserialize_instrument_ids")]
1225    pub instrument_ids: Vec<InstrumentId>,
1226    pub client_id: Option<ClientId>,
1227    pub venue: Option<Venue>,
1228    pub command_id: UUID4,
1229    pub ts_init: UnixNanos,
1230    pub correlation_id: Option<UUID4>,
1231    pub params: Option<Params>,
1232}
1233
1234impl SubscribeInstrumentClose {
1235    /// Creates a new [`SubscribeInstrumentClose`] instance.
1236    ///
1237    /// Duplicate IDs are removed in first-occurrence order.
1238    ///
1239    /// # Panics
1240    ///
1241    /// Panics if:
1242    /// - The identifier list is empty.
1243    /// - Both client and venue are absent.
1244    pub fn new(
1245        instrument_ids: impl IntoInstrumentIds,
1246        client_id: Option<ClientId>,
1247        venue: Option<Venue>,
1248        command_id: UUID4,
1249        ts_init: UnixNanos,
1250        correlation_id: Option<UUID4>,
1251        params: Option<Params>,
1252    ) -> Self {
1253        let instrument_ids = instrument_ids
1254            .into_instrument_ids()
1255            .expect("invalid instrument identifier list");
1256        check_client_id_or_venue(&client_id, &venue);
1257        Self {
1258            instrument_ids,
1259            client_id,
1260            venue,
1261            command_id,
1262            ts_init,
1263            correlation_id,
1264            params,
1265        }
1266    }
1267
1268    /// Creates a command for the supplied IDs with the same routing and identity.
1269    ///
1270    /// # Panics
1271    ///
1272    /// Panics if the identifier list is empty.
1273    #[must_use]
1274    pub fn with_instrument_ids(&self, instrument_ids: impl IntoInstrumentIds) -> Self {
1275        let instrument_ids = instrument_ids
1276            .into_instrument_ids()
1277            .expect("invalid instrument identifier list");
1278
1279        Self {
1280            instrument_ids,
1281            client_id: self.client_id,
1282            venue: self.venue,
1283            command_id: self.command_id,
1284            ts_init: self.ts_init,
1285            correlation_id: self.correlation_id,
1286            params: self.params.clone(),
1287        }
1288    }
1289
1290    /// Returns the instrument ID for a single-instrument adapter path.
1291    ///
1292    /// # Errors
1293    ///
1294    /// Returns an error if the command does not contain exactly one instrument.
1295    pub fn single_instrument_id(&self) -> anyhow::Result<InstrumentId> {
1296        single_instrument_id(&self.instrument_ids, "subscription")
1297    }
1298}
1299
1300#[derive(Clone, Debug, Serialize, Deserialize)]
1301pub struct SubscribeOptionChain {
1302    pub series_id: OptionSeriesId,
1303    pub strike_range: StrikeRange,
1304    pub snapshot_interval_ms: Option<u64>,
1305    pub command_id: UUID4,
1306    pub ts_init: UnixNanos,
1307    pub client_id: Option<ClientId>,
1308    pub venue: Option<Venue>,
1309    #[serde(default)]
1310    pub correlation_id: Option<UUID4>,
1311    pub params: Option<Params>,
1312}
1313
1314impl SubscribeOptionChain {
1315    // panics-doc-ok
1316    /// Creates a checked option-chain subscription command.
1317    ///
1318    /// # Errors
1319    ///
1320    /// Returns an error if the snapshot interval is zero.
1321    ///
1322    /// # Panics
1323    ///
1324    /// Panics if both client and venue are absent.
1325    #[expect(
1326        clippy::too_many_arguments,
1327        reason = "constructor exposes the option chain subscription fields"
1328    )]
1329    pub fn new(
1330        series_id: OptionSeriesId,
1331        strike_range: StrikeRange,
1332        snapshot_interval_ms: Option<u64>,
1333        command_id: UUID4,
1334        ts_init: UnixNanos,
1335        client_id: Option<ClientId>,
1336        venue: Option<Venue>,
1337        params: Option<Params>,
1338    ) -> CorrectnessResult<Self> {
1339        check_client_id_or_venue(&client_id, &venue);
1340
1341        if let Some(interval) = snapshot_interval_ms {
1342            check_positive_u64(interval, "snapshot_interval_ms")?;
1343        }
1344
1345        Ok(Self {
1346            series_id,
1347            strike_range,
1348            snapshot_interval_ms,
1349            command_id,
1350            ts_init,
1351            client_id,
1352            venue,
1353            correlation_id: None,
1354            params,
1355        })
1356    }
1357}
1358
1359#[cfg(test)]
1360mod tests {
1361    use nautilus_model::types::Price;
1362    use rstest::rstest;
1363
1364    use super::*;
1365
1366    #[rstest]
1367    #[case(None)]
1368    #[case(Some(1))]
1369    #[case(Some(250))]
1370    fn test_option_chain_command_preserves_valid_inputs(#[case] interval: Option<u64>) {
1371        let series_id = OptionSeriesId::new_derived(
1372            Venue::from("DERIBIT"),
1373            "BTC".into(),
1374            "USD".into(),
1375            UnixNanos::from(37),
1376        );
1377        let range = StrikeRange::Fixed(vec![Price::from("50000.00")]);
1378        let command_id = UUID4::new();
1379        let command = SubscribeOptionChain::new(
1380            series_id,
1381            range.clone(),
1382            interval,
1383            command_id,
1384            UnixNanos::from(19),
1385            Some(ClientId::from("SOURCE")),
1386            Some(Venue::from("DERIBIT")),
1387            None,
1388        )
1389        .unwrap();
1390        assert_eq!(command.series_id, series_id);
1391        assert_eq!(command.strike_range, range);
1392        assert_eq!(command.snapshot_interval_ms, interval);
1393        assert_eq!(command.command_id, command_id);
1394        assert_eq!(command.ts_init, UnixNanos::from(19));
1395        assert_eq!(command.client_id, Some(ClientId::from("SOURCE")));
1396        assert_eq!(command.venue, Some(Venue::from("DERIBIT")));
1397        assert_eq!(command.correlation_id, None);
1398        assert_eq!(command.params, None);
1399    }
1400
1401    #[rstest]
1402    fn test_option_chain_command_rejects_zero_interval() {
1403        let series_id = OptionSeriesId::new_derived(
1404            Venue::from("DERIBIT"),
1405            "BTC".into(),
1406            "USD".into(),
1407            UnixNanos::from(37),
1408        );
1409        let error = SubscribeOptionChain::new(
1410            series_id,
1411            StrikeRange::Fixed(vec![]),
1412            Some(0),
1413            UUID4::new(),
1414            UnixNanos::from(19),
1415            None,
1416            Some(Venue::from("DERIBIT")),
1417            None,
1418        )
1419        .unwrap_err();
1420        assert_eq!(
1421            error.to_string(),
1422            "invalid u64 for 'snapshot_interval_ms' not positive, was 0",
1423        );
1424    }
1425}