WebSocket overview

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, candles, live chart prices, market lifecycle, crypto prices, platform-wide firehoses and trade feed
user	`/ws/user`	`X-Api-Key` (`portfolio:read` scope)	own orders / fills / account-control events, deposit-limit and bond-payout signals, in-app notifications

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.dev.predictstreet.sde.adifoundation.ai/ws/market
wss://ws-gateway.dev.predictstreet.sde.adifoundation.ai/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

On /ws/user each socket is bound to one wallet, and its private channels serve only that wallet and its vault. A single_wallet key is bound to the partner’s associatedWallet. A multi_wallet key has no wallet of its own, so it must also name one on the upgrade with X-User-Wallet: 0x… (or ?wallet=0x… / ?user_wallet=0x…). Without it the socket closes with 4401 api_key_user_wallet_required; a malformed address closes it with 4401 api_key_user_wallet_invalid. (If a multi_wallet partner also has an associated wallet configured, the socket binds to that wallet and ignores X-User-Wallet.) Open one /ws/user socket per wallet. See WSS /ws/user. The server pushes one greeting after the upgrade:

{
  "type": "connected",
  "data": {
    "gateway":         "user",
    "walletAddress":   "0x1111111111111111111111111111111111111111",
    "vaultAddress":    "0x2222222222222222222222222222222222222222",
    "authMethod":      "api_key",
    "protocolVersion": 2
  },
  "serverTs": 1776949200000
}

vaultAddress is null when the wallet has no vault yet. An open socket keeps the value it got at the handshake, so reconnect after the vault is deployed before you subscribe to vault_positions / vault_activity. On /ws/market the greeting is { "gateway": "market", "authMethod": "api_key", "protocolVersion": 2, "partnerId": "…" } — no wallet context, since market data isn’t per-user.

Auth is checked at handshake. Issuing a new key doesn’t affect sockets opened with the old one; close and reopen to switch keys. A bad key closes with 4401 <reason> (e.g. 4401 api_key_expired). Open sockets on a key are closed immediately with 4401 api_key_revoked when the key is revoked, its scopes change, the partner is suspended, or the partner’s associated wallet, kind or per-wallet KYC setting changes. Reconnect once to learn whether the key still works.

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 / get_book_snapshot / unsubscribe / list_subscriptions / ping; anything else gets an unknown_cmd error
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
`market_price_tick`	`ids = ["<symbol>:<outcomeIndex>", ...]`	—	live edge of the probability chart — an outcome’s mark, at most about once a second
`all_trade_matches`	no `ids`	—	`token_trade_matches` frames for every token on the platform
`all_trade_settlements`	no `ids`	—	`token_trade_settlements` frames for every token
`all_books`	no `ids`	—	`token_book` updates and deltas for every token (high volume, no initial snapshot)
`global_activity`	no `ids`	—	one frame per trade platform-wide, in the taker’s view, with market titles and username
`condition_lifecycle`	`ids = [conditionId, ...]`	—	on-chain trading pause / unpause of a condition (status and resolution are on `market_lifecycle`)
`market_lifecycle`	`ids = [marketSymbol, ...]`	—	per-market status / dispute / resolution, and a crypto window’s open and close prices
`crypto_price_tick`	`ids = [instrumentId, ...]`	—	live underlying-asset price for crypto markets (`BTC-USD`, …)
`system`	`ids = ["platform_status"]`	—	accepted, but no frames are published on it; poll `GET /api/platform/status` for the platform freeze state

Private, on /ws/user:

Channel	Identifier model	Required scope	Purpose
`user_orders`	no `ids` (scoped to the socket’s wallet)	`portfolio:read`	own `order_placed` / `order_cancelled` / `order_rejected` / `order_expired` / `trade_failed`
`user_fills`	no `ids` (scoped to the socket’s wallet)	`portfolio:read`	own `user_fill` at match time, before on-chain settlement
`vault_positions`	`ids = [vaultAddress]` (your own vault)	`portfolio:read`	your vault’s balance changes / split / merge / redeem
`vault_activity`	`ids = [vaultAddress]` (your own vault)	`portfolio:read`	on-chain vault events, including `trade_fill` when a fill settles (`txHash`, `fee`), `deposit_confirmed` and `withdrawal_confirmed`
`user_activity`	no `ids` (scoped to the socket’s wallet)	`portfolio:read`	`withdrawal_<state>` on each status change of your withdrawals, `vault_created`, `user_paused` / `user_unpaused`
`me_limits_invalidated`	`ids = [walletAddress]` (your own wallet; none on a JWT session)	`portfolio:read`	your on-chain deposit tier, caps or restrictions changed — re-read `GET /api/me/deposit-limits`
`bond_payout_credited`	`ids = [walletAddress]` (your own wallet; none on a JWT session)	`portfolio:read`	a refunded challenge bond (plus any reward) became claimable
`dispute_intent`	`ids = [walletAddress]` (your own wallet; none on a JWT session)	`portfolio:read`	status of disputes filed from the web app; silent for challenges sent on-chain directly
`notifications`	no `ids` (scoped to the socket’s wallet)	`portfolio:read`	the web app’s in-app notification feed, live; best-effort, display text

Detailed payloads + examples in Subscriptions and Messages. The two crypto feeds have their own page: Crypto price feeds.

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, and each outcome’s outcomes[].tokenId
A neg-risk (multi-outcome) event is listed as one market per outcome (negRiskEligible: true). Each has its own symbol, conditionId, yesTokenId and noTokenId in that same response, so no on-chain lookup is needed

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

Token- and condition-scoped channels take these on-chain ids, not app symbols. market_lifecycle and market_price_tick are keyed by market symbol (market_price_tick as <symbol>:<outcomeIndex>), crypto_price_tick by instrument id, and the all_* channels and global_activity take no ids at all.

What clients should NOT do

No symbol-based subscriptions on token or condition channels. Use tokenId / conditionId; only market_lifecycle and market_price_tick take a market symbol.
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.

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.

Getting Started

Authentication

Vaults

Deposits

Trading

Events & Tags

Markets

Portfolio

Withdrawals

WebSocket

Settlement & Oracle

On-chain Contracts

Partners

Errors

Connect

Command envelope

Channel catalog

Where do `tokenId` and `conditionId` come from?

What clients should NOT do

Next

Subscriptions

Message shapes

Reconnect

API keys

​Connect

​Command envelope

​Channel catalog

​Where do tokenId and conditionId come from?

​What clients should NOT do

​Next

Subscriptions

Message shapes

Reconnect

API keys

Connect

Command envelope

Channel catalog

Where do `tokenId` and `conditionId` come from?

What clients should NOT do

Next