bybit/models/
rpi_orderbook_request.rs

1use crate::prelude::*;
2
3/// Parameters for requesting RPI (Real-time Price Improvement) order book data.
4///
5/// This struct defines the parameters for querying the RPI order book via the `/v5/market/rpi_orderbook` endpoint.
6/// The RPI order book shows both regular orders and RPI orders, which can provide price improvement for takers.
7/// RPI orders are special orders that can improve prices when they cross with non-RPI orders.
8#[derive(Clone, Default)]
9pub struct RPIOrderbookRequest<'a> {
10    /// The trading pair symbol (e.g., "BTCUSDT").
11    ///
12    /// Identifies the trading pair. Bots must specify a valid symbol to fetch the correct RPI order book.
13    /// This parameter is required.
14    pub symbol: Cow<'a, str>,
15
16    /// The product category (e.g., spot, linear, inverse).
17    ///
18    /// Specifies the instrument type. According to the Bybit API documentation, this parameter is optional.
19    /// If not specified, the API will return data for the appropriate category based on the symbol.
20    pub category: Option<Category>,
21
22    /// The maximum number of order book levels to return for each side (1-50).
23    ///
24    /// Controls the depth of the RPI order book (number of bid/ask levels).
25    /// This parameter is required and must be between 1 and 50 inclusive.
26    /// RPI order books are limited to 50 levels maximum.
27    pub limit: u64,
28}
29
30impl<'a> RPIOrderbookRequest<'a> {
31    /// Creates a default RPIOrderbook request.
32    ///
33    /// Returns a request with `symbol` set to `"BTCUSDT"`, no category, and `limit` set to 50.
34    /// Suitable for testing but should be customized for production.
35    pub fn default() -> RPIOrderbookRequest<'a> {
36        RPIOrderbookRequest::new("BTCUSDT", None, 50)
37    }
38
39    /// Constructs a new RPIOrderbook request with specified parameters.
40    ///
41    /// Allows customization. Bots should use this to specify the exact symbol, optional category, and limit
42    /// for their RPI order book requests.
43    ///
44    /// # Arguments
45    ///
46    /// * `symbol` - The trading pair symbol (e.g., "BTCUSDT")
47    /// * `category` - Optional product category (spot, linear, inverse)
48    /// * `limit` - Number of order book levels to return (1-50)
49    ///
50    /// # Panics
51    ///
52    /// Panics if `limit` is not between 1 and 50 inclusive.
53    pub fn new(symbol: &'a str, category: Option<Category>, limit: u64) -> RPIOrderbookRequest<'a> {
54        // Validate limit parameter
55        if limit == 0 || limit > 50 {
56            panic!("RPI orderbook limit must be between 1 and 50 inclusive");
57        }
58
59        RPIOrderbookRequest {
60            symbol: Cow::Borrowed(symbol),
61            category,
62            limit,
63        }
64    }
65
66    /// Constructs a new RPIOrderbook request with specified parameters, returning a Result.
67    ///
68    /// Similar to `new`, but returns a Result instead of panicking on invalid parameters.
69    /// This is the recommended method for production code.
70    ///
71    /// # Arguments
72    ///
73    /// * `symbol` - The trading pair symbol (e.g., "BTCUSDT")
74    /// * `category` - Optional product category (spot, linear, inverse)
75    /// * `limit` - Number of order book levels to return (1-50)
76    ///
77    /// # Returns
78    ///
79    /// Returns `Ok(RPIOrderbookRequest)` if parameters are valid, or `Err(String)` with an error message.
80    pub fn try_new(
81        symbol: &'a str,
82        category: Option<Category>,
83        limit: u64,
84    ) -> Result<RPIOrderbookRequest<'a>, String> {
85        // Validate limit parameter
86        if limit == 0 || limit > 50 {
87            return Err("RPI orderbook limit must be between 1 and 50 inclusive".to_string());
88        }
89
90        Ok(RPIOrderbookRequest {
91            symbol: Cow::Borrowed(symbol),
92            category,
93            limit,
94        })
95    }
96
97    /// Creates an RPIOrderbookRequest for spot trading.
98    ///
99    /// Convenience method for creating requests for spot markets.
100    pub fn spot(symbol: &'a str, limit: u64) -> Result<RPIOrderbookRequest<'a>, String> {
101        Self::try_new(symbol, Some(Category::Spot), limit)
102    }
103
104    /// Creates an RPIOrderbookRequest for linear perpetual futures.
105    ///
106    /// Convenience method for creating requests for USDT-margined perpetual futures.
107    pub fn linear(symbol: &'a str, limit: u64) -> Result<RPIOrderbookRequest<'a>, String> {
108        Self::try_new(symbol, Some(Category::Linear), limit)
109    }
110
111    /// Creates an RPIOrderbookRequest for inverse perpetual futures.
112    ///
113    /// Convenience method for creating requests for coin-margined perpetual futures.
114    pub fn inverse(symbol: &'a str, limit: u64) -> Result<RPIOrderbookRequest<'a>, String> {
115        Self::try_new(symbol, Some(Category::Inverse), limit)
116    }
117}
bybit/models/rpi_orderbook_request.rs

bybit/models/
rpi_orderbook_request.rs
