Orderbooks

Endpoint

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

A single WebSocket connection can subscribe to up to 1,000 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": "subscribe",   "river_ids": [12345], "max_freq": 5 }
{ "action": "unsubscribe", "river_ids": [12345] }

subscribe / unsubscribe accept one or many river_ids. Duplicate subscribes on the same connection are no-ops.
max_freq (optional, Hz) caps update frames per market for the river_ids in that frame. While capped, updates are coalesced to the latest book state, so you always converge on the current orderbook; the first update after a quiet period is delivered immediately. Each subscribe frame declares the desired cap for its river_ids: re-subscribing an already-subscribed river_id with a different max_freq updates the cap, and re-subscribing without one clears it. Omitted means uncapped. A non-positive or non-numeric value gets an error frame with code bad_max_freq.

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" | "bad_max_freq" | "forbidden" | "subscription_limit", "message": "..." }

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.
error with code subscription_limit is sent when a subscribe would take the connection past 1,000 markets. The whole frame is rejected and none of its river_ids are added — unsubscribe from markets you no longer need, or spread subscriptions across connections.

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

By default orderbook updates are not rate-capped — every upstream change is forwarded as it happens. Pass max_freq on subscribe to cap update frames per market; this reduces bandwidth and client-side processing without risking stale data, because capped updates are coalesced to the latest book state. If your client falls behind, pending updates are likewise coalesced per market (only the latest state is kept). 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() * 1000))
    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
`1001`	Server shutting down for deploy — reconnect with jitter
`1011`	Server-side overflow (client couldn’t keep up with the send rate)
`4401`	Missing or invalid authentication
`4503`	Authentication backend temporarily unavailable — retry 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