WebSocket API Quick Reference
Quick reference for the Hyperliquid Order Book WebSocket API. Connection details, message formats, and links to detailed documentation.
Hyperliquid RPC endpoint: endpoint URLs, plans and pricing.
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://api-hyperliquid-mainnet-orderbook.n.dwellir.com/{API_KEY}/wsReplace {API_KEY} with the API key from your Dwellir dashboard. The Order Book add-on must be enabled on your API plan.
Quick Start
import asyncio
import json
import websockets
async def main():
ws_url = "wss://api-hyperliquid-mainnet-orderbook.n.dwellir.com/{API_KEY}/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())Subscription Types
Trades
{
"method": "subscribe",
"subscription": {
"type": "trades",
"coin": "BTC"
}
}| Parameter | Default | Description |
|---|---|---|
user | (none) | Optional. Filter to trades involving a specific wallet address |
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 |
L4 Order Book
{
"method": "subscribe",
"subscription": {
"type": "l4Book",
"coin": "BTC"
}
}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 backoffResources
- 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
Trades Stream
Stream real-time trade executions from Hyperliquid with ultra-low latency. Access price, size, direction, and participant data for every trade.
eth_blockNumber
Get the current block height on Hyperliquid. Essential for syncing dApps, monitoring transaction confirmations, and blockchain state tracking.