BitMEX

BitMEX cryptocurrency exchange integration adapter.

This subpackage provides an instrument provider, data and execution clients, configurations, and constants for connecting to and interacting with BitMEX’s API.

For convenience, the most commonly used symbols are re-exported at the subpackage’s top level, so downstream code can simply import from nautilus_trader.adapters.bitmex.

class BitmexDataClientConfig

Bases: LiveDataClientConfig

Configuration for BitmexDataClient instances.

Parameters:

  • api_key (str, [default=None]) – The BitMEX API public key. If None then will source the BITMEX_API_KEY or BITMEX_TESTNET_API_KEY environment variable based on environment.

  • api_secret (str, [default=None]) – The BitMEX API secret key. If None then will source the BITMEX_API_SECRET or BITMEX_TESTNET_API_SECRET environment variable based on environment.

  • environment (BitmexEnvironment, optional) – The BitMEX environment for the client (MAINNET or TESTNET). If None then defaults to MAINNET.

  • base_url_http (str, optional) – The base url to BitMEX’s HTTP API. If None then will use the default production URL.

  • base_url_ws (str, optional) – The base url to BitMEX’s WebSocket API. If None then will use the default production URL.

  • proxy_url (str, optional) – Optional proxy URL for HTTP and WebSocket transports.

  • http_timeout_secs (PositiveInt, default 60) – The timeout for HTTP requests in seconds.

  • max_retries (PositiveInt, default 3) – The maximum number of retries for HTTP requests.

  • retry_delay_initial_ms (PositiveInt, default 1_000) – The initial delay (milliseconds) between retries.

  • retry_delay_max_ms (PositiveInt, default 10_000) – The maximum delay (milliseconds) between retries.

  • recv_window_ms (PositiveInt, default 10_000) – The expiration window (milliseconds) for signed requests. Note: Specified in milliseconds for consistency with other adapters, but BitMEX uses seconds-granularity timestamps (converted via integer division).

  • update_instruments_interval_mins (PositiveInt or None, default 60) – The interval (minutes) between reloading instruments from the venue.

  • max_requests_per_second (PositiveInt, default 10) – The maximum number of requests per second (burst limit). Defaults to 10 (per BitMEX documentation).

  • max_requests_per_minute (PositiveInt, default 120) – The maximum number of requests per minute (rolling window). Defaults to 120 so data clients can share the cached HTTP client with execution. Lower to 30 if you rely on BitMEX’s unauthenticated venue limits instead of local throttling.

api_key: str | None
api_secret: str | None
environment: BitmexEnvironment | None
base_url_http: str | None
base_url_ws: str | None
proxy_url: str | None
transport_backend: TransportBackend | None
http_timeout_secs: Annotated[int, msgspec.Meta(gt=0)] | None
max_retries: Annotated[int, msgspec.Meta(gt=0)] | None
retry_delay_initial_ms: Annotated[int, msgspec.Meta(gt=0)] | None
retry_delay_max_ms: Annotated[int, msgspec.Meta(gt=0)] | None
recv_window_ms: Annotated[int, msgspec.Meta(gt=0)] | None
update_instruments_interval_mins: Annotated[int, msgspec.Meta(gt=0)] | None
max_requests_per_second: Annotated[int, msgspec.Meta(gt=0)]
max_requests_per_minute: Annotated[int, msgspec.Meta(gt=0)]
dict() → dict[str, Any]

Return a dictionary representation of the configuration.

Return type:

dict[str, Any]

classmethod fully_qualified_name() → str

Return the fully qualified name for the NautilusConfig class.

Return type:

str

References

https://www.python.org/dev/peps/pep-3155/

handle_revised_bars: bool
property id: str

Return the hashed identifier for the configuration.

Return type:

str

instrument_provider: InstrumentProviderConfig
json() → bytes

Return serialized JSON encoded bytes.

Return type:

bytes

json_primitives() → dict[str, Any]

Return a dictionary representation of the configuration with JSON primitive types as values.

Return type:

dict[str, Any]

classmethod json_schema() → dict[str, Any]

Generate a JSON schema for this configuration class.

Return type:

dict[str, Any]

classmethod parse(raw: bytes | str) → Any

Return a decoded object of the given cls.

Parameters:

  • cls (type) – The type to decode to.

  • raw (bytes or str) – The raw bytes or JSON string to decode.

Return type:

Any

routing: RoutingConfig
validate() → bool

Return whether the configuration can be represented as valid JSON.

Return type:

bool

class BitmexExecClientConfig

Bases: LiveExecClientConfig

Configuration for BitmexExecutionClient instances.

Parameters:

  • api_key (str, [default=None]) – The BitMEX API public key. If None then will source the BITMEX_API_KEY or BITMEX_TESTNET_API_KEY environment variable based on environment.

  • api_secret (str, [default=None]) – The BitMEX API secret key. If None then will source the BITMEX_API_SECRET or BITMEX_TESTNET_API_SECRET environment variable based on environment.

  • environment (BitmexEnvironment, optional) – The BitMEX environment for the client (MAINNET or TESTNET). If None then defaults to MAINNET.

  • base_url_http (str, optional) – The base url to BitMEX’s HTTP API. If None then will use the default production URL.

  • base_url_ws (str, optional) – The base url to BitMEX’s WebSocket API. If None then will use the default production URL.

  • proxy_url (str, optional) – Optional proxy URL for HTTP and WebSocket transports.

  • http_timeout_secs (PositiveInt, default 60) – The timeout for HTTP requests in seconds.

  • max_retries (PositiveInt, default 3) – The maximum number of retries for HTTP requests.

  • retry_delay_initial_ms (PositiveInt, default 1_000) – The initial delay (milliseconds) between retries.

  • retry_delay_max_ms (PositiveInt, default 10_000) – The maximum delay (milliseconds) between retries.

  • recv_window_ms (PositiveInt, default 10_000) – The expiration window (milliseconds) for signed requests. Note: Specified in milliseconds for consistency with other adapters, but BitMEX uses seconds-granularity timestamps (converted via integer division).

  • max_requests_per_second (PositiveInt, default 10) – The maximum number of requests per second (burst limit). Defaults to 10 (per BitMEX documentation).

  • max_requests_per_minute (PositiveInt, default 120) – The maximum number of requests per minute (rolling window). Defaults to 120 for authenticated clients (per BitMEX documentation). Note: Execution clients are always authenticated.

  • submitter_pool_size (PositiveInt, optional) – The number of redundant HTTP clients in the submit broadcaster pool. Broadcasting is opt-in via params={“submit_tries”: N} on submit commands (N > 1). When broadcasting, up to N submit requests are fanned out in parallel for redundancy, with the first successful response short-circuiting remaining requests. If submit_tries exceeds pool_size, it will be capped at pool_size (with warning). If not specified, defaults to 1 (single client, no redundancy). Recommended maximum pool size of 3.

  • canceller_pool_size (PositiveInt, optional) – The number of redundant HTTP clients in the cancel broadcaster pool. Cancel requests are fanned out to multiple clients in parallel for redundancy, with the first successful response short-circuiting remaining requests. Recommended maximum pool size of 3.

  • submitter_proxy_urls (list[str], optional) – Optional list of proxy URLs for submit broadcaster path diversity.

  • canceller_proxy_urls (list[str], optional) – Optional list of proxy URLs for cancel broadcaster path diversity.

  • deadmans_switch_timeout_secs (PositiveInt, optional) – Dead man’s switch timeout in seconds. When set, a background task periodically calls the BitMEX cancelAllAfter endpoint to keep a server-side timer alive. If the client loses connectivity the timer expires and BitMEX cancels all open orders. The refresh interval is derived as timeout / 4 (minimum 1 second).

api_key: str | None
api_secret: str | None
environment: BitmexEnvironment | None
base_url_http: str | None
base_url_ws: str | None
proxy_url: str | None
transport_backend: TransportBackend | None
http_timeout_secs: Annotated[int, msgspec.Meta(gt=0)] | None
max_retries: Annotated[int, msgspec.Meta(gt=0)] | None
retry_delay_initial_ms: Annotated[int, msgspec.Meta(gt=0)] | None
retry_delay_max_ms: Annotated[int, msgspec.Meta(gt=0)] | None
recv_window_ms: Annotated[int, msgspec.Meta(gt=0)] | None
max_requests_per_second: Annotated[int, msgspec.Meta(gt=0)]
max_requests_per_minute: Annotated[int, msgspec.Meta(gt=0)]
submitter_pool_size: Annotated[int, msgspec.Meta(gt=0)] | None
canceller_pool_size: Annotated[int, msgspec.Meta(gt=0)] | None
submitter_proxy_urls: list[str] | None
canceller_proxy_urls: list[str] | None
deadmans_switch_timeout_secs: Annotated[int, msgspec.Meta(gt=0)] | None
dict() → dict[str, Any]

Return a dictionary representation of the configuration.

Return type:

dict[str, Any]

classmethod fully_qualified_name() → str

Return the fully qualified name for the NautilusConfig class.

Return type:

str

References

https://www.python.org/dev/peps/pep-3155/

property id: str

Return the hashed identifier for the configuration.

Return type:

str

instrument_provider: InstrumentProviderConfig
json() → bytes

Return serialized JSON encoded bytes.

Return type:

bytes

json_primitives() → dict[str, Any]

Return a dictionary representation of the configuration with JSON primitive types as values.

Return type:

dict[str, Any]

classmethod json_schema() → dict[str, Any]

Generate a JSON schema for this configuration class.

Return type:

dict[str, Any]

classmethod parse(raw: bytes | str) → Any

Return a decoded object of the given cls.

Parameters:

  • cls (type) – The type to decode to.

  • raw (bytes or str) – The raw bytes or JSON string to decode.

Return type:

Any

routing: RoutingConfig
validate() → bool

Return whether the configuration can be represented as valid JSON.

Return type:

bool

class BitmexInstrumentProvider

Bases: InstrumentProvider

Provides Nautilus instrument definitions from BitMEX.

Parameters:

  • client (nautilus_pyo3.BitmexHttpClient) – The BitMEX HTTP client.

  • active_only (bool, default True) – Whether to only load active instruments.

  • config (InstrumentProviderConfig, optional) – The instrument provider configuration, by default None.

property active_only: bool

Return whether the provider is configured to load only active instruments.

Return type:

bool

instruments_pyo3() → list[Any]

Return all BitMEX PyO3 instrument definitions held by the provider.

Return type:

list[nautilus_pyo3.Instrument]

async load_all_async(filters: dict | None = None) → None

Load the latest instruments into the provider asynchronously, optionally applying the given filters.

async load_ids_async(instrument_ids: list[InstrumentId], filters: dict | None = None) → None

Load the instruments for the given IDs into the provider, optionally applying the given filters.

The default implementation calls load_all_async (since many venue APIs only support bulk fetches) and then filters the provider to retain only the requested instruments plus any previously loaded ones.

Subclasses with per-instrument fetch capability should override this method.

Parameters:

  • instrument_ids (list[InstrumentId]) – The instrument IDs to load.

  • filters (frozendict[str, Any] or dict[str, Any], optional) – The venue specific instrument loading filters to apply.

async load_async(instrument_id: InstrumentId, filters: dict | None = None) → None

Load the instrument for the given ID into the provider asynchronously, optionally applying the given filters.

The default implementation delegates to load_ids_async. Subclasses with per-instrument fetch capability should override this method.

Parameters:

  • instrument_id (InstrumentId) – The instrument ID to load.

  • filters (frozendict[str, Any] or dict[str, Any], optional) – The venue specific instrument loading filters to apply.

add(instrument: Instrument) → None

Add the given instrument to the provider.

Parameters:

instrument (Instrument) – The instrument to add.

add_bulk(instruments: list[Instrument]) → None

Add the given instruments bulk to the provider.

Parameters:

instruments (list[Instrument]) – The instruments to add.

add_currency(currency: Currency) → None

Add the given currency to the provider.

Parameters:

currency (Currency) – The currency to add.

property count: int

Return the count of instruments held by the provider.

Return type:

int

currencies() → dict[str, Currency]

Return all currencies held by the instrument provider.

Return type:

dict[str, Currency]

currency(code: str) → Currency | None

Return the currency with the given code (if found).

Parameters:

code (str) – The currency code.

Return type:

Currency or None

Raises:

ValueError – If code is not a valid string.

find(instrument_id: InstrumentId) → Instrument | None

Return the instrument for the given instrument ID (if found).

Parameters:

instrument_id (InstrumentId) – The ID for the instrument

Return type:

Instrument or None

get_all() → dict[InstrumentId, Instrument]

Return all loaded instruments as a map keyed by instrument ID.

If no instruments loaded, will return an empty dict.

Return type:

dict[InstrumentId, Instrument]

async initialize(reload: bool = False) → None

Initialize the instrument provider.

Parameters:

reload (bool, default False) – If True, then will always reload instruments. If False, then will immediately return if already loaded.

list_all() → list[Instrument]

Return all loaded instruments.

Return type:

list[Instrument]

load(instrument_id: InstrumentId, filters: dict | None = None) → None

Load the instrument for the given ID into the provider, optionally applying the given filters.

Parameters:

  • instrument_id (InstrumentId) – The instrument ID to load.

  • filters (frozendict[str, Any] or dict[str, Any], optional) – The venue specific instrument loading filters to apply.

load_all(filters: dict | None = None) → None

Load the latest instruments into the provider, optionally applying the given filters.

Parameters:

filters (frozendict[str, Any] or dict[str, Any], optional) – The venue specific instrument loading filters to apply.

load_ids(instrument_ids: list[InstrumentId], filters: dict | None = None) → None

Load the instruments for the given IDs into the provider, optionally applying the given filters.

Parameters:

  • instrument_ids (list[InstrumentId]) – The instrument IDs to load.

  • filters (frozendict[str, Any] or dict[str, Any], optional) – The venue specific instrument loading filters to apply.

class BitmexLiveDataClientFactory

Bases: LiveDataClientFactory

Provides a BitMEX live data client factory.

static create(loop: AbstractEventLoop, name: str | None, config: BitmexDataClientConfig, msgbus: MessageBus, cache: Cache, clock: LiveClock) → BitmexDataClient

Create a new BitMEX data client.

Parameters:

  • loop (asyncio.AbstractEventLoop) – The event loop for the client.

  • name (str, optional) – The custom client ID.

  • config (BitmexDataClientConfig) – The client configuration.

  • msgbus (MessageBus) – The message bus for the client.

  • cache (Cache) – The cache for the client.

  • clock (LiveClock) – The clock for the client.

Return type:

BitmexDataClient

class BitmexLiveExecClientFactory

Bases: LiveExecClientFactory

Provides a BitMEX live execution client factory.

static create(loop: AbstractEventLoop, name: str | None, config: BitmexExecClientConfig, msgbus: MessageBus, cache: Cache, clock: LiveClock) → BitmexExecutionClient

Create a new BitMEX execution client.

Parameters:

  • loop (asyncio.AbstractEventLoop) – The event loop for the client.

  • name (str, optional) – The custom client ID.

  • config (BitmexExecClientConfig) – The client configuration.

  • msgbus (MessageBus) – The message bus for the client.

  • cache (Cache) – The cache for the client.

  • clock (LiveClock) – The clock for the client.

Return type:

BitmexExecutionClient