Struct OKXHttpClient 

pub struct OKXHttpClient { /* private fields */ }

Provides a higher-level HTTP client for the OKX REST API.

This client wraps the underlying OKXHttpInnerClient to handle conversions into the Nautilus domain model.

Implementations

impl OKXHttpClient

pub fn new( base_url: Option<String>, timeout_secs: Option<u64>, max_retries: Option<u32>, retry_delay_ms: Option<u64>, retry_delay_max_ms: Option<u64>, is_demo: bool, proxy_url: Option<String>, ) -> Result<Self>

Creates a new OKXHttpClient using the default OKX HTTP URL, optionally overridden with a custom base url.

This version of the client has no credentials, so it can only call publicly accessible endpoints.

Errors

Returns an error if the retry manager cannot be created.

pub fn from_env() -> Result<Self>

Creates a new authenticated OKXHttpClient using environment variables and the default OKX HTTP base url.

Errors

Returns an error if the operation fails.

pub fn with_credentials( api_key: Option<String>, api_secret: Option<String>, api_passphrase: Option<String>, base_url: Option<String>, timeout_secs: Option<u64>, max_retries: Option<u32>, retry_delay_ms: Option<u64>, retry_delay_max_ms: Option<u64>, is_demo: bool, proxy_url: Option<String>, ) -> Result<Self>

Creates a new OKXHttpClient configured with credentials for authenticated requests, optionally using a custom base url.

Errors

Returns an error if the operation fails.

pub fn cancel_all_requests(&self)

Cancel all pending HTTP requests.

pub fn cancellation_token(&self) -> &CancellationToken

Get the cancellation token for this client.

pub fn base_url(&self) -> &str

Returns the base url being used by the client.

pub fn api_key(&self) -> Option<&str>

Returns the public API key being used by the client.

pub fn api_key_masked(&self) -> Option<String>

Returns a masked version of the API key for logging purposes.

pub fn is_demo(&self) -> bool

Returns whether the client is configured for demo trading.

pub async fn get_server_time(&self) -> Result<u64, OKXHttpError>

Requests the current server time from OKX.

Returns the OKX system time as a Unix timestamp in milliseconds.

Errors

Returns an error if the HTTP request fails or if the response cannot be parsed.

pub fn is_initialized(&self) -> bool

Checks if the client is initialized.

The client is considered initialized if any instruments have been cached from the venue.

pub fn get_cached_symbols(&self) -> Vec<String>

Returns a snapshot of all instrument symbols currently held in the internal cache.

pub fn cache_instruments(&self, instruments: Vec<InstrumentAny>)

Caches multiple instruments.

Any existing instruments with the same symbols will be replaced.

pub fn cache_instrument(&self, instrument: InstrumentAny)

Caches a single instrument.

Any existing instrument with the same symbol will be replaced.

pub fn get_instrument(&self, symbol: &Ustr) -> Option<InstrumentAny>

Gets an instrument from the cache by symbol.

pub async fn request_account_state( &self, account_id: AccountId, ) -> Result<AccountState>

Requests the account state for the account_id from OKX.

Errors

Returns an error if the HTTP request fails or no account state is returned.

pub async fn set_position_mode( &self, position_mode: OKXPositionMode, ) -> Result<()>

Sets the position mode for the account.

Defaults to NetMode if no position mode is provided.

Errors

Returns an error if the HTTP request fails or the position mode cannot be set.

Note

This endpoint only works for accounts with derivatives trading enabled. If the account only has spot trading, this will return an error.

pub async fn request_instruments( &self, instrument_type: OKXInstrumentType, instrument_family: Option<String>, ) -> Result<Vec<InstrumentAny>>

Requests all instruments for the instrument_type from OKX.

Errors

Returns an error if the HTTP request fails or instrument parsing fails.

pub async fn request_instrument( &self, instrument_id: InstrumentId, ) -> Result<InstrumentAny>

Requests a single instrument by instrument_id from OKX.

Fetches the instrument from the API, caches it, and returns it.

Errors

This function will return an error if:

• The API request fails.
• The instrument is not found.
• Failed to parse instrument data.

pub async fn request_mark_price( &self, instrument_id: InstrumentId, ) -> Result<MarkPriceUpdate>

Requests the latest mark price for the instrument_type from OKX.

Errors

Returns an error if the HTTP request fails or no mark price is returned.

pub async fn request_index_price( &self, instrument_id: InstrumentId, ) -> Result<IndexPriceUpdate>

Requests the latest index price for the instrument_id from OKX.

Errors

Returns an error if the HTTP request fails or no index price is returned.

pub async fn request_trades( &self, instrument_id: InstrumentId, start: Option<DateTime<Utc>>, end: Option<DateTime<Utc>>, limit: Option<u32>, ) -> Result<Vec<TradeTick>>

Requests trades for the instrument_id and start -> end time range.

Errors

Returns an error if the HTTP request fails or trade parsing fails.

Panics

Panics if the API returns an empty response when debug logging is enabled.

pub async fn request_bars( &self, bar_type: BarType, start: Option<DateTime<Utc>>, end: Option<DateTime<Utc>>, limit: Option<u32>, ) -> Result<Vec<Bar>>

Requests historical bars for the given bar type and time range.

The aggregation source must be EXTERNAL. Time range validation ensures start < end. Returns bars sorted oldest to newest.

Errors

Returns an error if the request fails.

Endpoint Selection

The OKX API has different endpoints with different limits:

• Regular endpoint (/api/v5/market/candles): ≤ 300 rows/call, ≤ 40 req/2s
  • Used when: start is None OR age ≤ 100 days
• History endpoint (/api/v5/market/history-candles): ≤ 100 rows/call, ≤ 20 req/2s
  • Used when: start is Some AND age > 100 days

Age is calculated as Utc::now() - start at the time of the first request.

Supported Aggregations

Maps to OKX bar query parameter:

• Second → {n}s
• Minute → {n}m
• Hour → {n}H
• Day → {n}D
• Week → {n}W
• Month → {n}M

Pagination

• Uses before parameter for backwards pagination
• Pages backwards from end time (or now) to start time
• Stops when: limit reached, time window covered, or API returns empty
• Rate limit safety: ≥ 50ms between requests

Panics

May panic if internal data structures are in an unexpected state.

References

• https://tr.okx.com/docs-v5/en/#order-book-trading-market-data-get-candlesticks
• https://tr.okx.com/docs-v5/en/#order-book-trading-market-data-get-candlesticks-history

pub async fn request_order_status_reports( &self, account_id: AccountId, instrument_type: Option<OKXInstrumentType>, instrument_id: Option<InstrumentId>, start: Option<DateTime<Utc>>, end: Option<DateTime<Utc>>, open_only: bool, limit: Option<u32>, ) -> Result<Vec<OrderStatusReport>>

Requests historical order status reports for the given parameters.

Errors

Returns an error if the request fails.

References

• https://www.okx.com/docs-v5/en/#order-book-trading-trade-get-order-history-last-7-days.
• https://www.okx.com/docs-v5/en/#order-book-trading-trade-get-order-history-last-3-months.

pub async fn request_fill_reports( &self, account_id: AccountId, instrument_type: Option<OKXInstrumentType>, instrument_id: Option<InstrumentId>, start: Option<DateTime<Utc>>, end: Option<DateTime<Utc>>, limit: Option<u32>, ) -> Result<Vec<FillReport>>

Requests fill reports (transaction details) for the given parameters.

Errors

Returns an error if the request fails.

References

https://www.okx.com/docs-v5/en/#order-book-trading-trade-get-transaction-details-last-3-days.

pub async fn request_position_status_reports( &self, account_id: AccountId, instrument_type: Option<OKXInstrumentType>, instrument_id: Option<InstrumentId>, ) -> Result<Vec<PositionStatusReport>>

Requests current position status reports for the given parameters.

Position Modes

OKX supports two position modes, which affects how position data is returned:

Net Mode (One-way)

• posSide field will be "net"
• pos field uses signed quantities:
  • Positive value = Long position
  • Negative value = Short position
  • Zero = Flat/no position

Long/Short Mode (Hedge/Dual-side)

• posSide field will be "long" or "short"
• pos field is always positive (use posSide to determine actual side)
• Allows holding simultaneous long and short positions on the same instrument
• Position IDs are suffixed with -LONG or -SHORT for uniqueness

Errors

Returns an error if the request fails.

References

https://www.okx.com/docs-v5/en/#trading-account-rest-api-get-positions

pub async fn request_spot_margin_position_reports( &self, account_id: AccountId, ) -> Result<Vec<PositionStatusReport>>

Requests spot margin position status reports from account balance.

Spot margin positions appear in /api/v5/account/balance as balance sheet items with non-zero liab (liability) or spotInUseAmt fields, rather than in the positions endpoint. This method fetches the balance and converts any margin positions into position status reports.

Errors

Returns an error if the request fails or parsing fails.

References

https://www.okx.com/docs-v5/en/#trading-account-rest-api-get-balance

pub async fn place_algo_order( &self, request: OKXPlaceAlgoOrderRequest, ) -> Result<OKXPlaceAlgoOrderResponse, OKXHttpError>

Places an algo order via HTTP.

Errors

Returns an error if the request fails.

References

https://www.okx.com/docs-v5/en/#order-book-trading-algo-trading-post-place-algo-order

pub async fn cancel_algo_order( &self, request: OKXCancelAlgoOrderRequest, ) -> Result<OKXCancelAlgoOrderResponse, OKXHttpError>

Cancels an algo order via HTTP.

Errors

Returns an error if the request fails.

References

https://www.okx.com/docs-v5/en/#order-book-trading-algo-trading-post-cancel-algo-order

pub async fn place_algo_order_with_domain_types( &self, instrument_id: InstrumentId, td_mode: OKXTradeMode, client_order_id: ClientOrderId, order_side: OrderSide, order_type: OrderType, quantity: Quantity, trigger_price: Price, trigger_type: Option<TriggerType>, limit_price: Option<Price>, reduce_only: Option<bool>, ) -> Result<OKXPlaceAlgoOrderResponse, OKXHttpError>

Places an algo order using domain types.

This is a convenience method that accepts Nautilus domain types and builds the appropriate OKX request structure internally.

Errors

Returns an error if the request fails.

pub async fn cancel_algo_order_with_domain_types( &self, instrument_id: InstrumentId, algo_id: String, ) -> Result<OKXCancelAlgoOrderResponse, OKXHttpError>

Cancels an algo order using domain types.

This is a convenience method that accepts Nautilus domain types and builds the appropriate OKX request structure internally.

Errors

Returns an error if the request fails.

pub async fn request_algo_order_status_reports( &self, account_id: AccountId, instrument_type: Option<OKXInstrumentType>, instrument_id: Option<InstrumentId>, algo_id: Option<String>, algo_client_order_id: Option<ClientOrderId>, state: Option<OKXOrderStatus>, limit: Option<u32>, ) -> Result<Vec<OrderStatusReport>>

Requests algo order status reports.

Errors

Returns an error if the request fails.

pub async fn request_algo_order_status_report( &self, account_id: AccountId, instrument_id: InstrumentId, algo_client_order_id: ClientOrderId, ) -> Result<Option<OrderStatusReport>>

Requests an algo order status report by client order identifier.

Errors

Returns an error if the request fails.

pub fn raw_client(&self) -> &Arc<OKXRawHttpClient>

Exposes raw HTTP client for testing purposes

impl OKXHttpClient

pub fn py_base_url(&self) -> &str

pub fn py_api_key(&self) -> Option<&str>

pub fn py_api_key_masked(&self) -> Option<String>

pub fn py_is_initialized(&self) -> bool

pub fn py_get_cached_symbols(&self) -> Vec<String>

pub fn py_cancel_all_requests(&self)

pub fn py_cache_instruments( &self, py: Python<'_>, instruments: Vec<Py<PyAny>>, ) -> PyResult<()>

Errors

Returns a Python exception if adding the instruments to the cache fails.

pub fn py_cache_instrument( &self, py: Python<'_>, instrument: Py<PyAny>, ) -> PyResult<()>

Errors

Returns a Python exception if adding the instrument to the cache fails.

Trait Implementations

impl Clone for OKXHttpClient

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OKXHttpClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for OKXHttpClient

fn default() -> Self

Returns the “default value” for a type.

impl<'py> IntoPyObject<'py> for OKXHttpClient

type Target = OKXHttpClient

The Python output type

type Output = Bound<'py, <OKXHttpClient as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<Self as IntoPyObject<'_>>::Output, <Self as IntoPyObject<'_>>::Error>

Performs the conversion.

impl PyClass for OKXHttpClient

type Frozen = False

Whether the pyclass is frozen.

impl PyClassImpl for OKXHttpClient

const IS_BASETYPE: bool = false

#[pyclass(subclass)]

const IS_SUBCLASS: bool = false

#[pyclass(extends=…)]

const IS_MAPPING: bool = false

#[pyclass(mapping)]

const IS_SEQUENCE: bool = false

#[pyclass(sequence)]

const IS_IMMUTABLE_TYPE: bool = false

#[pyclass(immutable_type)]

const RAW_DOC: &'static CStr = /// Provides a higher-level HTTP client for the [OKX](https://okx.com) REST API. /// /// This client wraps the underlying `OKXHttpInnerClient` to handle conversions /// into the Nautilus domain model.

Docstring for the class provided on the struct or enum.

const DOC: &'static CStr

Fully rendered class doc, including the text_signature if a constructor is defined.

type BaseType = PyAny

Base class

type ThreadChecker = SendablePyClass<OKXHttpClient>

This handles following two situations:

type PyClassMutability = <<PyAny as PyClassBaseType>::PyClassMutability as PyClassMutability>::MutableChild

Immutable or mutable

type Dict = PyClassDummySlot

Specify this class has #[pyclass(dict)] or not.

type WeakRef = PyClassDummySlot

Specify this class has #[pyclass(weakref)] or not.

type BaseNativeType = PyAny

The closest native ancestor. This is PyAny by default, and when you declare #[pyclass(extends=PyDict)], it’s PyDict.

fn items_iter() -> PyClassItemsIter

fn lazy_type_object() -> &'static LazyTypeObject<Self>

fn dict_offset() -> Option<isize>

fn weaklist_offset() -> Option<isize>

impl PyClassNewTextSignature for OKXHttpClient

const TEXT_SIGNATURE: &'static str = "(api_key=None, api_secret=None, api_passphrase=None, base_url=None, timeout_secs=None, max_retries=None, retry_delay_ms=None, retry_delay_max_ms=None, is_demo=False, proxy_url=None)"

impl PyMethods<OKXHttpClient> for PyClassImplCollector<OKXHttpClient>

fn py_methods(self) -> &'static PyClassItems

impl PyTypeInfo for OKXHttpClient

const NAME: &'static str = "OKXHttpClient"

Class name.

const MODULE: Option<&'static str>

Module name, if any.

fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject

Returns the PyTypeObject instance for this type.

fn type_object(py: Python<'_>) -> Bound<'_, PyType>

Returns the safe abstraction over the type object.

fn is_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type or a subclass of this type.

fn is_exact_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type.

impl DerefToPyAny for OKXHttpClient

impl ExtractPyClassWithClone for OKXHttpClient