SPB Git

Repository Public

V11-QUOTE-ENGINE.md 35.4 KB 454 lines markdown

1# V11 — Real-time quotation engine23Live public market data — quotes, order books, trades, candles, venue status — pushed over a websocket to the wallet's web app4and to API clients. Written 2026-11-15, branch `v11-quotes`. Work note with the measured runs: `docs/v11/work/quotes.md`.56**Read-only.** The engine subscribes to PUBLIC market-data feeds and fans them out. It holds no account, no key and no signer;7`services/api/src/quotes/` imports neither the signer client nor a venue's trading object. Nothing in it can place, sign or8cancel anything.910**No production change was made.** Everything below was built and run locally.1112Contents: 1 architecture · 2 upstream sources · 3 endpoints and authentication · 4 protocol · 5 limits · 6 backpressure ·137 web client · 8 SDKs · 9 failure modes · 10 metrics and logs · 11 deployment notes · 12 for the agents' stream engine · 13 limits of this version1415---1617## 1. Architecture1819```20 venues (public feeds)                      API process (services/api/src/quotes)                     clients21 ────────────────────                       ─────────────────────────────────────                    ───────22 Hyperliquid  wss ──┐   upstreams.ts        hub.ts                     engine.ts + outbox.ts23 edgeX        wss ──┤   one Upstream  ───▶  Feed (venue|kind|symbol) ─▶ Chan (type|id|param) ─▶ Conn ─▶ browser  GET /api/v1/stream24 dYdX         wss ──┤   per venue           reference-counted            reference-counted        │      (session cookie + Origin)25 GMX         REST ──┤   (reconnect,         merge, seq, checksum,        last value, snapshot     ├────▶ API key  GET /api/v1/trading/stream26 Coinbase     wss ──┤    heartbeat,         venue status                                          │      (Bearer header or ticket)27 CoinGecko   REST ──┘    resubscribe)                                                             └────▶ another module of the process: hub.subscribe()28```2930| File | Role |31|---|---|32| `protocol.ts` | The wire protocol as zod schemas (version 1). The web client and the SDK tests import its TYPES. |33| `shared.ts` | Code shared by value with the browser (no import): book checksum (CRC-32), delta apply / diff, decimal compare, channel key, backoff, close codes. |34| `hub.ts` | `QuoteHub`: channels and upstream feeds, both reference-counted; merge of quote parts; book snapshot / delta; venue status; bounds. |35| `upstreams.ts` | One `Upstream` per venue: Hyperliquid, edgeX / dYdX / GMX through the derivatives registry, spot (Coinbase + the price module). |36| `ws-client.ts` | A reconnecting websocket CLIENT (backoff + jitter, liveness watchdog) — used for Coinbase. |37| `outbox.ts` | Per-connection backpressure: conflation, dropped-trade counter, high-water disconnect. |38| `engine.ts` | `QuoteEngine`: the websocket server (`@fastify/websocket` 11.3.7 on Fastify 5.12.8), authentication gate, tickets, limits, liveness, credential re-checks, stats. |39| `index.ts` | `installQuotes` (wiring used by `server.ts`), `quoteHub()`, `quoteSummary()`. |4041**Reference counting, two levels.** A *channel* (`quote|hyperliquid:BTC|`, `book|hyperliquid:BTC|10`) is opened by its first42listener and shared by the next ones. A channel needs one or more upstream *feeds* (`hyperliquid|ticker|BTC`,43`hyperliquid|bbo|BTC`); a feed is opened by the first channel that needs it (a book at depth 5 and a book at depth 20 share44ONE upstream book feed) and closed with the last. A channel without listener is kept `idleGraceMs` (10 s) before its feeds are45released: changing page does not cost a venue subscription. Nothing is connected upstream until something is subscribed.4647**Never a fabricated price.** A quote is the newest fields its source sent, merged. A field the source does not publish is48`null`. `mid` is the mid of the two sides when the source gives both, else the venue's own mid, else `null` — never one side of49now with the other side of earlier, never a figure from another venue. A malformed upstream frame is dropped and counted; it50never produces half a quote. When a venue has no data there is no message — there is a `status`.5152**Isolation.** Every upstream call and every listener call is wrapped; each venue has its own connection, its own status, its53own counters and its own subscription budget. A venue that throws, hangs, floods or dies costs the others nothing54(`services/api/test/quotes-hub.test.ts`, and observed in a browser: §"browser check" of the work note).5556**Bounded memory.** 3 000 channels in the hub, 800 upstream feeds per venue, 800 new upstream subscriptions per venue and per57minute, one quote + one book + 50 trades + one candle per channel; per connection: 300 subscriptions and a queue of at most one58entry per subscription (§6).5960## 2. Upstream sources6162Verified by a live connection on 2026-11-15 (probe frames recorded in `services/api/test/fixtures/quotes/` and63`packages/derivatives/test/fixtures/`).6465| Venue | Transport | What is used | Official documentation |66|---|---|---|---|67| **Hyperliquid** (main dex **and** builder-deployed dexes: `xyz:ANT`, `io:ANTH`…) | **websocket** `wss://api.hyperliquid.xyz/ws`, ONE connection owned by the hub | `activeAssetCtx` (mark, oracle, funding, open interest, 24 h), `bbo` (best bid / offer, venue-stamped), `l2Book`, `trades`, `candle` | https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket (+ `/subscriptions`, `/timeouts-and-heartbeats`); limits: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/rate-limits-and-user-limits |68| **edgeX** | **websocket** `wss://edgex-quote-prod-v2.edgex.exchange/api/v1/public/ws` through the adapter (one connection for the service) | `ticker.{contractId}`, `depth.{contractId}.15`, `trades.{contractId}`; candles: REST polling (10 s) | https://edgex-1.gitbook.io/edgeX-documentation/api-v2 (see `docs/v11/research/edgex-api.md` §1.8) |69| **dYdX v4** | **websocket** `wss://indexer.dydx.trade/v4/ws` through the adapter (the documented indexer websocket; verified live) | `v4_markets` (oracle price, funding estimate, open interest), `v4_orderbook`, `v4_trades`; candles: REST polling (10 s) | https://docs.dydx.xyz/indexer-client/websockets |70| **GMX v2** | **REST polling** (every 3 s, over the data service's 3 s cache: a fresh read about every 6 s) of the oracle tickers through the derivatives data service (per-venue budget, last-good cache) | quote only — GMX has no order book and no public trade feed; candles: REST polling | https://docs.gmx.io/docs/api/overview/ — no public websocket / SSE is documented |71| **spot** — symbols Coinbase lists against USD | **websocket** `wss://ws-feed.exchange.coinbase.com` (public market-data feed, no authentication) | channel `ticker` (last trade, best bid / offer with sizes, 24 h open, venue-stamped) + `heartbeat` | https://docs.cdp.coinbase.com/exchange/websocket-feed/overview (« available without authentication »; a subscribe is required within 5 s) |72| **spot** — any other wallet symbol | **polling** (60 s) of the wallet's existing price module (CoinGecko, `server.ts` `markets()`, cached 4 min) | last price with the source's own date (`venueTs`) | https://docs.coingecko.com/reference/coins-markets |7374What each upstream client does (reconnect with exponential backoff + jitter, heartbeat per the venue's protocol, resubscription75after reconnect, gap events):7677- **Hyperliquid** — `createHlStream` (`packages/derivatives/src/venues/hyperliquid/stream.ts`, extended in this work with `bbo`78  and `candle`): client `{"method":"ping"}` every 15 s (the venue drops a connection it has sent nothing to for 60 s), `stale`79  after 25 s of silence, re-opened 10 s later, backoff 1 s … 30 s, a `gap` event after every reconnection. The venue DROPS the80  whole connection on a subscription to an unknown coin: the hub validates the coin against the venue's own listing before it81  subscribes (main dex: `meta`; builder dexes: `perpDexs` asset table, delisted coins refused). Venue limits per address:82  10 websocket connections, 1 000 subscriptions, 30 new connections a minute, 2 000 messages sent a minute — hence the hub's83  budgets (800 feeds, 800 new feeds a minute).84- **edgeX** — `EdgeXStream`: answers the server's ping (every 10 s) with the same time; depth is a snapshot + increments whose85  `startVersion` must equal the previous `endVersion`, anything else is a gap and the channel is subscribed again.86- **dYdX** — `DydxStream`: client ping, per-connection `message_id` tracking (an id still missing 5 s after a later one = gap →87  reconnect), snapshots on resubscription. A crossed book published by the indexer is skipped, never repaired.88- **Coinbase** — `createReconnectingWs` (`ws-client.ts`): the `heartbeat` channel (one frame per second and per product) proves89  liveness; `stale` after 20 s of silence, re-opened 10 s later; resubscription of every product on reconnect.90- **Kraken** (`wss://ws.kraken.com/v2`, channel `ticker`) was verified live too and NOT added: one streamed source per symbol91  keeps « which exchange is this price from » unambiguous, and the wallet's bars already name Coinbase first.9293**Ids** are those of the markets hub: `venue:symbol` (`hyperliquid:BTC`, `hyperliquid:xyz:ANT`, `edgex:BTCUSDC`,94`dydx:BTC-USD`, `gmx:BTC/USD [BTC-USDC]`) and `spot:<symbol>`.9596**Venue timestamps.** `venueTs` is the venue's own stamp when it gives one: Hyperliquid `bbo.time` and `l2Book.time`, trade97times on every venue, Coinbase `ticker.time`, CoinGecko `last_updated`. Hyperliquid's asset context, edgeX's and dYdX's tickers98and books and GMX's tickers carry none: `venueTs` is `null` and `recvTs` (receipt by this server) is the only date.99100### Spot symbols without a Coinbase stream: the metered second source (2026-11-17)101102With `APIBRICKS_API_KEY` set, a spot symbol Coinbase does not list **and** that maps onto API Bricks with certainty is103polled from that provider instead of the price list: `source: "apibricks-rest"`, `transport: "poll"`, one batched REST104call every 5 minutes while a channel on such a symbol is open, stale after 15 minutes, `last` only (no bid / ask). It is105paid from a daily credit budget (30 polls a day by default). The path is chosen when the channel opens — no room in the106budget means the price list, as before. If the budget runs out while a channel is open, the source is **`down` with the107reason `quota`**: an error on the channel, `hub.venues[spot].upstream.second` and `metered.apibricks` in108`GET /api/v1/stream/stats` (budget used / ceiling / remaining / `exhausted`), and the `spot` venue status when that109source alone feeds it. Its failures touch neither the Coinbase stream nor the polled symbols. Without the key nothing of110this exists. Details: `docs/V11-MARKET-DATA-SOURCES.md` §2.3 (c).111112## 3. Endpoints and authentication113114| Route | Who | Credential |115|---|---|---|116| `GET /api/v1/stream` (websocket) | the wallet's web app | owner session cookie **and** `Origin` equal to `SPW_ORIGIN` |117| `GET /api/v1/trading/stream` (websocket) | API clients | `Authorization: Bearer spw_live_…` with scope `markets:read`, **or** `?ticket=…`; the owner's cookie is accepted too, under the same Origin rule |118| `POST /api/v1/trading/stream/ticket` | a key (`markets:read`) or the owner | answers `{ ticket, expiresAt, ttlMs, url, protocol }` |119| `GET /api/v1/stream/stats` | owner | counters (§10) |120121Authentication happens **before the upgrade**, in the hooks every request of the service goes through: the single `onRequest`122hook of `server.ts` (session cookie → owner; `apiKeyGate` → key principal, IP allow-list, per-key rate limit) and the trading123API's `scopeGuard` (the route declares `markets:read`). A refused request gets a plain HTTP answer — `401 unauthenticated`,124`403 origin_refused | insufficient_scope | key_path_forbidden | mixed_credentials`, `429 too_many_connections` — and the socket is125never upgraded.126127**The Origin rule.** A websocket handshake is a `GET` that carries the session cookie from ANY page: CORS does not apply to128websockets, and the custom-header CSRF defence of the REST routes cannot be used (a browser cannot set a header on a129websocket). The `Origin` header — set by the browser, not by the page — is therefore the CSRF defence: a cookie-authenticated130upgrade whose `Origin` is not exactly `SPW_ORIGIN` (absent, `null`, another scheme, a look-alike host) is refused with 403.131The cookie is also `SameSite=Strict`. A key or a ticket is not an ambient credential: no Origin is required with them.132133**API keys.** Never in the query string: `?key=`, `?token=`… open nothing (401). A key's restrictions apply **per134subscription**: a channel on a venue or an instrument outside `restrictions.venues` / `restrictions.instruments` is answered135`error restricted` and opens nothing upstream; the rest of the key's subscriptions go through. `status` channels are open to136every key.137138**Tickets** (for clients that cannot set a header — browsers): 24 random bytes (`spw_tkt_…`), stored as a SHA-256, valid 30 s,139**single use** (removed when presented, whatever the outcome), bound to the principal that asked for it (a key's scopes and140restrictions, or the owner's session), never combined with a cookie or a bearer header (403 `mixed_credentials`), accepted on141`/api/v1/trading/stream` only. The ticket is the only thing that ever appears in a URL, and it is worthless after one use.142143**Sessions end, keys get revoked.** Each socket re-checks its credential every 30 s (`auth.ts` `sessionAlive` — read-only, it does144not keep an idle session alive — and the key's status) and right after any successful `POST` to `/api/v1/auth/*`,145`/api/v1/developer/keys*`, `/api/v1/security/*`: a logout, an expired session, a revoked / rotated / expired key closes its146sockets with code **4001**.147148**CSP.** `connect-src 'self' wss://<origin host>`. CSP3 lets `'self'` match the `ws` / `wss` scheme of the page's own origin and149current Chrome, Firefox and Safari do; Safari up to 15.3 did not ([WebKit bug 201591](https://bugs.webkit.org/show_bug.cgi?id=201591),150closed as a duplicate of 235873), so the same-origin websocket origin is named explicitly — one origin, nothing wider. Checked151in Chromium (no CSP violation, `tests/e2e/v11-quotes-live.mts`); Safari / iOS were not run here.152153## 4. Protocol (version 1)154155JSON text frames. Every server frame carries `"v": 1` and a `type`. Prices, sizes and rates are canonical decimal **strings**156(`/^-?(0|[1-9]\d*)(\.\d+)?$/`), never floats. Times are milliseconds since the epoch.157158### Client → server159160```json161{ "v": 1, "op": "subscribe",   "reqId": 7, "channels": [ { "type": "quote", "id": "hyperliquid:BTC" },162                                                          { "type": "book",  "id": "hyperliquid:BTC", "depth": 10 },163                                                          { "type": "trades", "id": "dydx:BTC-USD" },164                                                          { "type": "candle", "id": "hyperliquid:BTC", "interval": "1m" },165                                                          { "type": "status", "id": "*" } ] }166{ "v": 1, "op": "unsubscribe", "channels": [ { "type": "quote", "id": "hyperliquid:BTC" } ] }167{ "v": 1, "op": "ping", "t": 42 }168```169170`type`: `quote | book | trades | candle | status`. `depth`: 5, 10 or 20 (default 20). `interval`: `1m 5m 15m 1h 4h 1d` (default171`1m`). `status` id: `*` or a venue id. `v` may be omitted; any other value is refused. Unknown fields are refused. At most 200172channels per frame. Subscribing again to a channel one already has means « send me the snapshot again ».173174### Server → client175176`hello` — first frame:177178```json179{ "v": 1, "type": "hello", "connId": "65e1db2a-87d6", "heartbeatMs": 15000, "serverTs": 1794798600000,180  "limits": { "maxSubscriptions": 300, "maxFrameBytes": 16384, "maxMessagesPerSec": 20, "idleTimeoutMs": 120000 } }181```182183`subscribed` — one per channel, with the **last known value at once** and its age (`null` when nothing was received yet):184185```json186{ "v": 1, "type": "subscribed", "reqId": 7, "channel": { "type": "quote", "id": "hyperliquid:BTC" }, "key": "quote|hyperliquid:BTC|",187  "staleAfterMs": 15000, "source": "hyperliquid-ws", "snapshotAgeMs": 84, "snapshot": { "v": 1, "type": "quote", "…": "…" } }188```189190`quote`:191192```json193{ "v": 1, "type": "quote", "id": "hyperliquid:BTC", "bid": "65085", "bidSize": "11.88311", "ask": "65086", "askSize": "0.85252",194  "mid": "65085.5", "mark": "65087", "index": "65115", "last": null, "funding": "0.0000125", "openInterest": "36159.52766",195  "change24h": "0.003067", "volume24h": "3319784424.8816184998", "venueTs": 1794797790906, "recvTs": 1794797791203,196  "seq": 412, "source": "hyperliquid-ws", "stale": false }197```198199`seq` increases by one for every quote the hub produced on that channel (a jump on the wire = conflated updates, never lost200state: a quote is a full state). `funding` is per funding interval of the venue, as the venue publishes it.201202`book` — a snapshot, then deltas:203204```json205{ "v": 1, "type": "book", "id": "hyperliquid:BTC", "depth": 10, "kind": "snapshot", "bids": [["65085","1.5"],["65084","3"]], "asks": [["65086","2"]],206  "seq": 1, "prevSeq": null, "checksum": 2874311908, "venueTs": 1794797790906, "recvTs": 1794797791203, "source": "hyperliquid-ws", "stale": false }207{ "v": 1, "type": "book", "id": "hyperliquid:BTC", "depth": 10, "kind": "delta", "bids": [["65085","0"],["65083","4"]], "asks": [],208  "seq": 2, "prevSeq": 1, "checksum": 1146302475, "venueTs": null, "recvTs": 1794797791703, "source": "hyperliquid-ws", "stale": false }209```210211A delta lists changed prices only; size `"0"` removes the price. **Contiguous sequence**: a delta applies only when `prevSeq` is212the `seq` of the last message applied. **Checksum**: CRC-32 (IEEE) of `p:s|p:s…;p:s|…` over the best 10 levels of each side, bids213first, decimal strings exactly as sent, computed on the server's book AFTER the message. On a hole or a mismatch the client214subscribes to the channel again and waits for the snapshot (`OrderBook` in both SDKs and `quotes.ts` do exactly this). After any215upstream gap or reconnection the server itself restarts the channel from a snapshot.216217`trade` — a batch, oldest first; the first batch after a subscription (or a gap) is the venue's recent history, flagged:218219```json220{ "v": 1, "type": "trade", "id": "hyperliquid:BTC", "trades": [ { "id": "437504529308123", "price": "65085", "size": "0.1", "side": "sell", "ts": 1794797517779 } ],221  "seq": 9, "recvTs": 1794797517902, "source": "hyperliquid-ws", "snapshot": true }222```223224`candle` — the bar in progress (same `ts`, new figures) or a new bar:225226```json227{ "v": 1, "type": "candle", "id": "hyperliquid:BTC", "interval": "1m", "ts": 1794798660000, "open": "65032", "high": "65066", "low": "65012", "close": "65066",228  "volume": "3.5836", "seq": 14, "recvTs": 1794798671010, "source": "hyperliquid-ws" }229```230231`status` — per venue: `connected | reconnecting | stale | down | idle` (`idle`: nothing subscribed, no connection):232233```json234{ "v": 1, "type": "status", "venue": "hyperliquid", "status": "reconnecting", "since": 1794798700000, "ageMs": 1200, "transport": "stream",235  "source": "hyperliquid-ws", "detail": null, "ts": 1794798701200 }236```237238Sent on every change, every 5 s for a venue that is not connected (its `ageMs` grows) and every 15 s otherwise. A venue that239stays `reconnecting` or `stale` for 30 s is reported `down` and stays so until it is connected again.240241Others:242243```json244{ "v": 1, "type": "heartbeat", "ts": 1794798615000, "subscriptions": 5 }          // every 15 s245{ "v": 1, "type": "pong", "t": 42, "ts": 1794798615003 }246{ "v": 1, "type": "dropped", "channel": "trades", "id": "hyperliquid:BTC", "count": 37, "total": 37 }247{ "v": 1, "type": "unsubscribed", "channel": { "type": "quote", "id": "hyperliquid:BTC" }, "key": "quote|hyperliquid:BTC|" }248{ "v": 1, "type": "error", "code": "unknown_instrument", "message": "unknown instrument 'hyperliquid:NOPE'", "channel": { "type": "quote", "id": "hyperliquid:NOPE" }, "reqId": 7 }249```250251Error codes: `bad_frame` (not JSON, or a binary frame), `bad_message`, `unsupported_version`, `unknown_instrument`,252`unsupported_channel` (e.g. a book on GMX, a book on spot), `restricted` (the key), `too_many_subscriptions`, `rate_limited`,253`upstream_unavailable` (the venue cannot be asked now, or a hub budget is spent), `internal`. An error never closes the254connection by itself.255256Close codes: `1001` server shutting down (reconnect), `1009` frame too big, `4001` session ended / key no longer active (do257**not** reconnect with the same credential), `4002` flood, `4003` slow consumer, `4004` idle, `4005` dead peer, `4006` repeated258protocol violations.259260### Staleness261262Per source, from how often it really sends (`QUOTE_CADENCE_MS`, measured in the work note): Hyperliquid 15 s, edgeX 15 s,263dYdX 60 s, GMX 20 s, Coinbase 30 s, CoinGecko 15 min. Computed **twice**:264265- **server**: `stale` in a message is true when the venue is not `connected` or the value is older than its bound when the frame266  is built (it matters for the snapshot of a `subscribed`);267- **client**: `subscribed.staleAfterMs` gives the bound; the client re-evaluates with ITS clock (`freshnessOf`): `live` →268  `delayed` (5 s, or half the bound) → `stale`, `reconnecting` as soon as the tab's connection or the value's venue is not live.269  A frozen connection therefore turns stale on screen without any message; the heartbeat watchdog then re-opens it.270271The age shown counts from the figure's own date: local receive time, minus the snapshot's age, minus what the server measured272between the source's date and its receipt (a CoinGecko price dated 3 minutes before the server got it is 3 minutes old).273274## 5. Limits275276| Limit | Default | Where |277|---|---|---|278| connections per principal | owner 12 (`SPW_STREAM_MAX_CONN_OWNER`), API key 4 (`SPW_STREAM_MAX_CONN_KEY`) | before the upgrade: 429 `too_many_connections` |279| connections in total | 200 (`SPW_STREAM_MAX_CONN`) | idem |280| subscriptions per connection | 300 (`SPW_STREAM_MAX_SUBS`) | `error too_many_subscriptions` |281| client frame size | 16 kB | close 1009 |282| client frames | 20 / s, burst 40 | `error rate_limited`; 20 refusals in a row: close 4002 |283| idle (nothing subscribed, nothing received) | 120 s | close 4004 |284| liveness | protocol ping every 15 s; no pong by the next one | socket terminated (4005 counted) |285| upgrade requests | the service's global limit, 240 / minute per address | 429 |286| ticket | 30 s, single use, 2 000 pending at most | 401 / 429 |287288## 6. Backpressure289290Per connection (`outbox.ts`). A frame goes straight to the socket while the client keeps up (`bufferedAmount` ≤ 256 kB and291nothing queued). Otherwise the queue takes over — bounded by construction, at most one entry per subscription:292293- **quote, candle, status — conflated**: only the newest per channel is kept; the replaced one is counted (`conflated`);294- **book — conflated into a snapshot**: one queued delta is sent as it is (its predecessor was sent); a second one for the same295  channel turns the entry into a SNAPSHOT of the channel's current book, built when it is finally written (`bookResyncs`). A296  client never receives a delta whose predecessor it did not get;297- **trades — dropped, never silently**: the count is sent as a `dropped` frame as soon as the client drains (`count` since the298  last notice, `total` since the connection opened). Delivered + declared dropped = everything.299300A client over the high-water mark (4 MB) for 10 s, or beyond four times that mark, is closed with **4003**. The hub also301conflates quotes at the source: at most one quote per channel every 100 ms, always the newest state.302303Tested with a really slow consumer (a client whose socket stops reading while 6 000 bursts are pushed): the healthy client on304the same hub receives every message in order; the slow one catches up with the latest quote of each market, a book whose305sequence and checksum hold, and `delivered + dropped = 6 000` trades (`services/api/test/quotes-stream.test.ts`).306307## 7. Web client308309`apps/web/src/quotes.ts` (hooks), `quotes-ui.tsx` (pieces), `quotes-spot.tsx` (first-chunk screens).310311- **One connection per tab**, lazy: opened by the first subscriber, closed 2.5 s after the last one leaves (`lingerMs`).312- **Reconnect** with backoff + jitter (1 s … 30 s), **resubscribe** everything (the venue statuses always come along), books313  restart from their snapshot.314- **Heartbeat watchdog**: no frame for 2.5 heartbeat periods (37.5 s) → the connection is considered frozen and re-opened.315- **Visibility**: the tab hidden for 30 s → socket closed (`paused`); visible → reconnected at once, fresh snapshots.316- **Fallback**: three failed connections in a row → `fallback` (it keeps trying, slowly). Every screen keeps the REST polling it317  had; the Futures terminal re-opens its SSE stream. The state is shown (`LiveStatus`).318- **Rendering**: messages fill a pending buffer; ONE `requestAnimationFrame` commits and wakes only the components subscribed319  to the keys that changed (`useSyncExternalStore`). 3 000 messages on 150 markets = one commit, 150 cell renders.320- Hooks: `useQuote(id)`, `useQuotes(ids)`, `useBook(id, depth)`, `useTrades(id)`, `useVenueStatus()`, `useConn()`,321  `useFresh(value)`, `useQuoteSubscriptions(ids)`. Pieces: `LiveDot` / `QuoteDot` (live · delayed · stale · reconnecting, in322  words with the age), `LiveCell` (a ticking figure; the tick flash is off under `prefers-reduced-motion`), `LiveStatus`.323- **First chunk**: 260.61 kB → 262.30 kB (+1.69 kB; gzip 80.03 → 80.61 kB). The client is a chunk of its own (10.5 kB, 3.9 kB324  gzip) loaded by the screens that use it; Home and the asset page reach it through a dynamic import (`quotes-spot.tsx`).325326| Screen | What ticks | Without the socket |327|---|---|---|328| Markets explorer | price, 24 h change, funding of every row; freshness dot; stream + venue status | listing polled every 10 s as before (30 s while live) |329| Futures terminal | ticker, order book (sequence + checksum), trades — the shared socket replaces the per-instrument SSE stream | SSE stream re-opened; REST snapshot every 5 s as before |330| Compare | mark, index, spread of the table; the live price next to the price each cost estimate was computed on | 15 s polling as before. The comparison is recomputed on that cadence or on demand (« Recompute now »), never per tick |331| Private Markets | price, bid, ask of live contracts (builder-dex coins and edgeX) | 20 s polling as before (60 s while live) |332| Asset page, Home | streamed USD price where Coinbase lists the symbol (in CAD: converted at the rate of the polled reading — said on screen) | polled CoinGecko price with its own date, as before |333334## 8. SDKs335336New files only: `packages/trading-sdk/src/stream.ts` (`SPWalletStream`, `OrderBook`; zero dependency) and337`sdk/python/src/sp_wallet/stream.py` (`SPWalletStream`, `OrderBook`; asyncio, `websockets==16.0` as the optional extra338`stream`). Not yet re-exported from the packages' index files (they belong to the contract workstream): import339`@sp-wallet/trading-sdk/src/stream.ts` / `sp_wallet.stream`.340341```ts342const stream = new SPWalletStream({ apiKey: process.env.SP_WALLET_API_KEY, baseUrl: 'https://wallet.example' });343await stream.subscribe([{ type: 'quote', id: 'hyperliquid:BTC' }, { type: 'book', id: 'hyperliquid:BTC', depth: 10 }]);344const book = new OrderBook();345stream.on('book', (m) => { if (!book.apply(m)) stream.resync({ type: 'book', id: 'hyperliquid:BTC', depth: 10 }); });346for await (const m of stream) if (m.type === 'quote') console.log(m.id, m.bid, m.ask, m.stale);347```348349```python350async with SPWalletStream(api_key="spw_live_…", base_url="https://wallet.example") as stream:351    await stream.subscribe([{"type": "quote", "id": "hyperliquid:BTC"}])352    async for m in stream:353        print(m.id, m.bid, m.ask, m.stale)354```355356Node (≥ 22, or the `ws` package passed as `WebSocket`) and Python send the key in the `Authorization` header of the handshake.357Browsers use a ticket: `ticket: () => fetchTicketFromYourBackend()`, or `auth: 'ticket'` when the page is served by the wallet's358origin. Both clients reconnect (backoff + jitter), resubscribe, watch the heartbeat, stop for good on `4001` or a refused359credential, and bound the `for await` buffer (oldest dropped, counted).360361## 9. Failure modes362363| What happens | What the client sees |364|---|---|365| A venue's connection drops | `status reconnecting` for that venue; its quotes say `reconnecting` then `stale`; the other venues are untouched; on return `status connected`, books restart from a snapshot |366| A venue does not come back in 30 s | `status down`, until it is connected again |367| A venue sends garbage | the frame is dropped and counted (`errors`, `lastError` in the stats); never a partial quote |368| A hole in a venue's book sequence | the upstream client resubscribes that channel; the hub sends a snapshot |369| A poll fails (GMX, CoinGecko) | no message; `status stale`, `down` after three failures |370| The client is slow | conflation, `dropped` notices; 4003 if it stays over the high-water mark |371| The client's connection freezes | no heartbeat → its watchdog reconnects; meanwhile every figure turns stale on its own clock |372| The websocket cannot be opened (proxy) | web: `fallback`, REST polling / SSE; SDK: an error after three attempts when it never opened |373| Session ends, key revoked | close 4001 |374| The API restarts | close 1001 « server shutting down »; clients reconnect and resubscribe; upstream connections are re-opened on demand |375| A hub budget is spent | `error upstream_unavailable` for the new channel; existing channels are untouched |376377## 10. Metrics and logs378379`GET /api/v1/stream/stats` (owner) — and a summary in `GET /api/v1/monitor/health` (`quotes`):380381```382connections { open, byPrincipal, total, refused }      subscriptions      messagesPerSec (last 10 s)      messagesSent, bytesSent383backpressure { queuedNow, conflated, tradesDropped, bookResyncs, slowConsumersClosed }384clients { deadPeers, badFrames, rateLimited, restricted, unauthorizedClosed }      tickets { issued, used, refused, pending }385upstreamReconnects      lagMs { samples, p50, p95 }386hub { channels, channelsByType, feeds, listeners, counters { quote, book, bookSnapshots, trade, candle, status, upstreamMessages, gaps, … },387      venues [ { venue, status, since, ageMs, transport, source, feeds, messages, reconnects, gaps, errors, lastError, upstream } ] }388```389390`lagMs` is measured from the venue's own timestamp of an update to that update being written to a client socket — only on391updates the venue stamped (Hyperliquid best bid / offer and books, trades, Coinbase tickers), sent without queueing.392393Structured logs (the service's pino logger): `quotes.conn.open` / `quotes.conn.close` (info: who, via, counters, duration),394`quotes.conn.closed` (warn: abnormal close with its code), `quotes.conn.dead`, `quotes.venue` (status changes; `down` at warn),395`quotes.gap`, `quotes.socket.error`. The cookie, the bearer header and a ticket are never logged (the logger redacts the two396headers; the ticket travels in the URL, which the service does not log at its level).397398## 11. Deployment notes (nothing was changed in production)399400- **Caddy** proxies websockets with a plain `reverse_proxy`: it performs the upgrade and tunnels the connection. No directive is401  needed. Two behaviours to know ([reverse_proxy documentation](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy)):402  `stream_timeout` — « Default: no timeout » — so Caddy does not cut a long-lived stream by itself; and on a **config reload**403  « WebSocket connections are forcibly closed » unless `stream_close_delay` is set. A reload is therefore a reconnection for404  every client (they do it by themselves, with jitter); setting `stream_close_delay 5m` in the site block would avoid it — a405  production change, not made.406- **Idle timers on the path** (a home router's NAT, a corporate proxy, a mobile carrier) are kept open by the 15 s heartbeat407  frame and the 15 s protocol ping. If an intermediary still cuts, the client's watchdog reconnects within 37.5 s.408- **`Origin`**: Caddy passes the browser's `Origin` header through; the API compares it with `SPW_ORIGIN`. `SPW_TRUST_PROXY`409  is unchanged (it concerns `req.ip`, used by the limits and the key IP allow-list).410- **Access logs**: a ticket appears in the request line of ONE upgrade request; it is single-use and expires in 30 s.411- **One process**: the hub is in-process. With `SPW_WORKERS=api` + a separate agents process, each process that builds the412  server has its own hub (and its own venue connections: Hyperliquid allows 10 per address).413- **Outbound**: the API host needs outbound `wss` to `api.hyperliquid.xyz`, `edgex-quote-prod-v2.edgex.exchange`,414  `indexer.dydx.trade` and `ws-feed.exchange.coinbase.com` (the first three were already used).415- **Restart**: `app.close()` closes every client with 1001 before the listener goes away (`main.ts` already calls it on416  SIGINT / SIGTERM).417418## 12. For the agents' stream engine419420`services/api/src/agent-runtime` has its own stream engine and stores `market_snapshots`; it was not edited. The hub exposes421what it can adopt instead of opening its own venue streams:422423```ts424import { quoteHub } from '../quotes/index.ts';425const hub = quoteHub()!;                                   // the hub of this process426await hub.validate({ type: 'quote', id: 'hyperliquid:BTC' });   // throws QuoteError(code) — unknown instrument, unsupported channel…427const sub = hub.subscribe({ type: 'quote', id: 'hyperliquid:BTC' }, (frame) => { /* frame.msg: QuoteMsg, typed; frame.lagTs */ });428sub.snapshot();         // the last known value now, or null429sub.unsubscribe();      // reference-counted: the upstream feed closes with its last user (after the idle grace)430hub.statuses();         // one StatusMsg per venue431```432433Same messages as on the wire (`protocol.ts`), same reference counting, same venue status; a listener that throws is isolated.434In a process without the HTTP server (`agent-worker-main.ts`) a hub can be built directly:435`new QuoteHub({ upstreams: defaultUpstreams(derivatives()) })`.436437## 13. Limits of this version438439- **Candles** are streamed by Hyperliquid only; edgeX, dYdX and GMX candles are the venues' REST bars re-read every 10 s440  (`source: <venue>-rest`). There is no candle channel for spot.441- **Bid / ask of edgeX and dYdX quotes** come from the order book and are present only while a book of that market is open in442  the hub (someone subscribed to it); otherwise they are `null` (edgeX's ticker increments and dYdX's market feed carry none).443- **dYdX quotes are sparse**: the feed speaks when the oracle price or the funding estimate moves (5 in a minute on BTC).444- **Hyperliquid `l2Book`** arrived every 5 to 12 s in the runs of 2026-11-15 (5 to 6 messages a minute on BTC); the best bid /445  offer (`bbo`, ≈ 10 / s) is what keeps the quote live. The terminal's book is as fresh as the venue's feed, no more.446- **Spot** streams from ONE exchange (Coinbase), in USD. The CAD figure on Home and the asset page is that price converted at447  the rate implied by the last polled reading; symbols Coinbase does not list stay on the polled price module.448- **GMX** has no stream: one quote per fresh read of the venue, about every 6 s (10 in a minute in the smoke).449- **One process**: no cross-process fan-out; connection limits are per process.450- **Safari / iOS** were not run (Chromium only); the CSP names the websocket origin explicitly for the old Safari behaviour.451- *(updated 2026-11-17)* The SDK stream classes are exported from both packages' index files since `v11-contract2`452  (`docs/v11/work/contract-resync.md` Part 3 §1). The OpenAPI document does not (cannot) describe the websocket: the453  stream has no machine-readable contract (`V11-REMAINING-LIMITATIONS.md` 6.5).454
Files main
Menu

Theme