Hyperliquid orderUpdates WebSocket: Order Lifecycle Tracking

Scope and Purpose of the orderUpdates Channel

The Hyperliquid orderUpdates channel is a user-scoped WebSocket subscription. It delivers order state transitions only for the account specified in the subscription request. A public market-data feed cannot substitute for it because order updates are private to the authenticated user. According to the Hyperliquid WebSocket subscriptions documentation, the subscribe message includes a type and a subscription object naming the channel and, for user-scoped channels, the user address.

This channel is essential for applications that need real-time visibility into order lifecycle events, such as trading dashboards, order management systems, and automated strategies. It complements the read-only Hyperliquid order status over the info API by providing push-based updates, but it does not replace historical queries. For a broader overview of Hyperliquid connectivity, see the Hyperliquid network page.

• User-scoped: only delivers orders for the subscribed account.
• Requires a valid subscription message with the user address.
• Complements, but does not replace, the info API for history.

Subscribe Message Format and Channel Identification

To receive order updates, a client sends a JSON-RPC 2.0 subscribe request over an established WebSocket connection. The request must include a subscription object with the channel name and the user address. The exact field names and any additional parameters are documented and may vary by API version, so always verify against the current payload. The JSON-RPC 2.0 specification defines the request/response semantics, while the Ethereum JSON-RPC specification provides a reference for similar subscription patterns, though Hyperliquid has its own implementation.

A typical subscribe message looks like the code example below. Note that the user address must be lowercase or checksummed as required by the API. After subscribing, the server will begin sending orderUpdates messages for that user.

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

ws.on('open', () => {
  const subscribeMsg = {
    method: 'subscribe',
    subscription: {
      type: 'orderUpdates',
      user: '0xYourAddressHere'
    }
  };
  ws.send(JSON.stringify(subscribeMsg));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.channel === 'orderUpdates') {
    console.log('Order update:', msg.data);
  }
});

Order Object Fields and Snapshot Semantics

Each orderUpdates message contains a full snapshot of an order, not a delta. The payload includes fields such as coin, oid (order ID), cloid (client order ID), side, order type, price, size, original size, status, and timestamps. Exact field names and additional fields are documented and may vary by API version, so always inspect the live payload. Because the message is a snapshot, the correct client behavior is to upsert the order by its identifier (oid or cloid) rather than apply an increment. A client that treats messages as deltas will double-count partial fills.

For example, if an order is partially filled, the size field reflects the remaining size, and the status indicates the current state. The original size remains constant. This design simplifies state management: you always have the current order state without needing to replay history. However, it also means that if you miss a message, your local state becomes stale until the next update or reconciliation.

• Snapshot, not delta: replace the entire order record on each update.
• Key by oid or cloid to upsert correctly.
• Fields like size and status reflect the current state.

Order Status Vocabulary and State Transitions

The order status field encodes the lifecycle stage. An order is created with status 'open'. It may then transition to 'partially filled' as fills occur, and eventually terminate in 'filled', 'cancelled', or 'rejected'. The exact status strings are documented and may vary by API version, so verify against the current documentation. A client must key its state machine on the status field rather than on the arrival order of messages, because WebSocket messages can arrive out of order or be delayed.

Understanding these transitions is crucial for building a reliable order tracker. For instance, an order might go from open to partially filled to filled, or from open to cancelled. Rejected orders may never appear as open. The Hyperliquid order rejection handling guide covers error decoding for rejected orders. Always treat the status as the authoritative indicator of the order's current state.

• open: order is active and unfilled.
• partially filled: some quantity has been executed.
• filled: completely executed.
• cancelled: cancelled by user or system.
• rejected: not accepted by the exchange.

Reconciling the Live Stream with the Info API

A WebSocket subscription only delivers events observed while the socket is open. Any reconnect or process restart loses the transitions that occurred while disconnected. Therefore, the only correct way to rebuild order history is to reconcile against the info-API read path. The Hyperliquid info endpoint documentation describes endpoints such as historicalOrders, frontendOpenOrders, and userFills. These provide the authoritative order set.

On reconnect, re-issue the subscribe, then pull the authoritative order set from the info API and diff it against your local snapshot. Treat the info-API result as the source of truth. This ensures that any missed updates are corrected. For a deeper dive into the info API order surface, see Hyperliquid order status over the info API.

• WebSocket is live-only; history requires the info API.
• On reconnect, re-subscribe and fetch authoritative orders.
• Diff local state against info API and apply corrections.

Building a Resumable Order Tracker in Node.js

To make the stream resumable, record the last observed order state per oid in a local store. On reconnect, re-issue the subscribe, then fetch the authoritative order set from the info API and diff it against your local snapshot. The code example below demonstrates a minimal implementation using Node.js and the ws library. It maintains a Map of orders keyed by oid, updates it on each orderUpdates message, and on reconnect fetches open orders from the info API to reconcile.

This pattern ensures that your local state remains consistent even if the WebSocket connection drops. Note that the info API call is a POST request to the /info endpoint with a JSON body specifying the type and user. The exact request format is documented and may vary by API version.

const WebSocket = require('ws');
const fetch = require('node-fetch');

const user = '0xYourAddressHere';
const orders = new Map(); // oid -> order snapshot

async function fetchOpenOrders() {
  const res = await fetch('https://api.hyperliquid.xyz/info', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ type: 'frontendOpenOrders', user })
  });
  return res.json();
}

async function reconcile() {
  const openOrders = await fetchOpenOrders();
  for (const order of openOrders) {
    orders.set(order.oid, order);
  }
  console.log('Reconciled', orders.size, 'orders');
}

function connect() {
  const ws = new WebSocket('wss://api.hyperliquid.xyz/ws');
  ws.on('open', () => {
    ws.send(JSON.stringify({
      method: 'subscribe',
      subscription: { type: 'orderUpdates', user }
    }));
    reconcile();
  });
  ws.on('message', (data) => {
    const msg = JSON.parse(data);
    if (msg.channel === 'orderUpdates') {
      for (const update of msg.data) {
        orders.set(update.oid, update);
      }
    }
  });
  ws.on('close', () => {
    setTimeout(connect, 1000);
  });
}

connect();

Measurement Method and Results Table

To verify the behavior of the orderUpdates channel against your own endpoint, you can instrument your client to log the sequence of statuses for a test order. Place a small order, then record each orderUpdates message with its timestamp, oid, status, and size. After the order reaches a terminal state, compare the observed sequence against the expected lifecycle. This method is reproducible and does not rely on fabricated benchmarks.

Use the table below to record your observations. Fill in the actual values from your test. This helps you confirm that your client correctly handles snapshots and transitions.

• Timestamp: when the message was received.
• oid: order identifier.
• Status: reported status string.
• Size: remaining size.
• Expected next state: based on lifecycle.

Limitations and Tradeoffs of the orderUpdates Channel

The orderUpdates channel is not a complete history. It only delivers events while the socket is open, so any disconnection creates gaps. It also does not provide fills directly; for fill-level detail, use the Hyperliquid trades and userFills channels. Additionally, the channel is user-scoped, so it cannot be used for market-wide order book monitoring. For liveness detection, see Hyperliquid WebSocket heartbeat detection.

Another tradeoff is that snapshot messages can be larger than deltas, increasing bandwidth. However, the simplicity of upserting by oid often outweighs this cost. Finally, the exact field names and status strings are documented and may vary by API version, so clients must be prepared to adapt.

• No history: gaps on disconnect.
• User-scoped: not for public market data.
• Snapshot size may be larger than deltas.
• Field names may vary by API version.

Troubleshooting Common Issues

If you are not receiving orderUpdates messages, first verify that your subscribe message is correctly formatted and that the user address matches the account. Check that the WebSocket connection is open and that you are not being rate-limited. For rate limits and endpoint health, refer to the Hyperliquid RPC endpoints (RPC Assistant). If messages arrive but your local state is incorrect, ensure you are upserting by oid and not applying deltas.

If you see duplicate or out-of-order messages, rely on the status field and timestamps to resolve conflicts. Always reconcile with the info API after reconnects. For error handling, see Hyperliquid order rejection handling.

• Verify subscription format and user address.
• Check WebSocket connection and rate limits.
• Upsert by oid; do not apply deltas.
• Reconcile with info API on reconnect.

Next Steps and Further Resources

To deepen your understanding, explore the OnFinality Learn hub for more guides on Hyperliquid and WebSocket mechanics. If you need reliable RPC endpoints for your application, consider the API service and review RPC pricing for options. For a complete list of Hyperliquid endpoints, see the Hyperliquid RPC endpoints (RPC Assistant).

You can also review the official Hyperliquid WebSocket subscriptions documentation and the info endpoint documentation for the latest details. Always test your implementation against the live API to ensure compatibility.

• Explore more guides on OnFinality Learn.
• Consider OnFinality API service for reliable endpoints.
• Review official Hyperliquid documentation for updates.