This file covers the public market-data socket, quote and band decoding, REST contract summaries, and order-book fallback. Endpoint shapes were observed on 2026-09-30; consumers must validate current data rather than assume a remembered listing.
TL;DR
- MDS is public and its subscribe frame is flat, unlike the trade socket's
paramsenvelope. - BBO price and size are decimal strings; validate both sides before deriving a midpoint.
- The live band is
minmax_price; invalidate it on disconnection. - REST books may contain many zero-size padded rows.
last_pricehas no freshness proof and is weaker evidence than a timestamped healthy quote.
1. Stream contract
Connect to wss://mds.qfex.com and send {type: 'subscribe', channels: ['bbo'], symbols: ['EXAMPLE-USD']}. The synthetic symbol illustrates the shape and is not a listing claim. Acknowledgement contains type: 'subscribed', channels, and symbols.
Channels documented or returned by the server include level2, trade, underlier, candle, funding, mark_price, open_interest, minmax_price, bbo, and market_stats. The toolkit's main data workflow consumes BBO and live bands; listing a channel here does not imply a complete implementation for it.
Observed BBO frames contained sequence, type, ISO time, symbol, and bid/ask arrays of [price, size] strings. The pulsed interval was about 500 ms per subscribed symbol. Subscription breadth and per-frame symbol count are caller policies; select them explicitly.
The MDS error form is flat, with error_code: 'InvalidJSON' observed for an unsupported channel. The trade socket uses different codes and envelopes. Decode by surface.
2. Live band freshness
minmax_price frames contain symbol, min_price, max_price, and time. The stream decoder requires finite nonnegative boundaries and a positive-width interval. Keep the raw server time and receipt time separately when the consuming application needs both.
The stream's resend cadence is unverified: a band may be emitted on change rather than on a periodic timer. A band-selection helper therefore needs explicit freshness policy and connection health. Core createMarketDataStream ages a band from its own frame. Experimental createStreamAgeMarketData extends that age from other symbol frames; those frames cannot prove that the old band is unchanged. Disconnect clears stream-backed confidence. A reference-data fallback must identify its age; it is not equivalent to a live band.
IoC band usage is described in markets-and-numbers.md §4. Band validity is separate from whether executable liquidity exists at the boundary.
3. REST contracts and books
GET /md/contracts returns summary rows including ticker identity, base/target currencies, last price, volume, open interest, index price, funding rate, next rate, and next-funding timestamp. Most numeric values are decimal strings. It supplies no bid/ask pair, and a last trade can be old on an inactive book.
GET /md/orderbook/{ticker_id} returns millisecond timestamp, bids, and asks as string pairs. Public responses observed 2026-09-30 included padded zero-size levels. Remove zero-size rows, reject malformed remaining rows, sort bids descending and asks ascending, and reject crossed or one-sided books as a midpoint source.
The existing symbol-price path uses a fresh BBO midpoint, then a validated REST-book midpoint, then a contract last price with explicitly weaker freshness. The package exposes the quote and book decoders separately; the caller supplies freshness and fallback policy.
4. Funding data
Funding documentation describes hourly calculation and settlement while the product's funding session is open; funding can be zero outside those hours. The live funding channel conveys the implied rate for its current window. Fees, funding cash flows, and trading PnL are distinct quantities; account mechanics are in account-and-leverage.md §4.
Pitfalls
| What breaks | Why | Correct approach |
|---|---|---|
| Subscription is rejected | Trade and MDS envelopes differ | Use flat MDS fields |
| Midpoint is zero or crossed | Padding or malformed sides | Filter size zero, validate both sides |
| A band survives a dead stream | Receipt time alone was retained | Include connection health |
| Last trade is treated as current liquidity | Summary data has no bid/ask or age proof | Prefer fresh quotes |
Open questions / not verified
- Band push cadence and server sequence-reset semantics across reconnects.
- Public REST and handshake throttling ceilings.
- Browser use outside the venue origin: observed CORS responses allowed the venue website, so a separate origin must verify its own access.
Sources
Pulsed BBO; Minmax price; Contracts; Order book; Funding. Response-shape observations: 2026-09-30. Freshness and fallback rules are implementation safeguards.
© markpaper authors. Licensed under CC BY 4.0: when publishing or adapting this material, credit “markpaper — QFEX knowledge base” and link to the original and the license.