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<Option<OrderStatusReport>>

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.

Returns an OrderStatusReport describing the venue’s immediate response (Filled for an atomic IOC fill, Accepted for a resting order), or None when the venue deferred the order without an oid (for example a waitingForFill trigger child): the order stays SUBMITTED until the user-events stream delivers the first OrderAccepted.

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

Submit multiple orders through the Hyperliquid WebSocket post API.

Returns one OrderStatusReport per accepted order in submission order. Deferred trigger children of a normalTpsl bracket are absent from the result; they stay SUBMITTED until the user-events stream delivers an OrderAccepted with the real oid.

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.

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.