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 the lightweight order book for an instrument.
92    ///
93    /// `GET /api/v5/market/books-lite`. Public.
94    ///
95    /// # Errors
96    ///
97    /// See [`get_ticker`](Self::get_ticker).
98    pub async fn get_order_lite_book(&self, inst_id: &str) -> Result<Vec<OrderBook>, Error> {
99        let query = InstIdQuery { inst_id };
100        self.client.get(BOOKS_LITE, &query, false).await
101    }
102
103    /// Retrieve candlestick (OHLCV) data.
104    ///
105    /// `GET /api/v5/market/candles`. `bar` is the bar size, e.g. `1m`, `1H`,
106    /// `1D` (OKX default `1m`). `limit` caps the number of bars (max 300).
107    /// Public.
108    ///
109    /// # Errors
110    ///
111    /// See [`get_ticker`](Self::get_ticker).
112    pub async fn get_candlesticks(
113        &self,
114        inst_id: &str,
115        bar: Option<&str>,
116        limit: Option<u32>,
117    ) -> Result<Vec<Candle>, Error> {
118        let query = CandlesQuery {
119            inst_id,
120            bar,
121            limit,
122        };
123        self.client.get(CANDLES, &query, false).await
124    }
125
126    /// Retrieve historical candlestick data for top currencies.
127    ///
128    /// `GET /api/v5/market/history-candles`. Public.
129    ///
130    /// # Errors
131    ///
132    /// See [`get_ticker`](Self::get_ticker).
133    pub async fn get_history_candlesticks(
134        &self,
135        request: &CandlesticksRequest,
136    ) -> Result<Vec<Candle>, Error> {
137        self.client.get(HISTORY_CANDLES, request, false).await
138    }
139
140    /// Retrieve index candlestick data.
141    ///
142    /// `GET /api/v5/market/index-candles`. Public.
143    ///
144    /// # Errors
145    ///
146    /// See [`get_ticker`](Self::get_ticker).
147    pub async fn get_index_candlesticks(
148        &self,
149        request: &CandlesticksRequest,
150    ) -> Result<Vec<Candle>, Error> {
151        self.client.get(INDEX_CANDLES, request, false).await
152    }
153
154    /// Retrieve mark-price candlestick data.
155    ///
156    /// `GET /api/v5/market/mark-price-candles`. Public.
157    ///
158    /// # Errors
159    ///
160    /// See [`get_ticker`](Self::get_ticker).
161    pub async fn get_mark_price_candlesticks(
162        &self,
163        request: &CandlesticksRequest,
164    ) -> Result<Vec<Candle>, Error> {
165        self.client.get(MARK_PRICE_CANDLES, request, false).await
166    }
167
168    /// Retrieve recent trades for an instrument.
169    ///
170    /// `GET /api/v5/market/trades`. Public.
171    ///
172    /// # Errors
173    ///
174    /// See [`get_ticker`](Self::get_ticker).
175    pub async fn get_trades(
176        &self,
177        inst_id: &str,
178        limit: Option<u32>,
179    ) -> Result<Vec<MarketTrade>, Error> {
180        let query = TradesQuery { inst_id, limit };
181        self.client.get(TRADES, &query, false).await
182    }
183
184    /// Retrieve historical trades for an instrument.
185    ///
186    /// `GET /api/v5/market/history-trades`. Public.
187    ///
188    /// # Errors
189    ///
190    /// See [`get_ticker`](Self::get_ticker).
191    pub async fn get_history_trades(
192        &self,
193        request: &HistoryTradesRequest,
194    ) -> Result<Vec<MarketTrade>, Error> {
195        self.client.get(HISTORY_TRADES, request, false).await
196    }
197
198    /// Retrieve OKX platform 24-hour volume.
199    ///
200    /// `GET /api/v5/market/platform-24-volume`. Public.
201    ///
202    /// # Errors
203    ///
204    /// See [`get_ticker`](Self::get_ticker).
205    pub async fn get_platform_24_volume(&self) -> Result<Vec<PlatformVolume>, Error> {
206        self.client.get(PLATFORM_24_VOLUME, &NoQuery, false).await
207    }
208
209    /// Retrieve index components.
210    ///
211    /// `GET /api/v5/market/index-components`. Public.
212    ///
213    /// # Errors
214    ///
215    /// See [`get_ticker`](Self::get_ticker).
216    pub async fn get_index_components(&self, index: &str) -> Result<Vec<IndexComponents>, Error> {
217        let query = IndexComponentsQuery { index };
218        self.client.get(INDEX_COMPONENTS, &query, false).await
219    }
220
221    /// Retrieve the USD/CNY exchange rate used by OKX.
222    ///
223    /// `GET /api/v5/market/exchange-rate`. Public.
224    ///
225    /// # Errors
226    ///
227    /// See [`get_ticker`](Self::get_ticker).
228    pub async fn get_exchange_rate(&self) -> Result<Vec<ExchangeRate>, Error> {
229        self.client.get(EXCHANGE_RATE, &NoQuery, false).await
230    }
231
232    /// Retrieve a block-trading ticker for a single instrument.
233    ///
234    /// `GET /api/v5/market/block-ticker`. Public.
235    ///
236    /// # Errors
237    ///
238    /// See [`get_ticker`](Self::get_ticker).
239    pub async fn get_block_ticker(&self, inst_id: &str) -> Result<Vec<BlockTicker>, Error> {
240        let query = InstIdQuery { inst_id };
241        self.client.get(BLOCK_TICKER, &query, false).await
242    }
243
244    /// Retrieve block-trading tickers for an instrument type.
245    ///
246    /// `GET /api/v5/market/block-tickers`. Public.
247    ///
248    /// # Errors
249    ///
250    /// See [`get_ticker`](Self::get_ticker).
251    pub async fn get_block_tickers(
252        &self,
253        inst_type: InstType,
254        inst_family: Option<&str>,
255    ) -> Result<Vec<BlockTicker>, Error> {
256        let query = TickersQuery {
257            inst_type: &inst_type,
258            inst_family,
259        };
260        self.client.get(BLOCK_TICKERS, &query, false).await
261    }
262
263    /// Retrieve recent block trades for an instrument.
264    ///
265    /// `GET /api/v5/market/block-trades`. Public.
266    ///
267    /// # Errors
268    ///
269    /// See [`get_ticker`](Self::get_ticker).
270    pub async fn get_block_trades(
271        &self,
272        inst_id: &str,
273        limit: Option<u32>,
274    ) -> Result<Vec<BlockTrade>, Error> {
275        let query = TradesQuery { inst_id, limit };
276        self.client.get(BLOCK_TRADES, &query, false).await
277    }
278
279    /// Retrieve option trades aggregated by instrument family.
280    ///
281    /// `GET /api/v5/market/option/instrument-family-trades`. Public.
282    ///
283    /// # Errors
284    ///
285    /// See [`get_ticker`](Self::get_ticker).
286    pub async fn get_option_instrument_family_trades(
287        &self,
288        inst_family: &str,
289    ) -> Result<Vec<OptionInstrumentFamilyTrade>, Error> {
290        let query = InstFamilyQuery { inst_family };
291        self.client
292            .get(OPTION_INSTRUMENT_FAMILY_TRADES, &query, false)
293            .await
294    }
295}
rust_okx/api/market/api.rs

rust_okx/api/market/
api.rs
