Tradeprints

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, 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.

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"
}

Field	Type	Notes
`exchange_timestamp`	string (ISO-8601) \| null	Exchange-reported trade time.
`price`	number	Trade price, normalised to `0–1` in YES terms.
`qty`	number	Trade size in contracts.
`aggressor_buy_flag`	boolean \| null	`true` if the taker bought (hit an ask). `false` if the taker sold. `null` if unknown.
`exchange_trade_id`	string \| null	Exchange-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.realtime.tradeprints([river_id]) as stream:
        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))

msg.type and top-level frame fields (msg.river_id) are attributes; msg.data is a plain dict — index it.

Changing subscriptions mid-stream

The object returned by client.realtime.tradeprints(...) 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.tradeprints([12345]) as stream:
    await stream.subscribe([67890, 11111])   # add markets
    await stream.unsubscribe([12345])        # stop receiving a market
    async for msg in stream:
        ...

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

Backfill

Protocol

Client → server

Server → client

Keepalive

Tradeprint payload

Rate limits and pacing

Minimal client

Changing subscriptions mid-stream

Close codes

​Endpoint

​Authentication

​Backfill

​Protocol

​Client → server

​Server → client

​Keepalive

​Tradeprint payload

​Rate limits and pacing

​Minimal client

​Changing subscriptions mid-stream

​Close codes

Endpoint

Authentication

Backfill

Protocol

Client → server

Server → client

Keepalive

Tradeprint payload

Rate limits and pacing

Minimal client

Changing subscriptions mid-stream

Close codes