WebSocket overview

Two gateways (/ws/market and /ws/user), X-Api-Key at handshake, Kalshi-style command envelope, channels keyed by tokenId / conditionId.

PredictStreet exposes WebSocket streaming through two separate gateways that share one client protocol. Pick the gateway by what data you want; never mix subscriptions across the two on one socket.

Both gateways authenticate with X-Api-Key — the same key you use on HTTP, same scope rules.

Gateway	Path	Auth	What lives here
market	/ws/market	X-Api-Key	public trades, orderbooks, market lifecycle, platform status
user	/ws/user	X-Api-Key (portfolio:read scope)	own orders / fills / account-control events

The protocol is Kalshi-style (envelope with id / cmd / params) and Polymarket-style identifier lists (channel + ids[]).

Connect

Same handshake contract for both gateways:

wss://ws-gateway.adipredictstreet.com/ws/market
wss://ws-gateway.adipredictstreet.com/ws/user

Pick one of:

• X-Api-Key: ps_live_<keyId>_<secret> header on the upgrade request
• ?key=<token> query parameter — for browser clients that can’t set custom headers on the WebSocket upgrade

The server pushes one greeting after the upgrade:

{
  "type": "connected",
  "data": {
    "gateway":       "user",
    "walletAddress": "0x1111111111111111111111111111111111111111",
    "authMethod":    "api_key"
  }
}

On /ws/market the greeting is just { "gateway": "market", "authMethod": "api_key", "protocolVersion": 2 } — no wallet context, since market data isn’t per-user.

Auth is validated at handshake only. Rotating a key does not invalidate an open socket; close and reopen to switch identity. A bad key closes with 4401 <reason> (e.g. 4401 api_key_revoked). Revoking a key closes every live socket bound to that keyId immediately via apikey:invalidate Redis pub/sub.

Command envelope

Every client-to-server message uses the same shape:

{ "id": 1, "cmd": "subscribe", "params": { /* ... */ } }

• id — client-side correlation id; echoed in the server’s response
• cmd — subscribe / update_subscription / unsubscribe / list_subscriptions / ping
• params — command-specific payload

Every accepted subscription gets a connection-local sid (numeric). Use sid for subsequent updates / unsubscribes / event routing on the client side. sids are not stable across reconnects.

Channel catalog

Public, on /ws/market:

Channel	Identifier model	Required scope	Purpose
token_trade_matches	ids = [tokenId, ...]	—	low-latency tape from the matcher (off-chain match)
token_trade_settlements	ids = [tokenId, ...]	—	chain-confirmed settlements (OrderFilled indexed)
token_book	ids = [tokenId, ...]	—	public orderbook snapshots + updates
token_ohlc	ids = [tokenId, ...]	—	rolling 5-second OHLC candles
condition_lifecycle	ids = [conditionId, ...]	—	market lifecycle, pause/unpause, oracle, payout
system	ids = ["platform_status"]	—	platform-wide freeze / maintenance banner

Private, on /ws/user:

Channel	Identifier model	Required scope	Purpose
user_orders	no ids (scoped to the key’s wallet)	portfolio:read	own order_placed / order_cancelled
user_fills	no ids (scoped to the key’s wallet)	portfolio:read	own user_fill (chain-confirmed fills)
vault_positions	ids = [vaultAddress, ...]	portfolio:read	per-vault balance changes / split / merge / redeem

Detailed payloads + examples in Subscriptions and Messages.

Where do tokenId and conditionId come from?

Market data is keyed by on-chain native ids, not by app symbol. Pull them from REST first:

• GET /api/markets/{symbol} → conditionId / questionId / yesTokenId / noTokenId (binary)
• For neg-risk multi-outcome markets, each question has its own conditionId and yes/no token ids — resolve them through the on-chain NegRiskAdapter before subscribing

Then open /ws/market and subscribe by those native ids:

{
  "id": 1,
  "cmd": "subscribe",
  "params": {
    "subscriptions": [
      { "channel": "token_trade_matches",     "ids": ["12345..."] },
      { "channel": "token_trade_settlements", "ids": ["12345..."] },
      { "channel": "token_book",              "ids": ["12345..."] },
      { "channel": "condition_lifecycle",     "ids": ["0xabc..."] }
    ]
  }
}

Don’t subscribe by app symbol — symbols are app metadata, not the canonical on-chain identity.

What clients should NOT do

• No symbol-based subscriptions. Use tokenId / conditionId.
• No invented room strings like vault:0xabc:erc1155. Use channel + ids only.
• No mixing of /ws/user and /ws/market on one socket. The gateway rejects cross-gateway channels with forbidden — open one socket per gateway.
• No assumptions about sid stability across reconnects. After any close, re-subscribe from scratch.

Next

Subscriptions

Per-channel subscribe / update / unsubscribe payloads.

Message shapes

Outbound event envelope and full event catalog by channel.

Reconnect

Heartbeat, sid rebuild, snapshot resync.

API keys

Scope catalog, rotation, revoke.