Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rivermarkets.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

wss://api.rivermarkets.com/v1/ws/tradeprints
A single WebSocket connection can subscribe to any number of markets. The server pushes one frame per trade print, in real time. There is no snapshot on subscribe — see Backfill.

​
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/tradeprints?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.

​
Backfill

The WebSocket stream is live-only — it does not emit historical trades on subscribe. To populate a recent trades view on page load, call: 
GET https://api.rivermarkets.com/v1/tradeprints?river_ids=12345&river_ids=67890&limit=50
This REST endpoint accepts one or more river_ids (repeat the parameter), queries each source exchange sequentially, and returns the most recent trades for every market in descending time order. The response is { "results": [...] } with one block per requested river_id in input order. Per-market failures show up as not_found rows with a message. Fire it in parallel with the WebSocket subscribe action and deduplicate overlap by exchange_trade_id.

​
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": "trade", "river_id": 12345, "data": { /* tradeprint */ } }
{ "type": "error", "code": "bad_json" | "bad_action" | "bad_river_id" | "forbidden", "message": "..." }
{ "type": "reconnect" }
{ "type": "connected" }
  • trade is sent once per print. Append-only — frames are never coalesced.
  • 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.

​
Tradeprint payload

{
  "exchange_timestamp": "2026-04-19T15:22:01.123+00:00",
  "price": 0.42,
  "qty": 150,
  "aggressor_buy_flag": true,
  "exchange_trade_id": "kalshi-abc-123"
}
FieldTypeNotes
exchange_timestampstring (ISO-8601) | nullExchange-reported trade time.
pricenumberTrade price, normalised to 0–1 in YES terms.
qtynumberTrade size in contracts.
aggressor_buy_flagboolean | nulltrue if the taker bought (hit an ask). false if the taker sold. null if unknown.
exchange_trade_idstring | nullExchange-assigned trade id. Use it to deduplicate REST backfill against the live WS stream.

​
Rate limits and pacing

Trades are append-only events — they are not rate-capped or coalesced. Every print on the upstream exchange is forwarded. If a slow client cannot drain fast enough, the server closes the connection with code 1011; reconnect and re-backfill.

​
Minimal client

Using the SDK (handles REST + WS signing automatically): 
import asyncio
from rivermarkets import AsyncRiverMarkets

async def run(river_id: int):
    client = AsyncRiverMarkets(key_id="<uuid>", private_key="<base64-priv>")

    # 1. Backfill recent trades.
    backfill = await client.tradeprints.list_tradeprints(river_ids=[river_id], limit=50)
    trades = backfill.results[0].trades
    seen = {t.exchange_trade_id for t in trades if t.exchange_trade_id}
    for t in trades:
        print("backfill", t.exchange_timestamp, t.price, t.qty)

    # 2. Subscribe to the live stream.
    async with client.ws.tradeprints() as stream:
        await stream.subscribe([river_id])
        async for msg in stream:
            if msg.type != "trade":
                continue
            tid = msg.data.exchange_trade_id
            if tid and tid in seen:
                continue
            if tid:
                seen.add(tid)
            print("live", msg.data.exchange_timestamp, msg.data.price, msg.data.qty)

asyncio.run(run(12345))

​
Close codes

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