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>) -> 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.

pub fn from_env() -> Result<Self>

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

pub fn with_credentials( api_key: Option<String>, api_secret: Option<String>, api_passphrase: Option<String>, base_url: Option<String>, timeout_secs: Option<u64>, ) -> Result<Self>

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

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 const 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 the cached instrument symbols. Returns a snapshot of all instrument symbols currently held in the internal cache.

Panics

Panics if the internal mutex guarding the instrument cache is poisoned (which would indicate a previous panic while the lock was held).

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

Adds the instruments to the clients instrument cache.

Any existing instruments will be replaced. Inserts multiple instruments into the local cache.

Panics

Panics if the instruments cache mutex is poisoned.

pub fn add_instrument(&mut self, instrument: InstrumentAny)

Adds the instrument to the clients instrument cache.

Any existing instrument will be replaced. Inserts a single instrument into the local cache.

Panics

Panics if the instruments cache mutex is poisoned.

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, ) -> 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_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.

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.

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.

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.

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.

References

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

impl OKXHttpClient

pub fn py_base_url(&self) -> &str

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

pub const fn py_is_initialized(&self) -> bool

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

pub fn py_add_instrument( &mut self, py: Python<'_>, instrument: PyObject, ) -> PyResult<()>

Errors

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

Trait Implementations

impl Clone for OKXHttpClient

fn clone(&self) -> OKXHttpClient

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)]

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 doc(py: Python<'_>) -> PyResult<&'static CStr>

Rendered class doc

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

fn dict_offset() -> Option<isize>

fn weaklist_offset() -> Option<isize>

impl PyClassNewTextSignature<OKXHttpClient> for PyClassImplCollector<OKXHttpClient>

fn new_text_signature(self) -> Option<&'static str>

impl<'a, 'py> PyFunctionArgument<'a, 'py, false> for &'a OKXHttpClient

type Holder = Option<PyRef<'py, OKXHttpClient>>

fn extract( obj: &'a Bound<'py, PyAny>, holder: &'a mut Self::Holder, ) -> PyResult<Self>

impl<'a, 'py> PyFunctionArgument<'a, 'py, false> for &'a mut OKXHttpClient

type Holder = Option<PyRefMut<'py, OKXHttpClient>>

fn extract( obj: &'a Bound<'py, PyAny>, holder: &'a mut Self::Holder, ) -> PyResult<Self>

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