# Order Updates - Order-Status Changes per Wallet

The `orderUpdates` channel pushes every order-status change of the wallets you subscribe to. This covers placements, fills, cancels, rejections, and triggers. Each message carries the changes of one applied block.

Frames use the public Hyperliquid `orderUpdates` shape, so clients written against the public channel work unchanged. The `users`, `coins`, `dexes`, and `sequence` parameters are Dwellir extensions. The typed gRPC form of this channel is [StreamOrderUpdates](https://www.dwellir.com/docs/hyperliquid/stream_order_updates).

## How to Subscribe

Send a subscription message to the WebSocket endpoint:

```json
{
  "method": "subscribe",
  "subscription": {
    "type": "orderUpdates",
    "user": "0x1111111111111111111111111111111111111111"
  }
}
```

To follow several wallets, or to narrow the stream, use the extension parameters:

```json
{
  "method": "subscribe",
  "subscription": {
    "type": "orderUpdates",
    "users": [
      "0x1111111111111111111111111111111111111111",
      "0x2222222222222222222222222222222222222222"
    ],
    "coins": ["xyz:NVDA"],
    "dexes": ["xyz"],
    "sequence": true
  }
}
```

### Subscription Parameters

| Parameter  | Type         | Required                 | Description                                                                                                                                               |
| ---------- | ------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`     | string       | Yes                      | Must be `"orderUpdates"`                                                                                                                                  |
| `user`     | string       | One of `user` or `users` | Order owner. A 0x-prefixed address, matched case-insensitively. This is the public form                                                                   |
| `users`    | string array | One of `user` or `users` | Extension. Several order owners on one subscription. Each element then carries an added `user` field that names the owner                                 |
| `coins`    | string array | No                       | Extension. Keeps only these coins. Absent or empty means all coins. Unknown coins never match                                                             |
| `dexes`    | string array | No                       | Extension. Keeps only coins on these HIP-3 dexes: `"xyz"` matches `xyz:BTC`, and `""` matches coins without a dex prefix. Absent or empty means no filter |
| `sequence` | boolean      | No                       | Extension. Adds a contiguous `sequence` counter to each frame and sends frames that the filters emptied                                                   |

`user` and `users` are mutually exclusive. `coins` and `dexes` combine with AND semantics. A one-entry `users` list is a different subscription from `user`, because the element shapes differ.

These subscriptions fail with an `Invalid subscription` error frame:

- neither `user` nor `users`, or both;
- the zero address in `user` or `users`;
- a `users` or `coins` list whose entries are all empty strings;
- a `coin` or `selector` field;
- a `"*"` entry in `dexes`, or an entry that contains `:`.

The subscription response echoes `users`, `coins`, and `dexes` sorted and deduplicated, with `users` addresses in lowercase.

### No Open-Orders Snapshot

The public channel sends no open-orders snapshot on subscribe, and neither does Dwellir. The stream starts with the next applied block. To get the current open orders, query [`openOrders`](https://www.dwellir.com/docs/hyperliquid/open-orders) or [`frontendOpenOrders`](https://www.dwellir.com/docs/hyperliquid/frontend-open-orders) on the Info endpoint.

The first websocket message after subscribing is a `subscriptionResponse`; subsequent messages carry the `orderUpdates` channel payloads.

## Request Parameters

- `type` (`string, required`): Subscription parameter: Must be `"orderUpdates"`
- `user` (`string, optional`): Subscription parameter: Order owner, a 0x-prefixed address matched case-insensitively. Required unless `users` is set; the zero address is rejected.
- `users` (`string array, optional`): Subscription parameter (extension): Several order owners. Required unless `user` is set; each element then carries an added `user` field.
- `coins` (`string array, optional`): Subscription parameter (extension): Coin filter. Absent or empty means all coins; unknown coins never match.
- `dexes` (`string array, optional`): Subscription parameter (extension): HIP-3 dex filter. `"xyz"` matches `xyz:BTC`, and `""` matches coins without a dex prefix.
- `sequence` (`boolean, optional`): Subscription parameter (extension): Adds a contiguous `sequence` counter and sends frames that the filters emptied.

## Request Example

```json
{
  "method": "subscribe",
  "subscription": {
    "type": "orderUpdates",
    "user": "0x1111111111111111111111111111111111111111"
  }
}
```

## Response Fields

- `channel` (`string, required`): Always `"orderUpdates"` for this subscription type
- `data` (`array, required`): Order-status changes of one applied block, in block order
- `data.order` (`object, required`): The order as of the change
- `data.order.coin` (`string, required`): Native coin name: `BTC`, `@N` for spot, `#N` for outcomes, `dex:COIN` for HIP-3
- `data.order.side` (`string, required`): `"B"` or `"A"`
- `data.order.limitPx` (`string, required`): Limit price
- `data.order.sz` (`string, required`): Size left on the order after the change, as the node reports it
- `data.order.oid` (`number, required`): Order ID
- `data.order.timestamp` (`number, required`): Placement time, Unix milliseconds
- `data.order.origSz` (`string, required`): Size at placement
- `data.order.reduceOnly` (`boolean, optional`): Present only when `true`
- `data.order.cloid` (`string, optional`): Present only when the order has a client order ID
- `data.status` (`string, required`): Node status, passed through, such as `open`, `filled`, `canceled`, or a rejection reason. The set is open-ended.
- `data.statusTimestamp` (`number, required`): Block time of the change, Unix milliseconds
- `data.user` (`string, optional`): Extension, `users` subscriptions only: the order owner
- `sequence` (`number, optional`): Extension, `"sequence": true` subscriptions only: starts at 1 and increments on every frame

## Successful Response

```json
{
  "channel": "orderUpdates",
  "data": [
    {
      "order": {
        "coin": "ZEC",
        "side": "B",
        "limitPx": "1201.5",
        "sz": "0.0",
        "oid": 586015384624,
        "timestamp": 1793000524947,
        "origSz": "2.71",
        "cloid": "0x0e5aba75fd65e15b844cee1beb6f78fb"
      },
      "status": "filled",
      "statusTimestamp": 1793000525681
    }
  ]
}
```

## Error Responses

### Invalid subscription

- Description: Neither or both of `user` and `users`, a zero address, a `users` or `coins` list with only empty-string entries, a `coin` or `selector` field, or a `"*"` or `:` entry in `dexes`.

```json
{"channel": "error", "data": "Invalid subscription: {\"method\":\"subscribe\",\"subscription\":{\"type\":\"orderUpdates\",\"user\":\"0x1111111111111111111111111111111111111111\",\"users\":[\"0x2222222222222222222222222222222222222222\"]}}"}
```

### Resync required

- Description: The subscriber fell behind. The connection closes after this frame; reconnect, resubscribe, and refetch open orders.

```json
{"channel": "error", "data": "resync required: broadcast lagged, incremental stream state is invalid"}
```

### Stream state reset

- Description: The stream state was reset. The connection then closes with code `1013` and a reason such as `"not ready; retry after 5s"`. Wait that many seconds, then reconnect, resubscribe, and refetch open orders.

```json
{"channel": "error", "data": "market state reset; resubscribe when ready"}
```

## Response Field Reference

```json
{"channel":"orderUpdates","data":[
  {"order":{"coin":"ZEC","side":"B","limitPx":"1201.5","sz":"0.0","oid":586015384624,
            "timestamp":1793000524947,"origSz":"2.71","cloid":"0x0e5aba75fd65e15b844cee1beb6f78fb"},
   "status":"filled","statusTimestamp":1793000525681}
]}
```

`data` is an array of changes in block order. Each element has these fields:

| Field              | Type    | Description                                                                     |
| ------------------ | ------- | ------------------------------------------------------------------------------- |
| `order.coin`       | string  | Native coin name: `BTC`, `@N` for spot, `#N` for outcomes, `dex:COIN` for HIP-3 |
| `order.side`       | string  | `"B"` or `"A"`                                                                  |
| `order.limitPx`    | string  | Limit price                                                                     |
| `order.sz`         | string  | Size left on the order after the change, as the node reports it                 |
| `order.oid`        | number  | Order ID                                                                        |
| `order.timestamp`  | number  | Placement time, Unix milliseconds                                               |
| `order.origSz`     | string  | Size at placement                                                               |
| `order.reduceOnly` | boolean | Present only when `true`                                                        |
| `order.cloid`      | string  | Present only when the order has a client order ID                               |
| `status`           | string  | Node status, passed through. See [Statuses](#statuses)                          |
| `statusTimestamp`  | number  | Block time of the change, Unix milliseconds                                     |
| `user`             | string  | Extension, `users` subscriptions only. The order owner                          |

With `"sequence": true`, the envelope gains a `sequence` field after `data`. The `data` array keeps its public shape:

```json
{"channel":"orderUpdates","data":[],"sequence":2}
```

`sequence` starts at 1 and increments on every frame. With it on, a block that the filters emptied still sends a frame with `"data":[]`. Without it, such a block sends nothing. A block with no order-status events sends nothing in either mode.

## Statuses

The status set is open-ended. Branch on the values you need and treat the rest as terminal.

- Seen on the public channel: `open`, `filled`, `canceled`, `badAloPxRejected`, `iocCancelRejected`, `perpMarginRejected`.
- Also seen in the node feed: `triggered`, `reduceOnlyCanceled`, `reduceOnlyRejected`, `selfTradeCanceled`, `minTradeNtlRejected`, `insufficientSpotBalanceRejected`, `marginCanceled`, `siblingFilledCanceled`, `liquidatedCanceled`, `scheduledCancel`, `tooManyOpenOrdersRejected`.

One order can change twice in one block. Both changes arrive, in order.

## Ordering and Delivery

- At most one frame per applied block. Changes keep the node's event order across all subscribed wallets.
- Order updates and fills come from different node feeds. A fill and the `filled` status of the same order can arrive in either order. For execution prices and sizes, add a [Trades](https://www.dwellir.com/docs/hyperliquid/trades) subscription with a `user` filter.
- The channel is incremental. A subscriber that falls behind gets an error frame that starts with `"resync required: "`, and the connection closes. Reconnect, resubscribe, and refetch open orders.
- After a stream state reset, the error frame reads `"market state reset; resubscribe when ready"`. The connection then closes with code `1013` and a reason such as `"not ready; retry after 5s"`. Wait that many seconds, then reconnect, resubscribe, and refetch open orders.

## Known Differences from the Public Channel

- **TWAP slice orders.** The public channel sent no frame for TWAP slice orders during Dwellir's comparison capture. If the node writes status events for slice orders, Dwellir forwards them.
- **`filled` size.** On the public channel, `order.sz` on a `filled` change is often not `"0.0"`. Dwellir forwards the node's value.

## Use Cases

- **Order management:** confirm placements, cancels, and rejections for your own wallets without polling.
- **Rejection monitoring:** alert on reasons such as `perpMarginRejected` or `badAloPxRejected`.
- **Multi-wallet tracking:** follow many wallets on one subscription with `users`.
- **Gap detection:** use `sequence: true` to detect lost frames.

## Get Access

Ready to integrate real-time Hyperliquid order updates?

- **[Volume Calculator](https://www.dwellir.com/hyperliquid-orderbook#calculator)** - Estimate monthly message volume
- **[Contact Sales](mailto:support@dwellir.com)** - Get your WebSocket credentials
- **[Dashboard](https://dashboard.dwellir.com)** - Manage your subscription
