Skip to content

feat: add WebSocket order book feed with reconnection and heartbeat#26

Open
alexanderxfgl-bit wants to merge 1 commit intokcolbchain:mainfrom
alexanderxfgl-bit:feat/orderbook-websocket-feed
Open

feat: add WebSocket order book feed with reconnection and heartbeat#26
alexanderxfgl-bit wants to merge 1 commit intokcolbchain:mainfrom
alexanderxfgl-bit:feat/orderbook-websocket-feed

Conversation

@alexanderxfgl-bit
Copy link
Copy Markdown

Closes #7

What

Adds a transport-agnostic WebSocket order book feed system that allows strategies to consume real-time L2 data without caring about the underlying transport.

Changes

  • src/connectors/orderbook_feed.py — Complete order book feed system:

    • BaseOrderBookFeed — Abstract interface with subscribe(), unsubscribe(), get_orderbook(), and on_update() callbacks. Strategies depend on this, not specific transports.

    • WebSocketOrderBookFeed — Core WebSocket transport:

      • Exponential backoff reconnection (configurable base/max delay, max attempts)
      • Heartbeat monitoring via ping_interval and ping_timeout
      • Snapshot + incremental delta merging (snapshot replaces, delta updates)
      • Delta queuing: deltas received before initial snapshot are buffered
      • Zero-quantity level removal (handles filled/cancelled orders)
      • Auto re-subscribe on reconnect
      • wait_for_snapshot() async helper for initial data
    • BinanceOrderBookFeed — Binance partial book depth stream:

      • Supports depth 5/10/20 at 100ms or 1000ms intervals
      • SUBSCRIBE/UNSUBSCRIBE protocol messages
      • Parses Binance depthUpdate format
    • UniswapV3OrderBookFeed — Reconstructed order book from on-chain data:

      • Takes slot0 (sqrtPriceX96, liquidity, tick) as input
      • Reconstructs L2 at adjacent ticks with decayed liquidity
      • Useful for strategies that need simulated order book from Uniswap
    • OrderBookSnapshot — Rich data model:

      • best_bid, best_ask, spread, mid_price properties
      • depth_at_price() for analyzing liquidity at a level
      • Sequence tracking for delta ordering
    • create_binance_feed() — Factory function for quick setup

Tests

28 new tests covering:

  • OrderBookSnapshot properties (empty, best_bid/ask, spread, mid_price, depth)
  • WebSocket feed subscribe/unsubscribe and symbol normalization
  • Full snapshot replacement
  • Delta queuing before snapshot + application after
  • Zero-quantity level removal
  • Static level update helper
  • Binance message parsing + non-depth event filtering
  • Uniswap V3 slot0 reconstruction
  • Factory function and config defaults

All 106 tests passing (1 pre-existing integration failure).

Closes kcolbchain#7

Implements transport-agnostic order book streaming via WebSocket:

## Changes
- **src/connectors/orderbook_feed.py** — Full order book feed system:
  - BaseOrderBookFeed: Abstract interface for strategies to consume L2 data
  - WebSocketOrderBookFeed: Core WS transport with:
    - Exponential backoff reconnection
    - Heartbeat monitoring (ping/pong)
    - Snapshot + incremental delta merging
    - Delta queuing before initial snapshot
    - Zero-quantity level removal (filled/cancelled orders)
  - BinanceOrderBookFeed: Binance partial book depth stream adapter
  - UniswapV3OrderBookFeed: Reconstructed order book from slot0 data
  - OrderBookSnapshot with best_bid/ask, spread, mid_price, depth_at_price

## Tests
28 new tests covering:
- OrderBookSnapshot properties (best_bid, best_ask, spread, mid_price, depth)
- WebSocket feed subscribe/unsubscribe
- Symbol normalization
- Full snapshot replacement
- Delta queuing before snapshot
- Delta merging after snapshot
- Zero-quantity level removal
- Static level update helper
- Binance message parsing
- Binance non-depth event filtering
- Uniswap V3 slot0 order book reconstruction
- Sequence incrementing
- Factory function create_binance_feed
- Config defaults and custom values

All 106 tests passing (1 pre-existing integration failure).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

WebSocket streaming for real-time order book updates

1 participant