WebSocket Feeds

Real-time market data is available via Hyperliquid's WebSocket API.

Connection

const ws = new WebSocket("wss://api.hyperliquid.xyz/ws");

ws.onopen = () => {
  console.log("Connected");
  // Subscribe to channels
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  handleMessage(data);
};

ws.onerror = (error) => {
  console.error("WebSocket error:", error);
};

ws.onclose = () => {
  console.log("Disconnected");
  // Implement reconnection logic
};

Subscription Format

// Subscribe
ws.send(JSON.stringify({
  method: "subscribe",
  subscription: {
    type: "CHANNEL_TYPE",
    // channel-specific parameters
  }
}));

// Unsubscribe
ws.send(JSON.stringify({
  method: "unsubscribe",
  subscription: {
    type: "CHANNEL_TYPE",
    // channel-specific parameters
  }
}));

Available Channels

Order Book (l2Book)

Real-time order book updates.

// Subscribe
ws.send(JSON.stringify({
  method: "subscribe",
  subscription: {
    type: "l2Book",
    coin: "SOXX"
  }
}));

Response:

{
  "channel": "l2Book",
  "data": {
    "coin": "SOXX",
    "levels": [
      [
        [["225.00", "10.5"], ["224.99", "5.2"]],  // bids
        [["225.01", "8.3"], ["225.02", "12.1"]]   // asks
      ]
    ],
    "time": 1705330800000
  }
}

Trades

Real-time trade feed.

ws.send(JSON.stringify({
  method: "subscribe",
  subscription: {
    type: "trades",
    coin: "SOXX"
  }
}));

Response:

{
  "channel": "trades",
  "data": [
    {
      "coin": "SOXX",
      "side": "B",           // B = buy, A = sell (aggressor)
      "px": "225.05",
      "sz": "2.5",
      "time": 1705330800123
    }
  ]
}

All Mids

Real-time mid prices for all assets.

ws.send(JSON.stringify({
  method: "subscribe",
  subscription: {
    type: "allMids"
  }
}));

Response:

{
  "channel": "allMids",
  "data": {
    "mids": {
      "SOXX": "225.025",
      "KODEX": "45000.50"
    }
  }
}

User Events

Real-time updates for your account (requires auth).

ws.send(JSON.stringify({
  method: "subscribe",
  subscription: {
    type: "user",
    user: "0xYourAddress"
  }
}));

Response types:

// Order fill
{
  "channel": "user",
  "data": {
    "type": "fill",
    "coin": "SOXX",
    "px": "225.00",
    "sz": "10",
    "side": "B",
    "time": 1705330800123,
    "oid": 12345
  }
}

// Order update
{
  "channel": "user",
  "data": {
    "type": "order",
    "order": {
      "oid": 12345,
      "coin": "SOXX",
      "side": "B",
      "limitPx": "224.50",
      "sz": "10",
      "status": "open"
    }
  }
}

// Position update
{
  "channel": "user",
  "data": {
    "type": "position",
    "position": {
      "coin": "SOXX",
      "szi": "10",
      "entryPx": "225.00",
      "unrealizedPnl": "5.50"
    }
  }
}

Candles

OHLCV candlestick data.

ws.send(JSON.stringify({
  method: "subscribe",
  subscription: {
    type: "candle",
    coin: "SOXX",
    interval: "1m"  // 1m, 5m, 15m, 1h, 4h, 1d
  }
}));

Response:

{
  "channel": "candle",
  "data": {
    "coin": "SOXX",
    "interval": "1m",
    "candle": {
      "t": 1705330800000,  // timestamp
      "o": "225.00",       // open
      "h": "225.50",       // high
      "l": "224.80",       // low
      "c": "225.25",       // close
      "v": "1234.5"        // volume
    }
  }
}

Ping/Pong

Maintain connection with periodic pings:

setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ method: "ping" }));
  }
}, 30000);  // Every 30 seconds

Server responds with:

{ "channel": "pong" }

Reconnection

Implement robust reconnection:

class ReconnectingWebSocket {
  constructor(url, protocols) {
    this.url = url;
    this.protocols = protocols;
    this.reconnectDelay = 1000;
    this.maxDelay = 30000;
    this.connect();
  }

  connect() {
    this.ws = new WebSocket(this.url, this.protocols);

    this.ws.onopen = () => {
      this.reconnectDelay = 1000;  // Reset delay
      this.resubscribe();
    };

    this.ws.onclose = () => {
      setTimeout(() => this.connect(), this.reconnectDelay);
      this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxDelay);
    };
  }

  resubscribe() {
    // Re-subscribe to all channels
    this.subscriptions.forEach(sub => {
      this.ws.send(JSON.stringify({
        method: "subscribe",
        subscription: sub
      }));
    });
  }
}

Example: Price Monitor

const WebSocket = require("ws");

const ws = new WebSocket("wss://api.hyperliquid.xyz/ws");

ws.on("open", () => {
  console.log("Connected to Hyperliquid WS");

  // Subscribe to SOXX trades
  ws.send(JSON.stringify({
    method: "subscribe",
    subscription: { type: "trades", coin: "SOXX" }
  }));

  // Subscribe to mid prices
  ws.send(JSON.stringify({
    method: "subscribe",
    subscription: { type: "allMids" }
  }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(data);

  if (msg.channel === "trades") {
    const trade = msg.data[0];
    console.log(`Trade: ${trade.side} ${trade.sz} @ $${trade.px}`);
  }

  if (msg.channel === "allMids") {
    const soxxMid = msg.data.mids["SOXX"];
    console.log(`SOXX Mid: $${soxxMid}`);
  }
});

// Keep alive
setInterval(() => {
  ws.send(JSON.stringify({ method: "ping" }));
}, 30000);

Example: Order Book Tracker

class OrderBookTracker {
  constructor(coin) {
    this.coin = coin;
    this.bids = new Map();
    this.asks = new Map();
    this.connect();
  }

  connect() {
    this.ws = new WebSocket("wss://api.hyperliquid.xyz/ws");

    this.ws.on("open", () => {
      this.ws.send(JSON.stringify({
        method: "subscribe",
        subscription: { type: "l2Book", coin: this.coin }
      }));
    });

    this.ws.on("message", (data) => {
      const msg = JSON.parse(data);
      if (msg.channel === "l2Book") {
        this.updateBook(msg.data.levels[0]);
      }
    });
  }

  updateBook(levels) {
    const [bids, asks] = levels;

    // Update bids
    this.bids.clear();
    bids.forEach(([price, size]) => {
      this.bids.set(price, parseFloat(size));
    });

    // Update asks
    this.asks.clear();
    asks.forEach(([price, size]) => {
      this.asks.set(price, parseFloat(size));
    });
  }

  getBestBid() {
    return Math.max(...this.bids.keys());
  }

  getBestAsk() {
    return Math.min(...this.asks.keys());
  }

  getSpread() {
    return this.getBestAsk() - this.getBestBid();
  }
}

Rate Limits

Limit	Value
Subscriptions per connection	100
Connections per IP	10
Messages per second	100

Best Practices

1. Use single connection — Subscribe to multiple channels on one socket

2. Handle reconnects — Network issues will happen

3. Ping regularly — Prevent idle disconnection

4. Process async — Don't block message handler

5. Buffer updates — Batch processing for high-frequency data