Orderbooks

Endpoint

wss://api.rivermarkets.com/v1/ws/orderbooks

A single WebSocket connection can subscribe to any number of markets. The server pushes a snapshot on subscribe and updates every time the orderbook changes.

Authentication

Browsers can’t set custom headers on the WebSocket handshake, so the signed-request flow moves to query params. The signature covers WS\nPATH\nSORTED_QUERY (excluding key_id/ts/sig)\nTIMESTAMP. See Authentication for the full recipe.

The official SDKs sign the handshake for you.

Signed handshake

wss://api.rivermarkets.com/v1/ws/orderbooks?key_id=<uuid>&ts=<unix>&sig=<b64-sig>

For first-party web clients, authenticate with a Supabase JWT carried in the subprotocol list — browsers cannot set headers on a WS upgrade, and a token in the query string would be written into every intermediary’s request log:

new WebSocket(url, ['river.jwt', `river.jwt.${accessToken}`])

The server selects the bare river.jwt marker, so the token never appears in a response either. Invalid or missing auth closes the connection with code 4401.

Protocol

All frames are JSON. Client frames are text; server frames are bytes (orjson-serialized UTF-8).

Client → server

{ "action": "subscribe",   "river_ids": [12345, 67890] }
{ "action": "unsubscribe", "river_ids": [12345] }

subscribe / unsubscribe accept one or many river_ids. Duplicate subscribes on the same connection are no-ops.

Server → client

{ "type": "snapshot", "river_id": 12345, "data": { /* orderbook */ } }
{ "type": "update",   "river_id": 12345, "data": { /* orderbook */ } }
{ "type": "pending",  "river_id": 12345, "message": "subscription initiated" }
{ "type": "error",    "code": "bad_json" | "bad_action" | "bad_river_id" | "forbidden", "message": "..." }
{ "type": "reconnect" }

snapshot is sent once on successful subscribe when the orderbook is already cached. Subsequent changes are delivered as update frames with an identical payload shape.
pending is sent when the orderbook isn’t in cache yet. A snapshot arrives shortly, followed by updates.
reconnect is sent during graceful pod shutdown. Reconnect with a small jitter.

Keepalive

Liveness is handled at the WebSocket protocol layer (RFC 6455 PING/PONG control frames). Standard clients (Python websockets, browser WebSocket) reply to server PINGs automatically — no application-level heartbeat is needed.

Orderbook payload

{
  "river_id": 12345,
  "bids": [{ "price": 0.42, "qty": 1500 }, ...],
  "asks": [{ "price": 0.43, "qty": 2200 }, ...],
  "best_bid_price": 0.42,
  "best_ask_price": 0.43,
  "exchange_timestamp": "2026-04-19T15:22:01.123456+00:00",
  "is_valid": true
}

is_valid=false indicates a transient crossed-book state at the exchange. The snapshot that follows will have fresh values.

Rate limits and pacing

Orderbook updates are not rate-capped — every upstream change is forwarded as it happens. If your client falls behind, pending updates are coalesced per market (only the latest state is kept), so you never see stale data. A client that cannot drain fast enough is disconnected with code 1011; reconnect and resubscribe to get a fresh snapshot.

Minimal client

Using the SDK (handles signing automatically):

import asyncio
from rivermarkets import AsyncRiverMarkets

async def run(river_ids: list[int]):
    client = AsyncRiverMarkets(key_id="<uuid>", private_key="<base64-priv>")
    async with client.realtime.orderbooks(river_ids) as stream:
        async for msg in stream:
            if msg.type in ("snapshot", "update"):
                print(msg.river_id, msg.data["best_bid_price"], msg.data["best_ask_price"])

asyncio.run(run([12345]))

msg.type and top-level frame fields (msg.river_id) are attributes; msg.data is a plain dict — index it. best_bid_price / best_ask_price are null on an empty side of the book.

Changing subscriptions mid-stream

The object returned by client.realtime.orderbooks(...) exposes subscribe / unsubscribe. Both accept one or many river_ids and can be called at any time — typically from a separate task while the async for loop drains messages. The SDK tracks the active set, so after a transparent reconnect the current set (including mid-stream changes) is re-subscribed automatically.

async with client.realtime.orderbooks([12345]) as stream:
    await stream.subscribe([67890, 11111])   # add markets — each gets a fresh snapshot
    await stream.unsubscribe([12345])        # stop receiving a market
    async for msg in stream:
        ...

Or signing the handshake manually:

import asyncio, base64, json, time
from urllib.parse import urlencode
import websockets
from nacl.signing import SigningKey

KEY_ID = "<uuid>"
signing_key = SigningKey(base64.b64decode("<base64-priv>"))


def sign_ws(path: str) -> str:
    ts = str(int(time.time()))
    canonical = "\n".join(["WS", path, "", ts]).encode()
    sig = base64.b64encode(signing_key.sign(canonical).signature).decode()
    return f"wss://api.rivermarkets.com{path}?{urlencode({'key_id': KEY_ID, 'ts': ts, 'sig': sig})}"


async def run(river_ids: list[int]):
    async with websockets.connect(sign_ws("/v1/ws/orderbooks")) as ws:
        await ws.send(json.dumps({"action": "subscribe", "river_ids": river_ids}))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("type") in ("snapshot", "update"):
                print(msg["river_id"], msg["data"]["best_bid_price"], msg["data"]["best_ask_price"])

asyncio.run(run([12345]))

Close codes

Code	Meaning
`1000`	Normal closure
`1011`	Server-side overflow (client couldn’t keep up with the send rate)
`4401`	Missing or invalid authentication
`4503`	Server draining for deploy — reconnect with jitter

Overview

Market Data

Account

Endpoint

Authentication

Protocol

Client → server

Server → client

Keepalive

Orderbook payload

Rate limits and pacing

Minimal client

Changing subscriptions mid-stream

Close codes

​Endpoint

​Authentication

​Protocol

​Client → server

​Server → client

​Keepalive

​Orderbook payload

​Rate limits and pacing

​Minimal client

​Changing subscriptions mid-stream

​Close codes

Endpoint

Authentication

Protocol

Client → server

Server → client

Keepalive

Orderbook payload

Rate limits and pacing

Minimal client

Changing subscriptions mid-stream

Close codes