# StreamOrderUpdates - Stream Order-Status Changes per Wallet

`StreamOrderUpdates` sends every order-status change of the orders that the requested wallets own. This covers placements, fills, cancels, rejections, and triggers. Each frame carries the changes of one applied block. It is the typed gRPC form of the WebSocket [`orderUpdates`](https://www.dwellir.com/docs/hyperliquid/order-updates) channel.

## Request and live-only behavior

`users` is required and must hold at least one 0x-prefixed address. Addresses match case-insensitively. An empty list or an empty-string entry returns `INVALID_ARGUMENT`. The zero address is accepted but has no special meaning.

Empty `coins` means every coin. Coin identifiers match exactly, and unknown coins never match. An empty-string or `"*"` coin entry returns `INVALID_ARGUMENT`. Optional `dexes` keeps only changes on the listed HIP-3 dexes: `xyz` matches `xyz:BTC`, and `""` matches coins without a dex prefix. A `"*"` entry or an entry that contains `:` returns `INVALID_ARGUMENT`. `users`, `coins`, and `dexes` combine with AND semantics.

The stream has no open-orders snapshot. It starts with the next applied block, as the public Hyperliquid channel does. 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.

Every block with order-status events produces a frame. When no change in the block matches your filters, the frame still arrives with an empty `orders` list, so `sequence` stays contiguous. A block without any order-status events sends no frame.

## Request Parameters

- `users` (`repeated string, required`): Required order-owner addresses, at least one. 0x-prefixed and matched case-insensitively; an empty list or an empty-string entry is invalid.
- `coins` (`repeated string, optional`): Optional exact coin scope; empty means all coins, unknown coins never match, and empty-string or wildcard entries are invalid.
- `dexes` (`repeated string, optional`): Optional HIP-3 dex filter; "" selects coins without a dex prefix, and empty means no filter. Wildcard entries and entries containing ":" are invalid.

## Request Example

```go
package main

import (
    "context"
    "crypto/tls"
    "log"
    "os"

    pb "example.com/hyperliquid-v3-client/gen/v3"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/metadata"
)

func main() {
    endpoint, apiKey := os.Getenv("HYPERLIQUID_GRPC_ENDPOINT"), os.Getenv("DWELLIR_API_KEY")
    if endpoint == "" || apiKey == "" {
        log.Fatal("set HYPERLIQUID_GRPC_ENDPOINT and DWELLIR_API_KEY")
    }
    conn, err := grpc.NewClient(endpoint, grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{MinVersion: tls.VersionTLS12})))
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()
    ctx := metadata.AppendToOutgoingContext(context.Background(), "x-api-key", apiKey)
    stream, err := pb.NewMarketStreamingClient(conn).StreamOrderUpdates(ctx, &pb.OrderUpdatesRequest{
        Users: []string{"0x1111111111111111111111111111111111111111"},
        Coins: []string{"BTC", "ETH"},
    })
    if err != nil {
        log.Fatal(err)
    }
    var last uint64
    for {
        update, err := stream.Recv()
        if err != nil {
            log.Fatal(err)
        }
        if update.GetSequence() != last+1 {
            log.Fatalf("sequence gap: got=%d expected=%d", update.GetSequence(), last+1)
        }
        last = update.GetSequence()
        for _, change := range update.GetOrders() {
            order := change.GetOrder()
            log.Printf("block=%d user=%s oid=%d coin=%s status=%s sz=%s", update.GetBlockNumber(), change.GetUser(), order.GetOid(), order.GetCoin(), change.GetStatus(), order.GetSz())
        }
    }
}
```

## Response Fields

- `time` (`int64, required`): Source block time in Unix milliseconds.
- `block_number` (`int64, required`): Sequential Hyperliquid block number.
- `sequence` (`uint64, required`): Per-subscription monotonic counter beginning at 1 on the first frame; a gap means loss.
- `orders` (`repeated OrderUpdate, required`): The block's matching order-status changes in block order; empty when the filters removed every change.
- `orders.user` (`string, required`): Order owner address.
- `orders.status` (`string, required`): Node status string, passed through, such as open, filled, canceled, triggered, or a rejection or cancel reason. The set is open-ended.
- `orders.status_timestamp` (`int64, required`): Block time of the change in Unix milliseconds.
- `orders.order` (`BasicOrder, required`): The order as of the change.
- `orders.order.coin` (`string, required`): Native coin identifier.
- `orders.order.side` (`string, required`): Native side B or A.
- `orders.order.limit_px` (`string, required`): Limit price as a decimal string.
- `orders.order.sz` (`string, required`): Size left on the order after the change, as the node reports it.
- `orders.order.oid` (`uint64, required`): Order identifier.
- `orders.order.timestamp` (`int64, required`): Order placement time in Unix milliseconds, not the frame's block time.
- `orders.order.orig_sz` (`string, required`): Size at placement as a decimal string.
- `orders.order.reduce_only` (`bool, required`): True for a reduce-only order.
- `orders.order.cloid` (`optional string, optional`): Client order identifier when the order has one.

## Successful Response

```protobuf
time: 1793000525681
block_number: 1058646974
sequence: 1
orders: {
  user: "0x1111111111111111111111111111111111111111"
  status: "filled"
  status_timestamp: 1793000525681
  order: {
    coin: "ZEC"
    side: "B"
    limit_px: "1201.5"
    sz: "0.0"
    oid: 586015384624
    timestamp: 1793000524947
    orig_sz: "2.71"
    cloid: "0x0e5aba75fd65e15b844cee1beb6f78fb"
  }
}
```

## Error Responses

### Invalid request

- Code: `INVALID_ARGUMENT`
- Description: users is empty or has an empty-string entry, or a coin or dex entry is malformed.

### Feature unavailable

- Code: `FAILED_PRECONDITION`
- Description: This stream is unavailable on the selected endpoint.

### View unavailable

- Code: `UNAVAILABLE`
- Description: The order view is not ready yet; retry.

### Lost order updates

- Code: `ABORTED`
- Description: Frame loss or a stream state reset ended this live-only stream; reconnect and refetch open orders.

### Slow consumer

- Code: `DEADLINE_EXCEEDED`
- Description: The consumer was too slow; reconnect.

### Unauthenticated

- Code: `UNAUTHENTICATED`
- Description: Usable x-api-key metadata was not supplied.

### Permission denied

- Code: `PERMISSION_DENIED`
- Description: The supplied credential cannot call this service.

## Statuses

`status` is the node status string, passed through unchanged. The set is open-ended: branch on the values you need and treat the rest as terminal. Common values are `open`, `filled`, `canceled`, and `triggered`. Rejection and cancel reasons include `badAloPxRejected`, `iocCancelRejected`, `perpMarginRejected`, `reduceOnlyCanceled`, `reduceOnlyRejected`, `selfTradeCanceled`, `minTradeNtlRejected`, `insufficientSpotBalanceRejected`, `marginCanceled`, `siblingFilledCanceled`, `liquidatedCanceled`, `scheduledCancel`, and `tooManyOpenOrdersRejected`.

One order can change twice in one block. Both changes arrive in block order. `order.sz` is the size left on the order after the change, as the node reports it. `order.timestamp` is the placement time, and `status_timestamp` is the block time of the change.

## Sequencing and recovery

Require each `sequence` to follow the last accepted value. The stream is live-only and incremental. A subscriber that falls behind gets `ABORTED`, and a stream state reset ends the stream the same way. On a gap or `ABORTED`, reconnect and refetch open orders. To recover the missed changes, replay from the last `block_number` you received with [StreamOrderStatuses](https://www.dwellir.com/docs/hyperliquid/stream_order_statuses) and its `users` filter, or use the [historical data](https://www.dwellir.com/docs/hyperliquid/historical-data). The replay position is inclusive, so skip the records of that block you already processed. Replayed records carry the raw node order-status envelope in `data`, not `OrderUpdate` messages. Common live-stream errors are listed on the [gRPC overview](https://www.dwellir.com/docs/hyperliquid/grpc#v3-market-streaming-service).

Order-status changes and fills come from different node feeds. A fill and the `filled` status of the same order can arrive in either order. Pair this stream with [StreamUserFills](https://www.dwellir.com/docs/hyperliquid/stream_user_fills) when you need execution details.

Related references: [StreamOrderStatuses](https://www.dwellir.com/docs/hyperliquid/stream_order_statuses) and [StreamL4OrderUpdates](https://www.dwellir.com/docs/hyperliquid/stream_l4_order_updates).
