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

nautilus_bybit/common/
symbol.rs
