Skip to content

Venue coverage

Family: SDK-crate (atelier-connect · framework registry) · min version 0.0.10

The ingestion framework connects to a fixed set of public exchange feeds through a registry of per-venue adapters. Each adapter wires three small implementations against one generic transport seam: a ProtocolHooks (subscribe framing, heartbeat, codec, bootstrap), a Normalizer (decoded frame to DomainEvent), and an ExchangeAdapter registry entry (profile, reconstruction model, spawn). This page is the coverage map for that registry: which venues resolve at boot, what each streams, and how each rebuilds a live book.

Scope

This page covers the open connector surface — what the SDK framework can connect to and normalize. It is a map of adapters and wire behavior, keyed to the framework registry in atelier-connect.

Coverage matrix

Twelve venues compile into the registry and self-check at boot (the registry resolves every requested venue id to a registered adapter, turning a silent empty stream into a fail-fast startup error). Every adapter streams a Level-2 order book and public trades over one multi-symbol socket on the venue's spot feed.

Venue Order book Trades Funding Open interest Liquidations Market Reconstruction model
binance yes yes — — — spot SeqDelta · RangeInclusive
bybit yes yes — — — spot SeqDelta · RangeInclusive
coinbase yes yes — — — spot SeqDelta · Monotonic
kraken yes yes — — — spot ChecksumDelta · top-10 CRC32
okx yes yes — — — spot ChecksumDelta · top-25 CRC32
gateio yes yes — — — spot FullRefresh · top-20
htx yes yes — — — spot SeqDelta · ExactPrev
kucoin yes yes — — — spot SeqDelta · RangeInclusive
bitso yes yes — — — spot L3 · per-order book
bitget yes yes — — — spot SeqDelta · ExactPrev
poloniex yes yes — — — spot SeqDelta · ExactPrev
upbit yes yes — — — spot FullRefresh · top-N

A dash marks a datatype delivered through the source clients rather than the framework's normalized event stream. The framework's DomainEvent models exactly two shapes — an order-book snapshot/delta and a public-trade print — so order book and trades are the coverage surface. Funding, open interest, and liquidations are modeled as first-class schema types in atelier-types and are consumed through the per-venue source clients; the framework normalizer forwards book and trade events. Bybit's decoder, for example, recognizes liquidation and ticker frames and returns them out of the normalized book-and-trades stream.

Reconstruction models

A venue's book model is keyed per channel (a venue may run one model on one channel and another elsewhere). Four models cover the twelve adapters. Each rebuilds a live book over the Empty → Synced ⇄ Gapped → Closed lifecycle and raises ResyncNeeded on a continuity break rather than silently dropping.

Model How it stays correct Venues
FullRefresh Every frame is a complete top-N book; each frame replaces the prior one. gateio (top-20), upbit
SeqDelta Incremental deltas seeded by a snapshot, validated by a sequence predicate. binance, bybit, coinbase, htx, kucoin, bitget, poloniex
ChecksumDelta Incremental deltas, each validated by a venue CRC32 over the top levels. okx (top-25), kraken (top-10)
L3 Per-order book keyed by order id, aggregated to price levels. bitso

SeqDelta continuity is decided by a per-venue predicate:

  • RangeInclusive (binance, bybit, kucoin) — each delta's id range must abut the last applied id; a forward jump is a dropped-frame gap.
  • ExactPrev (htx, bitget, poloniex) — each delta carries a previous-id pointer that must equal the last applied id.
  • Monotonic (coinbase) — the id is a connection-wide counter bumped by every message on the socket, so only strict monotonic advance is required.

The seeding snapshot arrives from one of three sources: a REST GET (RestSnapshot — binance, kucoin, bitso), an in-band request on the same socket (ReqOnSocket — htx), or the channel's first post-subscribe frame (WssSelfSeed — bybit, coinbase, bitget, poloniex).

flowchart LR
    frame["Decoded venue frame"] --> norm["Normalizer:<br/>frame to DomainEvent"]
    norm --> book["Book event"]
    norm --> trade["Trade event"]
    book --> model{"Reconstruction<br/>model"}
    model -->|FullRefresh| fr["Replace book<br/>each frame"]
    model -->|SeqDelta| sd["Seed + validate<br/>by sequence"]
    model -->|ChecksumDelta| cd["Apply + verify<br/>CRC32"]
    model -->|L3| l3["Per-order map<br/>to price levels"]
    fr --> synced["Synced book"]
    sd --> synced
    cd --> synced
    l3 --> synced
    trade --> log["Ordered, de-duplicated<br/>trade log"]

Diagram: a decoded venue frame is normalized to either a book event or a trade event; a book event is rebuilt by one of four reconstruction models into a synced book, while a trade event is appended to an ordered, de-duplicated trade log.

Public-trade prints append to a SourcedTradeBook, which orders and de-duplicates by the venue trade-sequence where one is provided and otherwise runs best-effort. Across the registered adapters trades run best-effort: each print is appended, and no print is dropped in favor of a batch head.

Symbol spelling

Each adapter carries a symbol codec that renders a canonical pair to the venue's wire spelling and parses it back.

Codec Wire form Venues
Concat BTCUSDT binance, bybit, bitget (upper); htx (lower)
Hyphen BTC-USDT coinbase, okx, kucoin
Slash BTC/USDT kraken
Underscore BTC_USDT gateio, poloniex (upper); bitso (lower)
QuoteFirst KRW-BTC upbit

Per-venue notes

Notes appear where a venue's transport or reconstruction is distinctive. Venues that follow the common pattern (one multi-symbol socket, REST- or self-seeded SeqDelta book) are fully described by the matrix above.

bitso

The one Level-3 venue. Bitso streams diff-orders: per-order changes keyed by order id, seeded by a REST L3 snapshot that carries the same order ids. The book engine keeps an order-id map, aggregates it to price levels incrementally (each order change touches only its own level), and projects the result onto the shared L2 engine so the emit path matches every other venue.

kraken

Incremental book deltas are validated by a CRC32 over the top-10 levels (price and quantity with the decimal point and leading zeros removed). The book is held at exactly the subscribed depth because the checksum is computed over that depth. Kraken pushes its own server heartbeats, so the client runs no keep-alive timer.

okx

Incremental books deltas are validated by a CRC32 over the top-25 levels interleaved by rank. The socket uses {op, args:[{channel, instId}]} subscribe framing and an application-level "ping"/"pong" text heartbeat.

htx

Frames arrive gzip-compressed; the transport inflates them before the adapter sees text. Keep-alive is server-driven — HTX sends {"ping":<ts>} and the client echoes {"pong":<ts>}. The MBP depth book is seeded by an in-band request appended after the subscribe frames, and its deltas chain by a previous-sequence pointer; a gap re-issues that in-band request.

kucoin

KuCoin requires a bullet-token bootstrap: the adapter first fetches a one-time token, the live socket endpoint, and the server's ping cadence, then connects to the dynamic URL. The book is a REST-seeded SeqDelta.

coinbase

The level2 book self-seeds from the first WSS snapshot frame, then validates updates by a connection-wide sequence_num — a counter bumped by every message on the socket, not a per-book contiguous id — so continuity is a strict monotonic advance.

gateio

spot.order_book is a limited-depth full-snapshot channel: each frame is a complete top-20 book every 100ms, mapped onto FullRefresh (each frame replaces the book, no seed, no continuity gate). Keep-alive is a text ping whose payload carries a live Unix-seconds timestamp recomputed per tick.

upbit

Each orderbook frame is a complete top-N book, so reconstruction is FullRefresh with no seeding or sequence gate. Symbols are spelled quote-first (KRW-BTC).

bitget

books deltas carry a seq/pseq pair and self-seed from the first action:"snapshot" frame; continuity is previous-id (ExactPrev). Keep-alive is a client-initiated literal "ping", answered by the venue with "pong".

poloniex

book_lv2 self-seeds from an in-band action:"snapshot" first frame; each frame carries both this update's id and the previous one, so deltas chain by an exact previous-id pointer. A gap re-subscribes the channel.

Adding a venue

A new public order-book-and-trades venue needs three implementations and one registry line:

  1. a ProtocolHooks — endpoint, subscribe frames, heartbeat, codec, and any pre-connect bootstrap;
  2. a WssDecoder plus a Normalizer mapping decoded frames to DomainEvents;
  3. an ExchangeAdapter entry declaring the profile, symbol codec, and book reconstruction model, registered in the single adapter list.