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

nautilus_okx/
config.rs
