Orderbooks - River Markets

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 you can authenticate with a Supabase JWT instead: ?access_token=<jwt>. 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.ws.orderbooks() as stream:
        await stream.subscribe(river_ids)
        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]))

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

​Endpoint

​Authentication

​Protocol

​Client → server

​Server → client

​Keepalive

​Orderbook payload

​Rate limits and pacing

​Minimal client

​Close codes

Endpoint

Authentication

Protocol

Client → server

Server → client

Keepalive

Orderbook payload

Rate limits and pacing

Minimal client

Close codes