Struct DydxWebSocketClient 

pub struct DydxWebSocketClient { /* private fields */ }

WebSocket client for dYdX v4 market data and account streams.

Authentication

dYdX v4 does not require traditional API key signatures for WebSocket connections. Public channels work without any credentials. Private channels (subaccounts) only need the wallet address included in the subscription message.

The DydxCredential stored in this client is used for:

• Providing the wallet address for private channel subscriptions
• Transaction signing (when placing orders via the validator node)

It is NOT used for WebSocket message signing or authentication.

Architecture

The client owns a small pool of connection slots. Each slot has its own WebSocketClient, FeedHandler task, command channel, and [SubscriptionState]. All slots write parsed events into a single shared output channel so callers see one merged stream.

Implementations

impl DydxWebSocketClient

pub fn new_public( url: String, heartbeat: Option<u64>, proxy_url: Option<String>, ) -> Self

Creates a new public WebSocket client for market data.

This creates a new independent instrument cache. To share a cache with the HTTP client, use Self::new_public_with_cache instead.

pub fn new_public_with_cache( url: String, instrument_cache: Arc<InstrumentCache>, heartbeat: Option<u64>, transport_backend: TransportBackend, proxy_url: Option<String>, ) -> Self

Creates a new public WebSocket client with a shared instrument cache.

Use this when you want to share instrument data with the HTTP client.

pub fn new_public_with_cache_and_pool( url: String, instrument_cache: Arc<InstrumentCache>, heartbeat: Option<u64>, transport_backend: TransportBackend, proxy_url: Option<String>, max_ws_connections: usize, per_channel_limit: usize, ) -> Self

Creates a new public WebSocket client with full pool configuration.

pub fn new_private( url: String, credential: DydxCredential, account_id: AccountId, heartbeat: Option<u64>, proxy_url: Option<String>, ) -> Self

Creates a new private WebSocket client for account updates.

This creates a new independent instrument cache. To share a cache with the HTTP client, use Self::new_private_with_cache instead.

pub fn new_private_with_cache( url: String, credential: DydxCredential, account_id: AccountId, instrument_cache: Arc<InstrumentCache>, heartbeat: Option<u64>, transport_backend: TransportBackend, proxy_url: Option<String>, ) -> Self

Creates a new private WebSocket client with a shared instrument cache.

Use this when you want to share instrument data with the HTTP client.

pub fn with_socket_factory(self, factory: SocketControlFactory) -> Self

Configures socket state reporting and reconnect control for each pool slot.

pub fn credential(&self) -> Option<&Arc<DydxCredential>>

Returns the credential associated with this client, if any.

pub fn is_connected(&self) -> bool

Returns true when any connection in the pool is connected.

pub fn url(&self) -> &str

Returns the URL of this WebSocket client.

pub fn connection_mode_atomic(&self) -> Arc<ArcSwap<AtomicU8>>

Returns a clone of the connection mode atomic reference.

With sharding, the returned atomic tracks the primary slot (slot 0) only; use Self::is_connected for a pool-wide check.

pub fn pool_size(&self) -> usize

Returns the current number of active slots in the pool.

pub const fn max_ws_connections(&self) -> usize

Returns the configured maximum number of pool connections.

pub const fn per_channel_limit(&self) -> usize

Returns the configured per-channel subscription limit.

pub fn set_account_id(&mut self, account_id: AccountId)

Sets the account ID for account message parsing.

pub fn account_id(&self) -> Option<AccountId>

Returns the account ID if set.

pub fn set_instrument_cache(&mut self, cache: Arc<InstrumentCache>)

Replaces the instrument cache with an externally shared one.

Use this to share the HTTP client’s cache (which includes CLOB pair ID and market ticker indices) with the WebSocket client. Must be called before connect().

pub fn cache_instrument(&self, instrument: InstrumentAny)

Caches a single instrument.

Any existing instrument with the same ID will be replaced.

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

Caches multiple instruments.

Any existing instruments with the same IDs will be replaced.

pub fn instrument_cache(&self) -> &Arc<InstrumentCache>

Returns a reference to the shared instrument cache.

pub fn encoder(&self) -> &Arc<ClientOrderIdEncoder>

Returns a reference to the shared client order ID encoder.

pub fn bar_types(&self) -> &Arc<DashMap<String, BarType>>

Returns a reference to the bar type registrations map.

pub fn ws_dispatch_state(&self) -> &Arc<DydxWsDispatchState>

Returns a reference to the shared WebSocket dispatch state.

pub fn set_bars_timestamp_on_close(&self, value: bool)

Sets whether bar timestamps use the close time.

pub fn bars_timestamp_on_close(&self) -> bool

Returns whether bar timestamps use the close time.

pub fn all_instruments(&self) -> Vec<InstrumentAny>

Returns all cached instruments.

This is a snapshot of the current cache contents.

pub fn cached_instruments_count(&self) -> usize

Returns the number of cached instruments.

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

Retrieves an instrument from the cache by InstrumentId.

Returns None if the instrument is not found.

pub fn get_instrument_by_market(&self, ticker: &str) -> Option<InstrumentAny>

Retrieves an instrument from the cache by market ticker (e.g., “BTC-USD”).

Returns None if the instrument is not found.

pub fn take_receiver( &mut self, ) -> Option<UnboundedReceiver<DydxWsOutputMessage>>

Takes ownership of the inbound message receiver. Returns None if the receiver has already been taken or not connected.

pub fn stream( &mut self, ) -> impl Stream<Item = DydxWsOutputMessage> + Send + 'static

Returns a stream of venue-specific WebSocket messages.

Takes ownership of the message receiver and returns it as a Stream.

Panics

Panics if the message receiver has already been taken or the client is not connected.

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

Connects the websocket client and opens the primary pool slot.

Additional slots are spawned lazily by subscribe_* methods once the per-channel limit is reached on every existing slot.

Errors

Returns an error if the connection cannot be established.

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

Disconnects all websocket connections in the pool.

Errors

Returns an error if the underlying clients cannot be accessed.

pub fn send_command(&self, cmd: HandlerCommand) -> DydxWsResult<()>

Sends a command directly to the primary slot (slot 0).

Errors

Returns an error if no slot exists or the handler task has terminated.

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

Subscribes to public trade updates for a specific instrument.

Errors

Returns an error if the subscription request fails.

References

https://docs.dydx.trade/developers/indexer/websockets#trades-channel

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

Unsubscribes from public trade updates for a specific instrument.

Errors

Returns an error if the unsubscription request fails.

pub async fn subscribe_orderbook( &self, instrument_id: InstrumentId, ) -> DydxWsResult<()>

Subscribes to orderbook updates for a specific instrument.

Errors

Returns an error if the subscription request fails.

References

https://docs.dydx.trade/developers/indexer/websockets#orderbook-channel

pub async fn unsubscribe_orderbook( &self, instrument_id: InstrumentId, ) -> DydxWsResult<()>

Unsubscribes from orderbook updates for a specific instrument.

Errors

Returns an error if the unsubscription request fails.

pub async fn subscribe_candles( &self, instrument_id: InstrumentId, resolution: &str, ) -> DydxWsResult<()>

Subscribes to candle/kline updates for a specific instrument.

Errors

Returns an error if the subscription request fails.

References

https://docs.dydx.trade/developers/indexer/websockets#candles-channel

pub async fn unsubscribe_candles( &self, instrument_id: InstrumentId, resolution: &str, ) -> DydxWsResult<()>

Unsubscribes from candle/kline updates for a specific instrument.

Errors

Returns an error if the unsubscription request fails.

pub async fn subscribe_markets(&self) -> DydxWsResult<()>

Subscribes to market updates for all instruments.

Errors

Returns an error if the subscription request fails.

References

https://docs.dydx.trade/developers/indexer/websockets#markets-channel

pub async fn unsubscribe_markets(&self) -> DydxWsResult<()>

Unsubscribes from market updates.

Errors

Returns an error if the unsubscription request fails.

pub async fn subscribe_subaccount( &self, address: &str, subaccount_number: u32, ) -> DydxWsResult<()>

Subscribes to subaccount updates (orders, fills, positions, balances).

This requires authentication and will only work for private WebSocket clients created with Self::new_private. Subaccount streams stay pinned to the primary slot: the Indexer caps them at 256 per connection, which is well above realistic per-process usage and keeps related fill/position events on a single in-order stream.

Errors

Returns an error if the client was not created with credentials or if the subscription request fails.

References

https://docs.dydx.trade/developers/indexer/websockets#subaccounts-channel

pub async fn unsubscribe_subaccount( &self, address: &str, subaccount_number: u32, ) -> DydxWsResult<()>

Unsubscribes from subaccount updates.

Errors

Returns an error if the unsubscription request fails.

pub async fn subscribe_block_height(&self) -> DydxWsResult<()>

Subscribes to block height updates.

Errors

Returns an error if the subscription request fails.

References

https://docs.dydx.trade/developers/indexer/websockets#block-height-channel

pub async fn unsubscribe_block_height(&self) -> DydxWsResult<()>

Unsubscribes from block height updates.

Errors

Returns an error if the unsubscription request fails.

Trait Implementations

impl Clone for DydxWebSocketClient

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 DydxWebSocketClient

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

Formats the value using the given formatter.