nautilus_okx/config.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//! Configuration structures for the OKX adapter.
17
18use nautilus_model::identifiers::{AccountId, TraderId};
19
20use crate::common::{
21 enums::{OKXContractType, OKXInstrumentType, OKXMarginMode, OKXVipLevel},
22 urls::{
23 get_http_base_url, get_ws_base_url_business, get_ws_base_url_private,
24 get_ws_base_url_public,
25 },
26};
27
28/// Configuration for the OKX data client.
29#[derive(Clone, Debug)]
30pub struct OKXDataClientConfig {
31 /// Optional API key for authenticated endpoints.
32 pub api_key: Option<String>,
33 /// Optional API secret for authenticated endpoints.
34 pub api_secret: Option<String>,
35 /// Optional API passphrase for authenticated endpoints.
36 pub api_passphrase: Option<String>,
37 /// Instrument types to load and subscribe to.
38 pub instrument_types: Vec<OKXInstrumentType>,
39 /// Contract type filter applied to loaded instruments.
40 pub contract_types: Option<Vec<OKXContractType>>,
41 /// Instrument families to load (e.g., "BTC-USD", "ETH-USD").
42 /// Required for OPTIONS. Optional for FUTURES/SWAP. Not applicable for SPOT/MARGIN.
43 pub instrument_families: Option<Vec<String>>,
44 /// Optional override for the HTTP base URL.
45 pub base_url_http: Option<String>,
46 /// Optional override for the public WebSocket URL.
47 pub base_url_ws_public: Option<String>,
48 /// Optional override for the business WebSocket URL.
49 pub base_url_ws_business: Option<String>,
50 /// Optional HTTP proxy URL.
51 pub http_proxy_url: Option<String>,
52 /// Optional WebSocket proxy URL.
53 ///
54 /// Note: WebSocket proxy support is not yet implemented. This field is reserved
55 /// for future functionality. Use `http_proxy_url` for REST API proxy support.
56 pub ws_proxy_url: Option<String>,
57 /// When true the client will use OKX demo endpoints.
58 pub is_demo: bool,
59 /// Optional HTTP timeout in seconds.
60 pub http_timeout_secs: Option<u64>,
61 /// Optional maximum retry attempts for requests.
62 pub max_retries: Option<u32>,
63 /// Optional initial retry delay in milliseconds.
64 pub retry_delay_initial_ms: Option<u64>,
65 /// Optional maximum retry delay in milliseconds.
66 pub retry_delay_max_ms: Option<u64>,
67 /// Optional interval for refreshing instruments.
68 pub update_instruments_interval_mins: Option<u64>,
69 /// Optional VIP level that unlocks additional subscriptions.
70 pub vip_level: Option<OKXVipLevel>,
71}
72
73impl Default for OKXDataClientConfig {
74 fn default() -> Self {
75 Self {
76 api_key: None,
77 api_secret: None,
78 api_passphrase: None,
79 instrument_types: vec![OKXInstrumentType::Spot],
80 contract_types: None,
81 instrument_families: None,
82 base_url_http: None,
83 base_url_ws_public: None,
84 base_url_ws_business: None,
85 http_proxy_url: None,
86 ws_proxy_url: None,
87 is_demo: false,
88 http_timeout_secs: Some(60),
89 max_retries: Some(3),
90 retry_delay_initial_ms: Some(1_000),
91 retry_delay_max_ms: Some(10_000),
92 update_instruments_interval_mins: Some(60),
93 vip_level: None,
94 }
95 }
96}
97
98impl OKXDataClientConfig {
99 /// Creates a new configuration with default settings.
100 #[must_use]
101 pub fn new() -> Self {
102 Self::default()
103 }
104
105 /// Returns `true` when all API credential fields are available (in config or env vars).
106 #[must_use]
107 pub fn has_api_credentials(&self) -> bool {
108 let has_key = self.api_key.is_some() || std::env::var("OKX_API_KEY").is_ok();
109 let has_secret = self.api_secret.is_some() || std::env::var("OKX_API_SECRET").is_ok();
110 let has_passphrase =
111 self.api_passphrase.is_some() || std::env::var("OKX_API_PASSPHRASE").is_ok();
112 has_key && has_secret && has_passphrase
113 }
114
115 /// Returns the HTTP base URL, falling back to the default when unset.
116 #[must_use]
117 pub fn http_base_url(&self) -> String {
118 self.base_url_http
119 .clone()
120 .unwrap_or_else(|| get_http_base_url().to_string())
121 }
122
123 /// Returns the public WebSocket URL, respecting the demo flag and overrides.
124 #[must_use]
125 pub fn ws_public_url(&self) -> String {
126 self.base_url_ws_public
127 .clone()
128 .unwrap_or_else(|| get_ws_base_url_public(self.is_demo).to_string())
129 }
130
131 /// Returns the business WebSocket URL, respecting the demo flag and overrides.
132 #[must_use]
133 pub fn ws_business_url(&self) -> String {
134 self.base_url_ws_business
135 .clone()
136 .unwrap_or_else(|| get_ws_base_url_business(self.is_demo).to_string())
137 }
138
139 /// Returns `true` when the business WebSocket should be instantiated.
140 #[must_use]
141 pub fn requires_business_ws(&self) -> bool {
142 self.has_api_credentials()
143 }
144}
145
146/// Configuration for the OKX execution client.
147#[derive(Clone, Debug)]
148pub struct OKXExecClientConfig {
149 /// The trader ID for the client.
150 pub trader_id: TraderId,
151 /// The account ID for the client.
152 pub account_id: AccountId,
153 /// Optional API key for authenticated endpoints.
154 pub api_key: Option<String>,
155 /// Optional API secret for authenticated endpoints.
156 pub api_secret: Option<String>,
157 /// Optional API passphrase for authenticated endpoints.
158 pub api_passphrase: Option<String>,
159 /// Instrument types the execution client should support.
160 pub instrument_types: Vec<OKXInstrumentType>,
161 /// Contract type filter applied to operations.
162 pub contract_types: Option<Vec<OKXContractType>>,
163 /// Instrument families to load (e.g., "BTC-USD", "ETH-USD").
164 /// Required for OPTIONS. Optional for FUTURES/SWAP. Not applicable for SPOT/MARGIN.
165 pub instrument_families: Option<Vec<String>>,
166 /// Optional override for the HTTP base URL.
167 pub base_url_http: Option<String>,
168 /// Optional override for the private WebSocket URL.
169 pub base_url_ws_private: Option<String>,
170 /// Optional override for the business WebSocket URL.
171 pub base_url_ws_business: Option<String>,
172 /// Optional HTTP proxy URL.
173 pub http_proxy_url: Option<String>,
174 /// Optional WebSocket proxy URL.
175 ///
176 /// Note: WebSocket proxy support is not yet implemented. This field is reserved
177 /// for future functionality. Use `http_proxy_url` for REST API proxy support.
178 pub ws_proxy_url: Option<String>,
179 /// When true the client will use OKX demo endpoints.
180 pub is_demo: bool,
181 /// Optional HTTP timeout in seconds.
182 pub http_timeout_secs: Option<u64>,
183 /// Enables consumption of the fills WebSocket channel when true.
184 pub use_fills_channel: bool,
185 /// Enables mass-cancel support when true.
186 pub use_mm_mass_cancel: bool,
187 /// Optional maximum retry attempts for requests.
188 pub max_retries: Option<u32>,
189 /// Optional initial retry delay in milliseconds.
190 pub retry_delay_initial_ms: Option<u64>,
191 /// Optional maximum retry delay in milliseconds.
192 pub retry_delay_max_ms: Option<u64>,
193 /// Optional margin mode (CROSS or ISOLATED) for margin/derivative accounts.
194 pub margin_mode: Option<OKXMarginMode>,
195 /// Enables margin/leverage for SPOT trading when true.
196 pub use_spot_margin: bool,
197}
198
199impl Default for OKXExecClientConfig {
200 fn default() -> Self {
201 Self {
202 trader_id: TraderId::from("TRADER-001"),
203 account_id: AccountId::from("OKX-001"),
204 api_key: None,
205 api_secret: None,
206 api_passphrase: None,
207 instrument_types: vec![OKXInstrumentType::Spot],
208 contract_types: None,
209 instrument_families: None,
210 base_url_http: None,
211 base_url_ws_private: None,
212 base_url_ws_business: None,
213 http_proxy_url: None,
214 ws_proxy_url: None,
215 is_demo: false,
216 http_timeout_secs: Some(60),
217 use_fills_channel: false,
218 use_mm_mass_cancel: false,
219 max_retries: Some(3),
220 retry_delay_initial_ms: Some(1_000),
221 retry_delay_max_ms: Some(10_000),
222 margin_mode: None,
223 use_spot_margin: false,
224 }
225 }
226}
227
228impl OKXExecClientConfig {
229 /// Creates a new configuration with default settings.
230 #[must_use]
231 pub fn new() -> Self {
232 Self::default()
233 }
234
235 /// Returns `true` when all API credential fields are available (in config or env vars).
236 #[must_use]
237 pub fn has_api_credentials(&self) -> bool {
238 let has_key = self.api_key.is_some() || std::env::var("OKX_API_KEY").is_ok();
239 let has_secret = self.api_secret.is_some() || std::env::var("OKX_API_SECRET").is_ok();
240 let has_passphrase =
241 self.api_passphrase.is_some() || std::env::var("OKX_API_PASSPHRASE").is_ok();
242 has_key && has_secret && has_passphrase
243 }
244
245 /// Returns the HTTP base URL, falling back to the default when unset.
246 #[must_use]
247 pub fn http_base_url(&self) -> String {
248 self.base_url_http
249 .clone()
250 .unwrap_or_else(|| get_http_base_url().to_string())
251 }
252
253 /// Returns the private WebSocket URL, respecting the demo flag and overrides.
254 #[must_use]
255 pub fn ws_private_url(&self) -> String {
256 self.base_url_ws_private
257 .clone()
258 .unwrap_or_else(|| get_ws_base_url_private(self.is_demo).to_string())
259 }
260
261 /// Returns the business WebSocket URL, respecting the demo flag and overrides.
262 #[must_use]
263 pub fn ws_business_url(&self) -> String {
264 self.base_url_ws_business
265 .clone()
266 .unwrap_or_else(|| get_ws_base_url_business(self.is_demo).to_string())
267 }
268}