nautilus_bybit/common/
symbol.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2025 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//! Helpers for working with Bybit-specific symbol strings.
17
18use std::{
19    borrow::Cow,
20    fmt::{Display, Formatter},
21};
22
23use nautilus_model::identifiers::{InstrumentId, Symbol};
24use ustr::Ustr;
25
26use super::{consts::BYBIT_VENUE, enums::BybitProductType};
27
28const VALID_SUFFIXES: &[&str] = &["-SPOT", "-LINEAR", "-INVERSE", "-OPTION"];
29
30/// Returns true if the supplied value contains a recognised Bybit product suffix.
31fn has_valid_suffix(value: &str) -> bool {
32    VALID_SUFFIXES.iter().any(|suffix| value.contains(suffix))
33}
34
35/// Represents a Bybit symbol augmented with a product-type suffix.
36#[derive(Clone, Debug, Eq, PartialEq, Hash)]
37pub struct BybitSymbol {
38    value: Ustr,
39}
40
41impl BybitSymbol {
42    /// Creates a new [`BybitSymbol`] after validating the suffix and normalising to upper case.
43    ///
44    /// # Errors
45    ///
46    /// Returns an error if the value does not contain one of the recognised Bybit suffixes.
47    pub fn new<S: AsRef<str>>(value: S) -> anyhow::Result<Self> {
48        let value_ref = value.as_ref();
49        let needs_upper = value_ref.bytes().any(|b| b.is_ascii_lowercase());
50        let normalised: Cow<'_, str> = if needs_upper {
51            Cow::Owned(value_ref.to_ascii_uppercase())
52        } else {
53            Cow::Borrowed(value_ref)
54        };
55        anyhow::ensure!(
56            has_valid_suffix(normalised.as_ref()),
57            "invalid Bybit symbol '{value_ref}': expected suffix in {VALID_SUFFIXES:?}"
58        );
59        Ok(Self {
60            value: Ustr::from(normalised.as_ref()),
61        })
62    }
63
64    /// Returns the underlying symbol without the Bybit suffix.
65    #[must_use]
66    pub fn raw_symbol(&self) -> &str {
67        self.value
68            .rsplit_once('-')
69            .map(|(prefix, _)| prefix)
70            .unwrap_or(self.value.as_str())
71    }
72
73    /// Returns the product type identified by the suffix.
74    #[must_use]
75    pub fn product_type(&self) -> BybitProductType {
76        if self.value.ends_with("-SPOT") {
77            BybitProductType::Spot
78        } else if self.value.ends_with("-LINEAR") {
79            BybitProductType::Linear
80        } else if self.value.ends_with("-INVERSE") {
81            BybitProductType::Inverse
82        } else if self.value.ends_with("-OPTION") {
83            BybitProductType::Option
84        } else {
85            unreachable!("symbol checked for suffix during construction")
86        }
87    }
88
89    /// Returns the instrument identifier corresponding to this symbol.
90    #[must_use]
91    pub fn to_instrument_id(&self) -> InstrumentId {
92        InstrumentId::new(Symbol::from_ustr_unchecked(self.value), *BYBIT_VENUE)
93    }
94
95    /// Returns the symbol value as `Ustr`.
96    #[must_use]
97    pub fn as_ustr(&self) -> Ustr {
98        self.value
99    }
100}
101
102impl Display for BybitSymbol {
103    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
104        f.write_str(self.value.as_str())
105    }
106}
107
108impl TryFrom<&str> for BybitSymbol {
109    type Error = anyhow::Error;
110
111    fn try_from(value: &str) -> anyhow::Result<Self> {
112        Self::new(value)
113    }
114}
115
116impl TryFrom<String> for BybitSymbol {
117    type Error = anyhow::Error;
118
119    fn try_from(value: String) -> anyhow::Result<Self> {
120        Self::new(value)
121    }
122}
123
124////////////////////////////////////////////////////////////////////////////////
125// Tests
126////////////////////////////////////////////////////////////////////////////////
127
128#[cfg(test)]
129mod tests {
130    use rstest::rstest;
131
132    use super::*;
133
134    #[rstest]
135    fn new_valid_symbol_is_uppercased() {
136        let symbol = BybitSymbol::new("btcusdt-linear").unwrap();
137        assert_eq!(symbol.to_string(), "BTCUSDT-LINEAR");
138    }
139
140    #[rstest]
141    fn new_invalid_symbol_errors() {
142        let err = BybitSymbol::new("BTCUSDT").unwrap_err();
143        assert!(format!("{err}").contains("expected suffix"));
144    }
145
146    #[rstest]
147    fn raw_symbol_strips_suffix() {
148        let symbol = BybitSymbol::new("ETH-26JUN26-16000-P-OPTION").unwrap();
149        assert_eq!(symbol.raw_symbol(), "ETH-26JUN26-16000-P");
150    }
151
152    #[rstest]
153    fn product_type_detection_matches_suffix() {
154        let linear = BybitSymbol::new("BTCUSDT-LINEAR").unwrap();
155        assert!(linear.product_type().is_linear());
156
157        let inverse = BybitSymbol::new("BTCUSD-INVERSE").unwrap();
158        assert!(inverse.product_type().is_inverse());
159
160        let spot = BybitSymbol::new("ETHUSDT-SPOT").unwrap();
161        assert!(spot.product_type().is_spot());
162
163        let option = BybitSymbol::new("ETH-26JUN26-16000-P-OPTION").unwrap();
164        assert!(option.product_type().is_option());
165    }
166
167    #[rstest]
168    fn instrument_id_uses_bybit_venue() {
169        let symbol = BybitSymbol::new("BTCUSDT-LINEAR").unwrap();
170        let instrument_id = symbol.to_instrument_id();
171        assert_eq!(instrument_id.to_string(), "BTCUSDT-LINEAR.BYBIT");
172    }
173}
nautilus_bybit/common/symbol.rs

nautilus_bybit/common/
symbol.rs
