> ## Documentation Index
> Fetch the complete documentation index at: https://docs.renesis.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Global Orderbook Module API

> Global orderbook aggregation and streaming endpoints

# 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
* **Public market data**: Orderbook data is not account-specific. REST endpoints still require authentication at the API gateway; the WebSocket stream does not.

***

## POST /order-execution/orderbook/subscribe

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

```bash theme={null}
curl -X POST https://api.renesis.fi/order-execution/orderbook/subscribe \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["BTC/USDT", "ETH/USDT"],
    "venues": ["binance", "bybit", "gateio", "kraken"]
  }'
```

### Response Examples

#### Success

```json theme={null}
{
  "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

```json theme={null}
{
  "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 /order-execution/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

```bash theme={null}
curl -X POST https://api.renesis.fi/order-execution/orderbook/unsubscribe \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["BTC/USDT"],
    "venues": ["binance", "bybit"]
  }'
```

### Response Example

```json theme={null}
{
  "isError": false,
  "message": "Unsubscribed from 4 subscription(s)",
  "statusCode": 200
}
```

***

## GET /order-execution/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

```bash theme={null}
# Single venue
curl "https://api.renesis.fi/order-execution/orderbook/book?symbol=BTC/USDT&venue=binance&depth=10" \
  -H "X-API-Key: $API_KEY"

# Global view (all venues)
curl "https://api.renesis.fi/order-execution/orderbook/book?symbol=BTC/USDT" \
  -H "X-API-Key: $API_KEY"
```

### Response Examples

#### Single Venue

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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 /order-execution/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

```bash theme={null}
curl "https://api.renesis.fi/order-execution/orderbook/quality?symbol=BTC/USDT" \
  -H "X-API-Key: $API_KEY"
```

### Response Example

```json theme={null}
{
  "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 /order-execution/orderbook/subscriptions

Get current subscription status and statistics.

### Request Example

```bash theme={null}
curl "https://api.renesis.fi/order-execution/orderbook/subscriptions" \
  -H "X-API-Key: $API_KEY"
```

### Response Example

```json theme={null}
{
  "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 /order-execution/orderbook/stats

Get service statistics including store and subscription metrics.

### Request Example

```bash theme={null}
curl "https://api.renesis.fi/order-execution/orderbook/stats" \
  -H "X-API-Key: $API_KEY"
```

### Response Example

```json theme={null}
{
  "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)

```bash theme={null}
# Subscribe to all venues
curl -X POST https://api.renesis.fi/order-execution/orderbook/subscribe \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["BTC/USDT"], "venues": ["binance", "bybit", "gateio", "kraken"]}'

# Get global view to find best prices
curl "https://api.renesis.fi/order-execution/orderbook/book?symbol=BTC/USDT" \
  -H "X-API-Key: $API_KEY"

# Check quality before routing
curl "https://api.renesis.fi/order-execution/orderbook/quality?symbol=BTC/USDT" \
  -H "X-API-Key: $API_KEY"
```

### 2. Arbitrage Detection

```bash theme={null}
# Get global view - negative spread = arb opportunity
curl "https://api.renesis.fi/order-execution/orderbook/book?symbol=BTC/USDT" \
  -H "X-API-Key: $API_KEY"
# Response: best_bid on gateio > best_ask on bybit = buy bybit, sell gateio
```

### 3. Execution Quality Monitoring

```bash theme={null}
# Monitor update rates and staleness
curl "https://api.renesis.fi/order-execution/orderbook/quality?symbol=BTC/USDT" \
  -H "X-API-Key: $API_KEY"
# 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 Socket.IO endpoint:

```
wss://api.renesis.fi (path: /order-execution/socket.io)
```

See [Global Orderbook Module Websocket](/oems-api/api/orderbook-websocket) for the full streaming reference.

### 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           |

### Subscribe Parameters

| 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

```javascript theme={null}
// Connect
var socket = io('wss://api.renesis.fi', {
  transports: ['websocket'],
  path: '/order-execution/socket.io'
});

// 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:

```json theme={null}
{
  "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

```python theme={null}
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(
    'https://api.renesis.fi',
    socketio_path='/order-execution/socket.io',
    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