WebSocket overview - Omnibook API

wss://api.omnibook.xyz/v1/ws

One connection carries every channel. Use it instead of polling, the private channel gives you a live copy of your orders, positions and balances without a single GET.

Authenticating the handshake

The upgrade request carries the same three DX-ACCESS-* headers as REST. The canonical string is fixed:

<timestamp>\nGET\n/v1/ws\n

with an empty body. A bad signature is rejected with 401. There is no anonymous WebSocket access.

import base64, hashlib, hmac, time
import websocket   # pip install websocket-client

API_KEY = "<your alphanumeric API key>"
SECRET = bytes.fromhex("<your 64-char hex secret>")
ts = str(int(time.time() * 1000))
sig = base64.b64encode(
    hmac.new(SECRET, f"{ts}\nGET\n/v1/ws\n".encode(), hashlib.sha256).digest()
).decode()

ws = websocket.create_connection(
    "wss://api.omnibook.xyz/v1/ws",
    header=[
        f"DX-ACCESS-KEY: {API_KEY}",
        f"DX-ACCESS-TIMESTAMP: {ts}",
        f"DX-ACCESS-SIGNATURE: {sig}",
    ],
)

The ±5 second clock window applies here too. Because it is checked once at handshake, a long-lived connection is unaffected by later drift, but a reconnect with a stale clock will fail.

Commands

Client to server:

{ "id": 1, "cmd": "subscribe", "params": { "channels": ["orderbook_snapshot"], "market_ids": [66] } }

cmd is subscribe, unsubscribe, list_subscriptions, or update_subscription. id is yours and is echoed back. Per-market public channels need market_ids on subscribe; one subscription can span markets from different assets. The two global channels (oracle, rounds) and the private user channel have no market set — in a mixed subscribe the market_ids you send apply to the per-market channels and are ignored for these three. market_ids is only required when the request includes a per-market channel; omitting it otherwise is fine, and omitting it when one is present is wscode 9. The reply assigns a subscription id, one per channel:

{ "id": 1, "type": "subscribed", "sid": 3, "channel": "orderbook_snapshot" }

To refresh an orderbook without tearing down the subscription:

{ "id": 2, "cmd": "update_subscription",
  "params": { "sid": 3, "action": "get_snapshot", "market_ids": [66] } }

Actions: get_snapshot, add_markets, delete_markets. The ack is type: "updated" with the resulting market set, then any snapshots.

Data envelope

{ "sid": 3, "seq": 17, "type": "orderbook_delta", "msg": { "...": "..." } }

seq is per subscription and contiguous from 1.

A gap in seq means you lost data. Public channels have no replay. Prefer update_subscription with action: "get_snapshot" to re-baseline without dropping the subscription; a full unsubscribe/resubscribe also works and starts a fresh seq from 1.Track seq per sid and treat any hole as a re-baseline, not as something to paper over. The private user channel is the exception: it has its own channel_seq and supports replay.

Command errors

{ "id": 1, "type": "error", "msg": { "wscode": 6, "text": "already subscribed" } }

`wscode`	Meaning
1	Unable to process
2	Params required
3	Unknown command
4	Unknown channel
5	Unknown sid
6	Already subscribed
7	Auth or scope insufficient
8	Invalid parameter
9	`market_ids` required
10	Rate limited (read bucket; see Rate limits)

Live channels

Six channels are implemented: orderbook_snapshot, orderbook_delta, trades, user, oracle, and rounds. The ticker display feed is deferred, subscribing returns wscode 4. See Channels for what each one carries.

oracle and rounds are global across every asset. One subscription receives ticks from all three price feeds and lifecycle events from all nine series, interleaved, and there is no server-side filter. Every frame names its origin — feed on oracle, category on rounds — so scope them client-side. See Series, assets, and categories.

WebSocket quickstart, complete runnable script
Channels, what each feed carries
Orderbook responses, interpreting L2 levels

​Authenticating the handshake

​Commands

​Data envelope

​Command errors

​Live channels

​Next

Authenticating the handshake

Commands

Data envelope

Command errors

Live channels

Next