Struct HyperliquidWebSocketClient 

pub struct HyperliquidWebSocketClient { /* private fields */ }

Hyperliquid WebSocket client following the BitMEX pattern.

Orchestrates WebSocket connection and subscriptions using a command-based architecture, where the inner FeedHandler owns the WebSocketClient and handles all I/O.

Implementations

impl HyperliquidWebSocketClient

pub fn new( url: Option<String>, environment: HyperliquidEnvironment, account_id: Option<AccountId>, transport_backend: TransportBackend, proxy_url: Option<String>, ) -> Self

Creates a new Hyperliquid WebSocket client without connecting.

If url is None, the appropriate URL will be determined from the environment:

• Mainnet: wss://api.hyperliquid.xyz/ws
• Testnet: wss://api.hyperliquid-testnet.xyz/ws

The connection will be established when connect() is called.

pub async fn connect(&mut self) -> Result<()>

Establishes WebSocket connection and spawns the message handler.

pub fn take_task_handle(&mut self) -> Option<JoinHandle<()>>

Takes the handler task handle from this client so that another instance (e.g., the non-clone original) can await it on disconnect.

pub fn set_task_handle(&mut self, handle: JoinHandle<()>)

pub fn set_post_timeout(&mut self, timeout: Duration)

pub async fn disconnect(&mut self) -> Result<()>

Disconnects the WebSocket connection.

pub async fn post_action_exec( &self, signer: &HyperliquidHttpClient, action: &HyperliquidExecAction, ) -> HyperliquidResult<HyperliquidExchangeResponse>

Send a typed exchange action through the Hyperliquid WebSocket post API.

The supplied HTTP client is used only as the canonical signer for the action envelope. The signed payload is sent over the active WebSocket connection and the response is correlated by post id.

pub async fn post_action_exec_with_timeout( &self, signer: &HyperliquidHttpClient, action: &HyperliquidExecAction, timeout: Duration, expires_after: Option<u64>, ) -> HyperliquidResult<HyperliquidExchangeResponse>

Send a typed exchange action with a caller-specified timeout and optional expiry.

pub async fn submit_order( &self, signer: &HyperliquidHttpClient, instrument_id: InstrumentId, client_order_id: ClientOrderId, order_side: OrderSide, order_type: OrderType, quantity: Quantity, time_in_force: TimeInForce, price: Option<Price>, trigger_price: Option<Price>, post_only: bool, reduce_only: bool, ) -> HyperliquidResult<()>

Submit an order through the Hyperliquid WebSocket post API.

The HTTP client supplies signing credentials, builder attribution, and cached instrument metadata. The action itself is sent over WebSocket.

pub async fn submit_orders( &self, signer: &HyperliquidHttpClient, orders: &[&OrderAny], ) -> HyperliquidResult<()>

Submit multiple orders through the Hyperliquid WebSocket post API.

pub async fn cancel_order( &self, signer: &HyperliquidHttpClient, instrument_id: InstrumentId, client_order_id: Option<ClientOrderId>, venue_order_id: Option<VenueOrderId>, ) -> HyperliquidResult<()>

Cancel an order through the Hyperliquid WebSocket post API.

pub async fn cancel_orders( &self, signer: &HyperliquidHttpClient, cancels: &[(InstrumentId, ClientOrderId, Option<VenueOrderId>)], ) -> HyperliquidResult<Vec<Option<String>>>

Cancel multiple orders through one Hyperliquid WebSocket post action.

pub async fn modify_order( &self, signer: &HyperliquidHttpClient, instrument_id: InstrumentId, venue_order_id: VenueOrderId, order_side: OrderSide, order_type: OrderType, price: Price, quantity: Quantity, trigger_price: Option<Price>, reduce_only: bool, post_only: bool, time_in_force: TimeInForce, client_order_id: Option<ClientOrderId>, ) -> HyperliquidResult<()>

Modify an order through the Hyperliquid WebSocket post API.

pub fn is_active(&self) -> bool

Returns true if the WebSocket is actively connected.

pub fn url(&self) -> &str

Returns the URL of this WebSocket client.

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

Caches multiple instruments.

Clears the existing cache first, then adds all provided instruments. Instruments are keyed by their raw_symbol which is unique per instrument:

• Perps use base currency (e.g., “BTC”)
• Spot uses @{pair_index} format (e.g., “@107”) or slash format for PURR

pub fn cache_instrument(&self, instrument: InstrumentAny)

Caches a single instrument.

Any existing instrument with the same raw_symbol will be replaced.

pub fn instruments_cache(&self) -> Arc<AtomicMap<Ustr, InstrumentAny>>

Returns a shared reference to the instrument cache.

pub fn cache_spot_fill_coins(&self, mapping: AHashMap<Ustr, Ustr>)

Caches spot fill coin mappings for instrument lookup.

Hyperliquid WebSocket fills for spot use @{pair_index} format (e.g., @107), while instruments are identified by full symbols (e.g., HYPE-USDC-SPOT). This mapping allows the handler to look up instruments from spot fills.

pub fn cache_cloid_mapping(&self, cloid: Ustr, client_order_id: ClientOrderId)

Caches a venue CLOID to client_order_id mapping for order/fill resolution.

This mapping allows WebSocket order status and fill reports to be resolved back to the original client_order_id.

This writes directly to a shared cache that the handler reads from, avoiding any race conditions between caching and WebSocket message processing.

pub fn remove_cloid_mapping(&self, cloid: &Ustr)

Removes a cloid mapping from the cache.

Called on terminal order state. The cache is FIFO-bounded so missed removals self-evict (see GH-3972 cancel-replace drain).

pub fn clear_cloid_cache(&self)

Clears all cloid mappings from the cache.

Useful for cleanup during reconnection or shutdown.

pub fn cloid_cache_len(&self) -> usize

Returns the number of cloid mappings in the cache.

pub fn get_cloid_mapping(&self, cloid: &Ustr) -> Option<ClientOrderId>

Looks up a client_order_id by its venue CLOID.

Returns Some(ClientOrderId) if the mapping exists, None otherwise.

pub fn get_instrument(&self, id: &InstrumentId) -> Option<InstrumentAny>

Gets an instrument from the cache by ID.

Searches the cache for a matching instrument ID.

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

Gets an instrument from the cache by raw_symbol (coin).

pub fn subscription_count(&self) -> usize

Returns the count of confirmed subscriptions.

pub fn get_bar_type(&self, coin: &str, interval: &str) -> Option<BarType>

Gets a bar type from the cache by coin and interval.

This looks up the subscription key created when subscribing to bars.

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

Subscribe to L2 order book for an instrument.

pub async fn subscribe_book_with_options( &self, instrument_id: InstrumentId, n_sig_figs: Option<u32>, mantissa: Option<u32>, ) -> Result<()>

Subscribe to L2 order book with optional nSigFigs / mantissa precision controls passed through to the venue’s l2Book stream.

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

Subscribe to order book depth-10 snapshots.

Reuses the same l2Book WebSocket subscription as Self::subscribe_book and flags the handler to additionally emit NautilusWsMessage::Depth10 for this coin.

pub async fn subscribe_book_depth10_with_options( &self, instrument_id: InstrumentId, n_sig_figs: Option<u32>, mantissa: Option<u32>, ) -> Result<()>

Subscribe to depth-10 snapshots with optional nSigFigs / mantissa precision controls.

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

Unsubscribe from order book depth-10 snapshots.

Clears the depth10 emission flag only; the underlying l2Book stream stays open so active deltas subscribers keep receiving updates. Call Self::unsubscribe_book separately to tear down the stream entirely.

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

Subscribe to best bid/offer (BBO) quotes for an instrument.

pub async fn subscribe_all_mids(&self) -> Result<()>

Subscribe to all mid prices across markets.

pub async fn subscribe_all_dexs_asset_ctxs(&self) -> Result<()>

Subscribe to aggregate asset contexts across all perp dexes.

pub async fn subscribe_all_mids_with_dex(&self, dex: Option<&str>) -> Result<()>

Subscribe to all mid prices across markets, optionally scoped to a specific dex.

pub async fn unsubscribe_all_mids(&self) -> Result<()>

Unsubscribe from all mid prices across markets.

pub async fn unsubscribe_all_dexs_asset_ctxs(&self) -> Result<()>

Unsubscribe from aggregate asset contexts across all perp dexes.

pub async fn unsubscribe_all_mids_with_dex( &self, dex: Option<&str>, ) -> Result<()>

Unsubscribe from all mid prices across markets, optionally scoped to a specific dex.

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

Subscribe to trades for an instrument.

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

Subscribe to mark price updates for an instrument.

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

Subscribe to index/oracle price updates for an instrument.

pub async fn subscribe_bars(&self, bar_type: BarType) -> Result<()>

Subscribe to candle/bar data for a specific coin and interval.

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

Subscribe to funding rate updates for an instrument.

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

Subscribe to open interest updates for an instrument.

pub async fn subscribe_order_updates(&self, user: &str) -> Result<()>

Subscribe to order updates for a specific user address.

pub async fn subscribe_user_events(&self, user: &str) -> Result<()>

Subscribe to user events (fills, funding, liquidations) for a specific user address.

pub async fn subscribe_user_fills(&self, user: &str) -> Result<()>

Subscribe to user fills for a specific user address.

Note: This channel is redundant with userEvents which already includes fills. Prefer using subscribe_user_events or subscribe_all_user_channels instead.

pub async fn subscribe_all_user_channels(&self, user: &str) -> Result<()>

Subscribe to all user channels (order updates + user events) for convenience.

Note: userEvents already includes fills, so we don’t subscribe to userFills separately to avoid duplicate fill messages.

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

Unsubscribe from L2 order book for an instrument.

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

Unsubscribe from quote ticks for an instrument.

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

Unsubscribe from trades for an instrument.

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

Unsubscribe from mark price updates for an instrument.

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

Unsubscribe from index/oracle price updates for an instrument.

pub async fn unsubscribe_bars(&self, bar_type: BarType) -> Result<()>

Unsubscribe from candle/bar data.

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

Unsubscribe from funding rate updates for an instrument.

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

Unsubscribe from open interest updates for an instrument.

pub fn cache_all_dex_asset_ctxs_instrument_ids( &self, mapping: AHashMap<Ustr, Vec<Option<InstrumentId>>>, )

Cache the ordered instrument IDs required to normalize allDexsAssetCtxs.

pub async fn next_event(&mut self) -> Option<NautilusWsMessage>

Receives the next message from the WebSocket handler.

Returns None if the handler has disconnected or the receiver was already taken.

impl HyperliquidWebSocketClient

pub fn py_url(&self) -> String

Returns the URL of this WebSocket client.

Trait Implementations

impl Clone for HyperliquidWebSocketClient

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 HyperliquidWebSocketClient

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

Formats the value using the given formatter.

impl DerefToPyAny for HyperliquidWebSocketClient

impl<'a, 'py> FromPyObject<'a, 'py> for HyperliquidWebSocketClient

where Self: Clone,

type Error = PyClassGuardError<'a, 'py>

The type returned in the event of a conversion error.

fn extract( obj: Borrowed<'a, 'py, PyAny>, ) -> Result<Self, <Self as FromPyObject<'a, 'py>>::Error>

Extracts Self from the bound smart pointer obj.

impl<'py> IntoPyObject<'py> for HyperliquidWebSocketClient

type Target = HyperliquidWebSocketClient

The Python output type

type Output = Bound<'py, <HyperliquidWebSocketClient 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 HyperliquidWebSocketClient

const NAME: &str = "HyperliquidWebSocketClient"

Name of the class.

type Frozen = False

Whether the pyclass is frozen.

impl PyClassImpl for HyperliquidWebSocketClient

const MODULE: Option<&str>

Module which the class will be associated with.

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 = /// Hyperliquid WebSocket client following the BitMEX pattern. /// /// Orchestrates WebSocket connection and subscriptions using a command-based architecture, /// where the inner FeedHandler owns the WebSocketClient and handles all I/O.

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 Layout = <<HyperliquidWebSocketClient as PyClassImpl>::BaseNativeType as PyClassBaseType>::Layout<HyperliquidWebSocketClient>

Description of how this class is laid out in memory

type BaseType = PyAny

Base class

type ThreadChecker = NoopThreadChecker

This handles following two situations:

type Inventory = Pyo3MethodsInventoryForHyperliquidWebSocketClient

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<PyObjectOffset>

Used to provide the dictoffset slot (equivalent to tp_dictoffset)

fn weaklist_offset() -> Option<PyObjectOffset>

Used to provide the weaklistoffset slot (equivalent to tp_weaklistoffset

impl PyClassNewTextSignature for HyperliquidWebSocketClient

const TEXT_SIGNATURE: &'static str = "(url=None, environment=..., account_id=None, proxy_url=None)"

impl PyStubType for HyperliquidWebSocketClient

fn type_output() -> TypeInfo

The type to be used in the output signature, i.e. return type of the Python function or methods.

fn type_input() -> TypeInfo

The type to be used in the input signature, i.e. the arguments of the Python function or methods.

impl PyTypeInfo for HyperliquidWebSocketClient

const NAME: &str = <Self as ::pyo3::PyClass>::NAME

👎Deprecated since 0.28.0:

prefer using ::type_object(py).name() to get the correct runtime value

Class name.

const MODULE: Option<&str> = <Self as ::pyo3::impl_::pyclass::PyClassImpl>::MODULE

👎Deprecated since 0.28.0:

prefer using ::type_object(py).module() to get the correct runtime value

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.