WebSocket API Quick Reference

Quick reference for connecting to and using the Hyperliquid Order Book WebSocket API. For detailed documentation on each subscription type, see the individual pages.

Detailed Documentation#

Subscription	Description	Documentation
Trades	Real-time trade executions	View Trades Docs →
L2 Order Book	Aggregated price levels	View L2 Docs →
L4 Order Book	Individual order visibility	View L4 Docs →

For an overview of all subscription types and use cases, see the Order Book Server Overview.

Connection#

wss://<your-instance>.dwellir.com/ws

Contact ben@dwellir.com for server credentials.

Quick Start#

Python
JavaScript

import asyncio
import json
import websockets

async def main():
    ws_url = "wss://your-instance.dwellir.com/ws"

    async with websockets.connect(ws_url) as websocket:
        # Subscribe to BTC trades
        await websocket.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "trades", "coin": "BTC"}
        }))

        async for message in websocket:
            print(json.loads(message))

asyncio.run(main())

const WebSocket = require('ws');
const ws = new WebSocket('wss://your-instance.dwellir.com/ws');

ws.on('open', () => {
    ws.send(JSON.stringify({
        method: 'subscribe',
        subscription: { type: 'trades', coin: 'BTC' }
    }));
});

ws.on('message', (data) => console.log(JSON.parse(data)));

Subscription Types#

Trades#

{
  "method": "subscribe",
  "subscription": {
    "type": "trades",
    "coin": "BTC"
  }
}

Full Trades Documentation →

L2 Order Book#

{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "BTC",
    "nSigFigs": 5,
    "nLevels": 20
  }
}

Parameter	Default	Range	Description
`nSigFigs`	5	2-5	Price aggregation significant figures
`nLevels`	20	1-100	Number of price levels per side

Full L2 Documentation →

L4 Order Book#

{
  "method": "subscribe",
  "subscription": {
    "type": "l4Book",
    "coin": "BTC"
  }
}

Full L4 Documentation →

Unsubscribe#

{
  "method": "unsubscribe",
  "subscription": {
    "type": "trades",
    "coin": "BTC"
  }
}

Server Messages#

Subscription Confirmation#

{
  "channel": "subscriptionResponse",
  "data": {
    "method": "subscribe",
    "subscription": { "type": "trades", "coin": "BTC" }
  }
}

Error Response#

{
  "channel": "error",
  "data": "Invalid subscription: coin not found"
}

Common Errors#

Error	Cause
`"coin not found"`	Invalid trading pair symbol
`"n_levels too high"`	Requested more than 100 levels
`"Already subscribed"`	Duplicate subscription
`"Order book not ready"`	Server initializing

Response Channels#

Channel	Subscription Type
`trades`	Trades stream
`l2Book`	L2 order book
`l4Book`	L4 order book
`subscriptionResponse`	Subscription confirmations
`error`	Error messages

Reconnection#

The server may restart to resync state. Implement automatic reconnection:

async def connect_with_retry():
    delay = 1
    while True:
        try:
            async with websockets.connect(ws_url) as ws:
                delay = 1  # Reset on success
                await handle_connection(ws)
        except Exception:
            await asyncio.sleep(delay)
            delay = min(delay * 2, 60)  # Exponential backoff

Resources#

Code Examples - Complete Python examples
Volume Calculator - Estimate monthly usage
Contact - Get access credentials

For detailed documentation, visit the individual subscription pages: Trades | L2 Book | L4 Book