Example: WebSocket Subscriptions

This example demonstrates how to subscribe to various real-time data streams using the Hyperliquid WebSocket API.

Full Code (examples/basic_ws.py)

import example_utils

from hyperliquid.utils import constants

def main():
    address, info, _ = example_utils.setup(constants.TESTNET_API_URL)
    # An example showing how to subscribe to the different subscription types and prints the returned messages
    # Some subscriptions do not return snapshots, so you will not receive a message until something happens
    info.subscribe({"type": "allMids"}, print)
    info.subscribe({"type": "l2Book", "coin": "ETH"}, print)
    info.subscribe({"type": "trades", "coin": "PURR/USDC"}, print)
    info.subscribe({"type": "userEvents", "user": address}, print)
    info.subscribe({"type": "userFills", "user": address}, print)
    info.subscribe({"type": "candle", "coin": "ETH", "interval": "1m"}, print)
    info.subscribe({"type": "orderUpdates", "user": address}, print)
    info.subscribe({"type": "userFundings", "user": address}, print)
    info.subscribe({"type": "userNonFundingLedgerUpdates", "user": address}, print)
    info.subscribe({"type": "webData2", "user": address}, print)
    info.subscribe({"type": "bbo", "coin": "ETH"}, print)
    info.subscribe({"type": "activeAssetCtx", "coin": "BTC"}, print)  # Perp
    info.subscribe({"type": "activeAssetCtx", "coin": "@1"}, print)  # Spot
    info.subscribe({"type": "activeAssetData", "user": address, "coin": "BTC"}, print)  # Perp only


if __name__ == "__main__":
    main()

Explanation

The info.subscribe(subscription, callback) method is the core of WebSocket functionality.

• subscription: A dictionary that defines the data channel you want to listen to.
• callback: A function that will be executed every time a message is received on that channel. In this example, we simply use print to display the raw message.

This script will run indefinitely, printing messages as they are received from the WebSocket server. You will need to manually stop it with Ctrl+C.

Available Subscription Types

Here are some of the key subscription channels demonstrated:

• {"type": "allMids"}: Provides a stream of all mid-market prices.
• {"type": "l2Book", "coin": "ETH"}: Streams Level 2 order book updates for a specific asset (ETH in this case).
• {"type": "trades", "coin": "PURR/USDC"}: Streams executed trades for a specific asset.
• {"type": "userEvents", "user": address}: A comprehensive stream for a specific user, including fills, order updates, and more. This is a powerful endpoint for tracking all account activity.
• {"type": "userFills", "user": address}: Streams only the trade fills for a specific user.
• {"type": "candle", "coin": "ETH", "interval": "1m"}: Streams updates for candlestick data at a specified interval.
• {"type": "orderUpdates", "user": address}: Streams updates related to your orders (placed, canceled, etc.).
• {"type": "webData2", "user": address}: Provides a rich stream of data used by the Hyperliquid frontend, including portfolio and margin information.
• {"type": "bbo", "coin": "ETH"}: Streams the best bid and offer for an asset.