Global Orderbook Module API

The Orderbook API provides real-time orderbook aggregation across multiple exchanges (Binance, Bybit, Gate.io, Kraken). It streams public orderbook data via WebSocket and provides quality metrics for each venue.

Key Features

Multi-venue aggregation: Subscribe to orderbooks across multiple exchanges simultaneously
Quality metrics: Staleness, spread, depth, and confidence scoring per venue
Global best prices: Find the best bid/ask across all venues
Ref-counting subscriptions: Efficient resource management with warm cache
No authentication required: Orderbook data is public

Subscribe to orderbook updates for one or more symbols on one or more venues.

Request Body (JSON)

symbols (array, required): List of trading pairs in CCXT format (e.g., ["BTC/USDT", "ETH/USDT"])
venues (array, required): List of exchange venues: "binance", "bybit", "gateio", "kraken"

Request Example

curl -X POST http://localhost:8082/oems/orderbook/subscribe \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["BTC/USDT", "ETH/USDT"],
    "venues": ["binance", "bybit", "gateio", "kraken"]
  }'

Response Examples

Success

{
  "isError": false,
  "message": "Subscribed",
  "statusCode": 200,
  "data": {
    "subscriptions": [
      {"venue": "binance", "symbol": "BTC/USDT", "status": "active"},
      {"venue": "bybit", "symbol": "BTC/USDT", "status": "active"},
      {"venue": "gateio", "symbol": "BTC/USDT", "status": "pending"},
      {"venue": "kraken", "symbol": "BTC/USDT", "status": "active"}
    ]
  }
}

Invalid Request

{
  "isError": true,
  "message": "Error - unsupported venue: fake. Supported: binance, bybit, gateio, kraken",
  "statusCode": 400
}

Subscription Status Values

Status	Description
`pending`	WebSocket connection in progress
`active`	Receiving orderbook updates
`error`	Connection failed
`warm_cache`	Unsubscribed but still cached (5 min)

POST /oems/orderbook/unsubscribe

Unsubscribe from orderbook updates. Subscriptions move to warm cache (5 minutes) before being fully closed.

Request Body (JSON)

symbols (array, required): List of trading pairs to unsubscribe from
venues (array, required): List of exchange venues to unsubscribe from

Request Example

curl -X POST http://localhost:8082/oems/orderbook/unsubscribe \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["BTC/USDT"],
    "venues": ["binance", "bybit"]
  }'

Response Example

{
  "isError": false,
  "message": "Unsubscribed from 4 subscription(s)",
  "statusCode": 200
}

GET /oems/orderbook/book

Get current orderbook data. Returns either a single venue’s book or a global aggregated view.

Query Parameters

symbol (string, required): Trading pair (e.g., “BTC/USDT”)
venue (string, optional): Specific venue (omit for global view across all subscribed venues)
venues (string, optional): Comma-separated list of venues to filter global view (e.g., “binance,gateio”). Use this to get a client-specific view of subscribed venues.
depth (integer, optional): Number of orderbook levels to return (1-100). Default: 20

Request Examples

# Single venue
curl "http://localhost:8082/oems/orderbook/book?symbol=BTC/USDT&venue=binance&depth=10"

# Global view (all venues)
curl "http://localhost:8082/oems/orderbook/book?symbol=BTC/USDT"

Response Examples

Single Venue

{
  "isError": false,
  "message": "Success",
  "statusCode": 200,
  "data": {
    "venue": "binance",
    "symbol": "BTC/USDT",
    "bids": [[87951.30, 1.5], [87950.00, 2.3], [87949.50, 0.8]],
    "asks": [[87951.31, 0.8], [87952.00, 1.2], [87953.00, 3.5]],
    "mid_price": 87951.305,
    "spread_bps": 0.01,
    "staleness_ms": 45,
    "confidence": 0.95,
    "timestamp": "2025-12-19T14:56:00.000000",
    "sequence": 83589979142
  }
}

Global View

{
  "isError": false,
  "message": "Success",
  "statusCode": 200,
  "data": {
    "symbol": "BTC/USDT",
    "timestamp": "2025-12-19T14:56:00.000000",
    "best_bid": {
      "price": 87953.60,
      "quantity": 0.23,
      "venue": "gateio"
    },
    "best_ask": {
      "price": 87949.90,
      "quantity": 0.12,
      "venue": "bybit"
    },
    "venues": {
      "binance": {"bid": 87951.30, "ask": 87951.31, "confidence": 0.95},
      "bybit": {"bid": 87949.80, "ask": 87949.90, "confidence": 1.0},
      "gateio": {"bid": 87953.60, "ask": 87953.70, "confidence": 0.92},
      "kraken": {"bid": 87951.30, "ask": 87951.40, "confidence": 0.98}
    }
  }
}

Not Found

{
  "isError": true,
  "message": "No orderbook data available for BTC/USDT on binance",
  "statusCode": 404
}

Notes

A negative global spread (best_bid > best_ask) indicates a cross-venue arbitrage opportunity
Bids are sorted by price descending (best first)
Asks are sorted by price ascending (best first)

GET /oems/orderbook/quality

Get quality metrics for all venues with orderbook data for a symbol.

Query Parameters

symbol (string, required): Trading pair (e.g., “BTC/USDT”)

Request Example

curl "http://localhost:8082/oems/orderbook/quality?symbol=BTC/USDT"

Response Example

{
  "isError": false,
  "message": "Success",
  "statusCode": 200,
  "data": {
    "symbol": "BTC/USDT",
    "venues": [
      {
        "venue": "bybit",
        "staleness_ms": 19,
        "spread_bps": 0.01,
        "depth_at_10bps": 15.5,
        "depth_at_50bps": 42.3,
        "bid_ask_imbalance": 0.12,
        "update_rate_per_sec": 28.5,
        "sequence_gaps": 0,
        "quality": "GOOD",
        "confidence": 1.0
      },
      {
        "venue": "binance",
        "staleness_ms": 71,
        "spread_bps": 0.0,
        "depth_at_10bps": 12.8,
        "depth_at_50bps": 38.1,
        "bid_ask_imbalance": -0.05,
        "update_rate_per_sec": 9.3,
        "sequence_gaps": 1245,
        "quality": "GOOD",
        "confidence": 0.69
      }
    ]
  }
}

Quality Levels

Quality	Staleness	Description
`GOOD`	< 500ms	Fresh data, reliable for execution
`DEGRADED`	500ms - 2s	Slightly stale, use with caution
`STALE`	2s - 5s	Old data, not recommended for execution
`UNAVAILABLE`	> 5s	No recent updates, do not use

Confidence Scoring

Confidence starts at 1.0 and is reduced by:

Staleness: Up to -0.4 (linear to 5000ms)
Wide spread: Up to -0.2 (linear from 1bps to 20bps)
Sequence gaps: -0.05 per gap, max -0.3
If quality is UNAVAILABLE: confidence = 0

GET /oems/orderbook/subscriptions

Get current subscription status and statistics.

Request Example

curl "http://localhost:8082/oems/orderbook/subscriptions"

Response Example

{
  "isError": false,
  "message": "Success",
  "statusCode": 200,
  "data": {
    "active_count": 6,
    "warm_cache_count": 2,
    "by_venue": {
      "binance": 2,
      "bybit": 2,
      "gateio": 2,
      "kraken": 2
    },
    "subscriptions": [
      {
        "venue": "binance",
        "symbol": "BTC/USDT",
        "ref_count": 2,
        "status": "active",
        "subscribed_at": "2025-12-19T14:50:00.000000",
        "last_update": "2025-12-19T14:56:41.000000"
      },
      {
        "venue": "binance",
        "symbol": "ETH/USDT",
        "ref_count": 1,
        "status": "active",
        "subscribed_at": "2025-12-19T14:55:00.000000",
        "last_update": "2025-12-19T14:56:40.000000"
      }
    ]
  }
}

GET /oems/orderbook/stats

Get service statistics including store and subscription metrics.

Request Example

curl "http://localhost:8082/oems/orderbook/stats"

Response Example

{
  "isError": false,
  "message": "Success",
  "statusCode": 200,
  "data": {
    "store": {
      "book_count": 8,
      "venues": ["binance", "bybit", "gateio", "kraken"],
      "symbols": ["BTC/USDT", "ETH/USDT"],
      "total_gaps": 2450
    },
    "subscriptions": {
      "active_count": 8,
      "warm_cache_count": 0,
      "total_count": 8,
      "by_status": {"active": 8},
      "by_venue": {"binance": 2, "bybit": 2, "gateio": 2, "kraken": 2},
      "collectors": ["binance", "bybit", "gateio", "kraken"]
    },
    "initialized_venues": ["binance", "bybit", "gateio", "kraken"]
  }
}

Supported Venues

Venue	Update Rate	Notes
Bybit	~28/sec	Highest update rate, excellent for HFT
Kraken	~15/sec	Good update rate, reliable
Binance	~9/sec	Standard rate, tightest spreads
Gate.io	~8/sec	Good depth, slightly slower

Typical Use Cases

1. Smart Order Routing (SOR)

# Subscribe to all venues
curl -X POST http://localhost:8082/oems/orderbook/subscribe \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["BTC/USDT"], "venues": ["binance", "bybit", "gateio", "kraken"]}'

# Get global view to find best prices
curl "http://localhost:8082/oems/orderbook/book?symbol=BTC/USDT"

# Check quality before routing
curl "http://localhost:8082/oems/orderbook/quality?symbol=BTC/USDT"

2. Arbitrage Detection

# Get global view - negative spread = arb opportunity
curl "http://localhost:8082/oems/orderbook/book?symbol=BTC/USDT"
# Response: best_bid on gateio > best_ask on bybit = buy bybit, sell gateio

3. Execution Quality Monitoring

# Monitor update rates and staleness
curl "http://localhost:8082/oems/orderbook/quality?symbol=BTC/USDT"
# Use venues with confidence >= 0.4 and staleness < 2000ms

WebSocket Streaming

Real-time orderbook streaming via WebSocket for low-latency updates.

Connection

Connect to the WebSocket endpoint:

ws://localhost:8082/socket.io/

Events

Client to Server

Event	Payload	Description
subscribe_orderbook	symbol, venues, include_global, depth	Subscribe to orderbook stream
unsubscribe_orderbook	symbol	Unsubscribe from stream
get_snapshot	symbol, venues	Request current snapshot

Server to Client

Event	Payload	Description
connected	sid, message	Connection acknowledged
subscribed	symbol, venues, include_global, depth	Subscription confirmed
orderbook_snapshot	symbol, venues, timestamp	Initial snapshot with full depth
orderbook_update	venue, symbol, bids, asks, …	Per-venue update with depth
global_book	symbol, data, timestamp	Aggregated global view

Parameter	Type	Default	Description
symbol	string	required	Trading pair (e.g., “BTC/USDT”)
venues	array	all	Filter to specific venues
include_global	boolean	true	Include global best prices
depth	integer	5	Number of price levels: 1, 5, 10, or 20

JavaScript Example

// Connect
var socket = io('http://localhost:8082', {transports: ['websocket']});

// Subscribe to BTC/USDT with 10 levels of depth
socket.emit('subscribe_orderbook', {
  symbol: 'BTC/USDT',
  venues: ['binance', 'bybit'],
  include_global: true,
  depth: 10
});

// Receive per-venue updates
socket.on('orderbook_update', function(data) {
  console.log(data.venue, data.bids.length, 'levels');
  console.log('Best bid:', data.bids[0]);
  console.log('Best ask:', data.asks[0]);
});

// Receive global best prices
socket.on('global_book', function(data) {
  console.log('Global best bid:', data.data.best_bid);
});

Update Payload

Each update includes arrays of price and quantity pairs:

{
  "venue": "binance",
  "symbol": "BTC/USDT",
  "bids": [
    [88150.50, 1.5],
    [88150.00, 2.3],
    [88149.50, 0.8]
  ],
  "asks": [
    [88151.00, 0.8],
    [88151.50, 1.2],
    [88152.00, 0.5]
  ],
  "spread_bps": 0.57,
  "mid_price": 88150.75,
  "staleness_ms": 15.2,
  "confidence": 0.98,
  "quality": "GOOD",
  "timestamp": "2025-12-19T15:30:00.000000"
}

bids: Sorted by price descending (best first)
asks: Sorted by price ascending (best first)

Python Example

import socketio

sio = socketio.Client()

@sio.on('orderbook_update')
def on_update(data):
    print(data['venue'], len(data['bids']), 'levels')
    print('Best bid:', data['bids'][0])
    print('Best ask:', data['asks'][0])

@sio.on('global_book')
def on_global(data):
    print('Global best bid:', data['data']['best_bid'])

sio.connect('http://localhost:8082', transports=['websocket'])
sio.emit('subscribe_orderbook', {
    'symbol': 'BTC/USDT',
    'venues': ['binance', 'bybit', 'gateio'],
    'depth': 10
})
sio.wait()

Performance

Update rate: 10-20 updates/sec per symbol
Latency: Under 100ms from exchange to client
Broadcast interval: 100ms (sends only changed data)
Recommended depth: 5-10 for most use cases, 20 for detailed analysis

Getting Started

API Reference

​Global Orderbook Module API

​Key Features

​POST /oems/orderbook/subscribe

​Request Body (JSON)

​Request Example

​Response Examples

​Success

​Invalid Request

​Subscription Status Values

​POST /oems/orderbook/unsubscribe

​Request Body (JSON)

​Request Example

​Response Example

​GET /oems/orderbook/book

​Query Parameters

​Request Examples

​Response Examples

​Single Venue

​Global View

​Not Found

​Notes

​GET /oems/orderbook/quality

​Query Parameters

​Request Example

​Response Example

​Quality Levels

​Confidence Scoring

​GET /oems/orderbook/subscriptions

​Request Example

​Response Example

​GET /oems/orderbook/stats

​Request Example

​Response Example

​Supported Venues

​Typical Use Cases

​1. Smart Order Routing (SOR)

​2. Arbitrage Detection

​3. Execution Quality Monitoring

​WebSocket Streaming

​Connection

​Events

​Client to Server

​Server to Client

​Subscribe Parameters

​JavaScript Example

​Update Payload

​Python Example

​Performance

Global Orderbook Module API

Key Features

POST /oems/orderbook/subscribe

Request Body (JSON)

Request Example

Response Examples

Success

Invalid Request

Subscription Status Values

POST /oems/orderbook/unsubscribe

Request Body (JSON)

Request Example

Response Example

GET /oems/orderbook/book

Query Parameters

Request Examples

Response Examples

Single Venue

Global View

Not Found

Notes

GET /oems/orderbook/quality

Query Parameters

Request Example

Response Example

Quality Levels

Confidence Scoring

GET /oems/orderbook/subscriptions

Request Example

Response Example

GET /oems/orderbook/stats

Request Example

Response Example

Supported Venues

Typical Use Cases

1. Smart Order Routing (SOR)

2. Arbitrage Detection

3. Execution Quality Monitoring

WebSocket Streaming

Connection

Events

Client to Server

Server to Client

Subscribe Parameters

JavaScript Example

Update Payload

Python Example

Performance