Ws

hl.Ws

Ws(
    *,
    network: Network,
    universe: Universe,
    account: Account | None = None,
)

Main WebSocket interface for the Hyperliquid API.

This class provides a unified interface for WebSocket operations including: - Subscriptions via ws.subscriptions - Info operations via ws.info - Exchange operations via ws.exchange - Direct WebSocket management (run, run_forever)

Parameters:

Name	Type	Description	Default
network	Network	The network to use.	required
universe	Universe | None	The universe to use for the exchange.	required
account	Account | None	The default account to use for authenticated requests.	None

Methods:

Name	Description
run	Run the websocket client as a task until context exits.
run_forever	Run the websocket manager main loop forever or until it is cancelled.

Attributes:

Name	Type	Description
account	Account | None	The default account to use for authenticated requests.
exchange	Exchange	Access exchange methods via WebSocket.
info	Info	Access info methods via WebSocket.
subscriptions	Subscriptions	Access subscription methods.
universe	Universe	The universe of assets available on the exchange.

account property writable

account: Account | None

The default account to use for authenticated requests.

exchange property

exchange: Exchange

Access exchange methods via WebSocket.

info property

info: Info

Access info methods via WebSocket.

subscriptions property

subscriptions: Subscriptions

Access subscription methods.

universe property writable

universe: Universe

The universe of assets available on the exchange.

run async

run() -> AsyncGenerator[None, None]

Run the websocket client as a task until context exits.

This is a convenience method that starts the websocket manager and ensures it is properly cancelled and cleaned up when the context exits.

Examples:

Use the run method in combination with the async with syntax to run the websocket manager and automatically close the underlying connection once the context exits.

>>> async with api.ws.run():
...     # The websocket connection will automatically be closed when the async context manager exits
...     sid, queue = await api.ws.subscriptions.l2_book(asset="BTC")
...     # Process the next 10 messages
...     for _ in range(10):
...         msg = await queue.get()

run_forever async

run_forever() -> None

Run the websocket manager main loop forever or until it is cancelled.

The client will connect to the websocket API, continuously receive and process incoming messages, and send out outgoing messages.

It is recommended to use the run contextual manager instead of this method since it will automatically close the underlying connection once the context exits.

Examples:

Run the websocket manager forever:

>>> await api.ws.run_forever()

Or run it as a cancellable task:

>>> task = asyncio.create_task(api.ws.run_forever())
... # Do something
... sid, queue = await api.ws.subscriptions.l2_book(asset="BTC")
... # Cancel the task to shut down the websocket client
... task.cancel()
... # Optionally, the task can be awaited to wait for it to shut down
... await task