bybit/models/
ticker_request.rs

1use crate::prelude::*;
2
3/// Parameters for requesting ticker information.
4///
5/// This struct defines the parameters for querying ticker data via the `/v5/market/tickers` endpoint.
6/// Ticker data includes the latest price snapshot, best bid/ask price, and trading volume in the last 24 hours.
7#[derive(Clone, Default)]
8pub struct TickerRequest<'a> {
9    /// The product category (e.g., Linear, Inverse, Spot, Option).
10    ///
11    /// Specifies the instrument type. This parameter is required for all ticker requests.
12    pub category: Category,
13
14    /// The trading pair symbol (e.g., "BTCUSDT").
15    ///
16    /// Optionally specifies a single trading pair. If unset, the API returns data for all instruments
17    /// in the category. For `option` category, either `symbol` or `base_coin` must be provided.
18    pub symbol: Option<Cow<'a, str>>,
19
20    /// Base coin, uppercase only.
21    ///
22    /// Applies to `option` category only. When querying options, either `symbol` or `base_coin` must be provided.
23    /// This parameter is ignored for other categories.
24    pub base_coin: Option<Cow<'a, str>>,
25
26    /// Expiry date for options contracts.
27    ///
28    /// Applies to `option` category only. Format: e.g., "25DEC22". Used to filter options by expiry date.
29    /// This parameter is ignored for other categories.
30    pub exp_date: Option<Cow<'a, str>>,
31}
32
33impl<'a> TickerRequest<'a> {
34    /// Creates a default Ticker request.
35    ///
36    /// Returns a request with `category` set to `Linear` and `symbol` set to `"BTCUSDT"`.
37    /// Suitable for testing but should be customized for production to match specific trading needs.
38    pub fn default() -> TickerRequest<'a> {
39        TickerRequest::new(Category::Linear, Some("BTCUSDT"), None, None)
40    }
41
42    /// Constructs a new Ticker request with specified parameters.
43    ///
44    /// Allows full customization. Bots should use this to tailor requests to their strategy,
45    /// ensuring `category` and `symbol` align with the instruments being traded.
46    pub fn new(
47        category: Category,
48        symbol: Option<&'a str>,
49        base_coin: Option<&'a str>,
50        exp_date: Option<&'a str>,
51    ) -> TickerRequest<'a> {
52        TickerRequest {
53            category,
54            symbol: symbol.map(Cow::Borrowed),
55            base_coin: base_coin.map(Cow::Borrowed),
56            exp_date: exp_date.map(Cow::Borrowed),
57        }
58    }
59
60    /// Validates the request parameters according to API constraints.
61    ///
62    /// Returns `Ok(())` if the request is valid, or `Err(String)` with an error message.
63    pub fn validate(&self) -> Result<(), String> {
64        // For option category, either symbol or base_coin must be provided
65        if self.category == Category::Option && self.symbol.is_none() && self.base_coin.is_none() {
66            return Err(
67                "Option category requires either symbol or base_coin parameter".to_string(),
68            );
69        }
70
71        Ok(())
72    }
73
74    /// Creates a request for linear perpetual futures.
75    ///
76    /// Convenience method for creating requests for USDT-margined perpetual futures.
77    pub fn linear(symbol: Option<&'a str>) -> TickerRequest<'a> {
78        TickerRequest::new(Category::Linear, symbol, None, None)
79    }
80
81    /// Creates a request for inverse perpetual futures.
82    ///
83    /// Convenience method for creating requests for coin-margined perpetual futures.
84    pub fn inverse(symbol: Option<&'a str>) -> TickerRequest<'a> {
85        TickerRequest::new(Category::Inverse, symbol, None, None)
86    }
87
88    /// Creates a request for spot trading pairs.
89    ///
90    /// Convenience method for creating requests for spot markets.
91    pub fn spot(symbol: Option<&'a str>) -> TickerRequest<'a> {
92        TickerRequest::new(Category::Spot, symbol, None, None)
93    }
94
95    /// Creates a request for options contracts.
96    ///
97    /// Convenience method for creating requests for options markets.
98    pub fn option(
99        symbol: Option<&'a str>,
100        base_coin: Option<&'a str>,
101        exp_date: Option<&'a str>,
102    ) -> TickerRequest<'a> {
103        TickerRequest::new(Category::Option, symbol, base_coin, exp_date)
104    }
105
106    /// Creates a request for options by base coin.
107    ///
108    /// Convenience method for creating requests for options markets filtered by base coin.
109    pub fn option_by_base_coin(base_coin: &'a str, exp_date: Option<&'a str>) -> TickerRequest<'a> {
110        TickerRequest::new(Category::Option, None, Some(base_coin), exp_date)
111    }
112}
bybit/models/ticker_request.rs

bybit/models/
ticker_request.rs
