rust_okx/api/market/
api.rs

1use crate::client::OkxClient;
2use crate::error::Error;
3use crate::model::InstType;
4use crate::transport::Transport;
5
6use super::endpoints::*;
7use super::internal::*;
8use super::requests::*;
9use super::responses::*;
10
11/// Accessor for the public market-data endpoints.
12///
13/// Obtain one via [`OkxClient::market`](crate::OkxClient::market).
14pub struct Market<'a, T> {
15    client: &'a OkxClient<T>,
16}
17
18impl<'a, T: Transport> Market<'a, T> {
19    pub(crate) fn new(client: &'a OkxClient<T>) -> Self {
20        Self { client }
21    }
22
23    /// Retrieve the latest ticker for a single instrument.
24    ///
25    /// `GET /api/v5/market/ticker`. Public (unauthenticated). The returned
26    /// vector contains exactly one [`Ticker`].
27    ///
28    /// # Errors
29    ///
30    /// Returns [`Error::Api`] on a non-zero OKX code, or
31    /// [`Error::Transport`]/[`Error::Decode`] on transport/parsing failure.
32    pub async fn get_ticker(&self, inst_id: &str) -> Result<Vec<Ticker>, Error> {
33        let query = InstIdQuery { inst_id };
34        self.client.get(TICKER, &query, false).await
35    }
36
37    /// Retrieve tickers for an instrument type.
38    ///
39    /// `GET /api/v5/market/tickers`. Public. `underlying` and `inst_family`
40    /// are useful for derivatives and omitted when `None`.
41    ///
42    /// # Errors
43    ///
44    /// See [`get_ticker`](Self::get_ticker).
45    pub async fn get_tickers(
46        &self,
47        inst_type: InstType,
48        inst_family: Option<&str>,
49    ) -> Result<Vec<Ticker>, Error> {
50        let query = TickersQuery {
51            inst_type: &inst_type,
52            inst_family,
53        };
54        self.client.get(TICKERS, &query, false).await
55    }
56
57    /// Retrieve index tickers.
58    ///
59    /// `GET /api/v5/market/index-tickers`. Public. Filter by quote currency,
60    /// index instrument ID, or neither.
61    ///
62    /// # Errors
63    ///
64    /// See [`get_ticker`](Self::get_ticker).
65    pub async fn get_index_tickers(
66        &self,
67        quote_ccy: Option<&str>,
68        inst_id: Option<&str>,
69    ) -> Result<Vec<IndexTicker>, Error> {
70        let query = IndexTickersQuery { quote_ccy, inst_id };
71        self.client.get(INDEX_TICKERS, &query, false).await
72    }
73
74    /// Retrieve the order book for an instrument.
75    ///
76    /// `GET /api/v5/market/books`. `depth` is the number of levels per side
77    /// (OKX default 1, max 400). Public.
78    ///
79    /// # Errors
80    ///
81    /// See [`get_ticker`](Self::get_ticker).
82    pub async fn get_orderbook(
83        &self,
84        inst_id: &str,
85        depth: Option<u32>,
86    ) -> Result<Vec<OrderBook>, Error> {
87        let query = OrderBookQuery { inst_id, sz: depth };
88        self.client.get(BOOKS, &query, false).await
89    }
90
91    /// Retrieve candlestick (OHLCV) data.
92    ///
93    /// `GET /api/v5/market/candles`. `bar` is the bar size, e.g. `1m`, `1H`,
94    /// `1D` (OKX default `1m`). `limit` caps the number of bars (max 300).
95    /// Public.
96    ///
97    /// # Errors
98    ///
99    /// See [`get_ticker`](Self::get_ticker).
100    pub async fn get_candlesticks(
101        &self,
102        inst_id: &str,
103        bar: Option<&str>,
104        limit: Option<u32>,
105    ) -> Result<Vec<Candle>, Error> {
106        let query = CandlesQuery {
107            inst_id,
108            bar,
109            limit,
110        };
111        self.client.get(CANDLES, &query, false).await
112    }
113
114    /// Retrieve historical candlestick data for top currencies.
115    ///
116    /// `GET /api/v5/market/history-candles`. Public.
117    ///
118    /// # Errors
119    ///
120    /// See [`get_ticker`](Self::get_ticker).
121    pub async fn get_history_candlesticks(
122        &self,
123        request: &CandlesticksRequest,
124    ) -> Result<Vec<Candle>, Error> {
125        self.client.get(HISTORY_CANDLES, request, false).await
126    }
127
128    /// Retrieve index candlestick data.
129    ///
130    /// `GET /api/v5/market/index-candles`. Public.
131    ///
132    /// # Errors
133    ///
134    /// See [`get_ticker`](Self::get_ticker).
135    pub async fn get_index_candlesticks(
136        &self,
137        request: &CandlesticksRequest,
138    ) -> Result<Vec<IndexCandle>, Error> {
139        self.client.get(INDEX_CANDLES, request, false).await
140    }
141
142    /// Retrieve mark-price candlestick data.
143    ///
144    /// `GET /api/v5/market/mark-price-candles`. Public.
145    ///
146    /// # Errors
147    ///
148    /// See [`get_ticker`](Self::get_ticker).
149    pub async fn get_mark_price_candlesticks(
150        &self,
151        request: &CandlesticksRequest,
152    ) -> Result<Vec<IndexCandle>, Error> {
153        self.client.get(MARK_PRICE_CANDLES, request, false).await
154    }
155
156    /// Retrieve recent trades for an instrument.
157    ///
158    /// `GET /api/v5/market/trades`. Public.
159    ///
160    /// # Errors
161    ///
162    /// See [`get_ticker`](Self::get_ticker).
163    pub async fn get_trades(
164        &self,
165        inst_id: &str,
166        limit: Option<u32>,
167    ) -> Result<Vec<MarketTrade>, Error> {
168        let query = TradesQuery { inst_id, limit };
169        self.client.get(TRADES, &query, false).await
170    }
171
172    /// Retrieve historical trades for an instrument.
173    ///
174    /// `GET /api/v5/market/history-trades`. Public.
175    ///
176    /// # Errors
177    ///
178    /// See [`get_ticker`](Self::get_ticker).
179    pub async fn get_history_trades(
180        &self,
181        request: &HistoryTradesRequest,
182    ) -> Result<Vec<MarketTrade>, Error> {
183        self.client.get(HISTORY_TRADES, request, false).await
184    }
185
186    /// Retrieve OKX platform 24-hour volume.
187    ///
188    /// `GET /api/v5/market/platform-24-volume`. Public.
189    ///
190    /// # Errors
191    ///
192    /// See [`get_ticker`](Self::get_ticker).
193    pub async fn get_platform_24_volume(&self) -> Result<Vec<PlatformVolume>, Error> {
194        self.client.get(PLATFORM_24_VOLUME, &NoQuery, false).await
195    }
196
197    /// Retrieve index components.
198    ///
199    /// `GET /api/v5/market/index-components`. Public.
200    ///
201    /// # Errors
202    ///
203    /// See [`get_ticker`](Self::get_ticker).
204    pub async fn get_index_components(&self, index: &str) -> Result<Vec<IndexComponents>, Error> {
205        let query = IndexComponentsQuery { index };
206        self.client.get(INDEX_COMPONENTS, &query, false).await
207    }
208
209    /// Retrieve the USD/CNY exchange rate used by OKX.
210    ///
211    /// `GET /api/v5/market/exchange-rate`. Public.
212    ///
213    /// # Errors
214    ///
215    /// See [`get_ticker`](Self::get_ticker).
216    pub async fn get_exchange_rate(&self) -> Result<Vec<ExchangeRate>, Error> {
217        self.client.get(EXCHANGE_RATE, &NoQuery, false).await
218    }
219
220    /// Retrieve a block-trading ticker for a single instrument.
221    ///
222    /// `GET /api/v5/market/block-ticker`. Public.
223    ///
224    /// # Errors
225    ///
226    /// See [`get_ticker`](Self::get_ticker).
227    pub async fn get_block_ticker(&self, inst_id: &str) -> Result<Vec<BlockTicker>, Error> {
228        let query = InstIdQuery { inst_id };
229        self.client.get(BLOCK_TICKER, &query, false).await
230    }
231
232    /// Retrieve block-trading tickers for an instrument type.
233    ///
234    /// `GET /api/v5/market/block-tickers`. Public.
235    ///
236    /// # Errors
237    ///
238    /// See [`get_ticker`](Self::get_ticker).
239    pub async fn get_block_tickers(
240        &self,
241        inst_type: InstType,
242        inst_family: Option<&str>,
243    ) -> Result<Vec<BlockTicker>, Error> {
244        let query = TickersQuery {
245            inst_type: &inst_type,
246            inst_family,
247        };
248        self.client.get(BLOCK_TICKERS, &query, false).await
249    }
250
251    /// Retrieve option trades aggregated by instrument family.
252    ///
253    /// `GET /api/v5/market/option/instrument-family-trades`. Public.
254    ///
255    /// # Errors
256    ///
257    /// See [`get_ticker`](Self::get_ticker).
258    pub async fn get_option_instrument_family_trades(
259        &self,
260        inst_family: &str,
261    ) -> Result<Vec<OptionFamilyTradeGroup>, Error> {
262        let query = InstFamilyQuery { inst_family };
263        self.client
264            .get(OPTION_INSTRUMENT_FAMILY_TRADES, &query, false)
265            .await
266    }
267}
rust_okx/api/market/api.rs

rust_okx/api/market/
api.rs
