Stream real-time HIP-4 market data with WebSocket

The SDK maintains a single shared WebSocket connection to Hyperliquid and multiplexes all subscriptions over it. You subscribe to a market, receive a callback on every update, and call the returned unsubscribe function when you’re done. Reconnection and subscription restoration happen automatically in the background.

All subscriptions-order book, price, and trades-share one WebSocket connection. Opening multiple subscriptions does not open multiple connections.

subscribeOrderBook delivers a Level 2 book snapshot (bids and asks) for side 0 of the market on every change.

import { createHIP4Adapter } from "@outcome.xyz/hip4";

const hip4 = createHIP4Adapter({ testnet: true });
await hip4.initialize();

const unsub = hip4.marketData.subscribeOrderBook("516", (book) => {
  console.log("Bids:", book.bids.slice(0, 3)); // [{ price, size }, ...]
  console.log("Asks:", book.asks.slice(0, 3));
});

// Later - stop receiving updates
unsub();

subscribePrice delivers both sides of a market via Hyperliquid’s allMids feed. Side names come from the outcome’s sideSpecs once the adapter has loaded them, so call initialize() first. Until then, they read "Side 0" and "Side 1".

const unsub = hip4.marketData.subscribePrice("516", (price) => {
  const yes = price.outcomes[0]; // { name: "Yes", price: "0.65", midpoint: "0.65" }
  const no = price.outcomes[1]; // { name: "No",  price: "0.35", midpoint: "0.35" }

  console.log(`${yes.name}: ${yes.price} | ${no.name}: ${no.price}`);
});

// Stop when done
unsub();

subscribeTrades delivers each executed trade on side 0 of the market as it happens.

const unsub = hip4.marketData.subscribeTrades("516", (trade) => {
  console.log(
    `${trade.side} ${trade.size} @ ${trade.price} - ${new Date(trade.timestamp).toISOString()}`,
  );
});

// Stop when done
unsub();

Call your unsubscribe function when a component unmounts or a view is hidden to prevent memory leaks and avoid processing updates for stale data.

Unsubscribe is safe to call more than once - a second call is a no-op (handy under React Strict Mode, which runs effect cleanups twice). And when several parts of your app subscribe to the same market, one unsubscribing never stops updates for the others: the shared subscription is reference-counted and only torn down when the last subscriber leaves.

Auto-reconnect

The WebSocket reconnects automatically if the connection drops. The retry schedule uses exponential backoff starting at 1 second, capped at 30 seconds, with a maximum of 10 attempts. Once reconnected, all active subscriptions are restored without any action on your part.

Create a price feed for charting

createPriceFeed merges historical candles with live price ticks into a single continuously-updating snapshot. It’s designed to power live charts without you needing to stitch together the initial fetch and the real-time stream yourself.

import { createPriceFeed } from "@outcome.xyz/hip4";

const unsub = createPriceFeed(
  hip4.marketData,
  "516",
  (snap) => {
    if (!snap.ready) return; // still loading historical candles

    renderChart(snap.candles); // full candle array (historical + live)
    console.log("Current mid:", snap.currentMid);
  },
  {
    interval: "1h", // candle interval - default: "1h"
    lookbackMs: 7 * 24 * 60 * 60 * 1000, // 7 days of history - default: 14 days
    sideIndex: 0, // 0 = Yes side, 1 = No side - default: 0
  },
);

// Tear down the feed when no longer needed
unsub();

PriceFeedOptions

Field	Type	Default	Description
`interval`	`string`	`"1h"`	Candle interval accepted by Hyperliquid (e.g. `"1m"`, `"5m"`, `"1h"`, `"1d"`)
`lookbackMs`	`number`	14 days	How far back to fetch historical candles, in milliseconds
`sideIndex`	`number`	`0`	Which side’s live ticks to track: `0` for Yes, `1` for No

Historical candles always come from side 0, because fetchCandles reads side 0. With sideIndex: 1, only the live ticks follow side 1.

PriceFeedSnapshot

Field	Type	Description
`marketId`	`string`	The market ID passed to `createPriceFeed`
`candles`	`PriceFeedCandle[]`	Full OHLCV array: historical candles merged with live ticks
`currentMid`	`number \| null`	Latest mid-price received (may be newer than the last candle close)
`ready`	`boolean`	`false` until the initial candle fetch completes

subscribePositions delivers updated position data for a wallet address. It polls fetchPositions instead of using a WebSocket: you get the first result right away, then a new one 10 seconds after each poll finishes.

const unsub = hip4.account.subscribePositions(
  "0xYourWalletAddress",
  (positions) => {
    for (const pos of positions) {
      console.log(`${pos.outcomeName}: ${pos.shares} shares @ ${pos.avgCost}`);
    }
  },
);

// Stop polling when done
unsub();

​Subscribe to the order book

​Subscribe to live prices

​Subscribe to the trade stream

​Auto-reconnect

​Create a price feed for charting

​PriceFeedOptions

​PriceFeedSnapshot

​Subscribe to account positions

Subscribe to the order book

Subscribe to live prices

Subscribe to the trade stream

Auto-reconnect

Create a price feed for charting

PriceFeedOptions

PriceFeedSnapshot

Subscribe to account positions