The Bjarkan SOR API provides access to real-time market data across multiple exchanges. This includes both orderbook data and trade data. You can choose between aggregated orderbook data across all exchanges or separate data for each exchange and symbol. Live market data is crucial for making informed trading decisions and is used by the smart order router for order execution.

​
Starting and Stopping Data Streams

Before you can receive market data, you need to start the appropriate data stream:

  • To start a stream: POST /start_stream?stream_type=orderbook or POST /start_stream?stream_type=trades
  • To stop a stream: POST /stop_stream?stream_type=orderbook or POST /stop_stream?stream_type=trades

Make sure you have set the appropriate configuration (orderbook or trades) before starting a stream.

​
Fetching Real-time Order Book Updates

Once you’ve started the orderbook stream, you can connect to the WebSocket endpoint wss://api.bjarkan.io/connect_stream?type=orderbook to receive continuous order book updates.

​
Fetching the Latest Order Book Snapshot

Use the GET /get_latest_orderbook endpoint to fetch the latest order book data. The structure of the response will depend on your aggregated setting in the orderbook configuration.

​
Fetching Real-time Trade Updates

After starting the trades stream, connect to the WebSocket endpoint wss://api.bjarkan.io/connect_stream?type=trades to receive a continuous stream of trade data from the configured exchanges and symbols.

​
Order Book Structure

​
Aggregated Order Book

When aggregated is set to True in your orderbook configuration, the order book will have the following structure:

{
  "BTC/USDT": {
    "timestamp": 1726247582931,
    "exchange_timestamp": 1726247582921,
    "symbol": "BTC/USDT",
    "bids": [
      [59463.14222635, 0.016, "kraken"],
      [59462.8264301, 9.87259, "binance"],
      // ... more bid entries
    ],
    "asks": [
      [59579.4406878, 1.31557, "htx"],
      [59579.580825, 0.00022, "okx"],
      // ... more ask entries
    ],
    "hash": "e897338a5fe11c181db3c70f40d31a44"
  },
  // ... potentially more symbols
}

​
Non-Aggregated Order Book

When aggregated is set to False, the order book will be structured as follows:

{
  "binance": {
    "BTC/USDT": {
      "timestamp": 1726245985929,
      "exchange_timestamp": 1726245985919,
      "symbol": "BTC/USDT",
      "bids": [
        [59300.01598434, 0.49403, "binance"],
        [59300.00599413, 0.00136, "binance"],
        [59299.95604308, 0.00037, "binance"]
      ],
      "asks": [
        [59416.3109772, 5.63609, "binance"],
        [59416.320987, 0.115, "binance"],
        [59416.3510164, 0.00047, "binance"]
      ],
      "hash": "4933178dbb7defa1aedb7cadb6bf6351"
    },
    "ETH/USDT": {
      // Similar structure as BTC/USDT
    }
  },
  // ... and however many exchanges more
}

For each symbol (in aggregated mode) or each exchange and symbol (in non-aggregated mode):

  • timestamp: The Unix timestamp when the orderbook was processed by our system.
  • exchange_timestamp: The Unix timestamp when the orderbook was created by the exchange.
  • symbol: The trading pair symbol (e.g., “BTC/USDT”).
  • bids/asks: Buy/sell orders, represented as [price, quantity, exchange].
  • hash: A unique identifier for the current state of the order book.

The bids and asks are sorted by price (descending for bids, ascending for asks), representing the best available prices.

​
Trade Data Structure

The trade data structure is as follows:

{
  "binance": {
    "BTC/USDT": [
      {
        "id": "12345",
        "exchange_timestamp": 1726247582921,
        "timestamp": 1726247582921000,
        "price": 59463.14,
        "amount": 0.1,
        "side": "buy"
      },
      // ... more trades
    ],
    // ... more symbols
  },
  // ... more exchanges
}

For each trade:

  • id: A unique identifier for the trade.
  • exchange_timestamp: The timestamp of the trade as reported by the exchange.
  • timestamp: The timestamp when the trade was processed by our system.
  • price: The price at which the trade occurred.
  • amount: The amount of the base asset traded.
  • side: The side of the trade (“buy” or “sell”).

​
Understanding Fee-Aware Orderbooks & Trades

The Bjarkan SOR API provides fee-aware orderbooks and trades, which incorporate exchange fees directly into the prices. This feature offers several advantages:

  1. True Arbitrage Detection: By including fees in the prices, you can identify genuine arbitrage opportunities across exchanges.
  2. Accurate Market Quoting: When using this data to quote markets yourself, you’re working with prices that already account for exchange fees.
  3. Realistic Price Comparisons: The fee-adjusted prices allow for a more accurate picture of an aggregated order book and trades across different exchanges.
  4. Order Routing: When smart order routing, you can make more informed decisions about which exchange to route orders to, based on the fee-adjusted prices.

​
How It Works

When you set up your configurations, you can specify fees for each exchange in basis points (bps). The API then applies these fees to the data, adjusting the prices accordingly.

Fees are specified in the fees_bps field of the configurations. You can set a single fee for an exchange or different fees per symbol:

{
  "fees_bps": {
    "binance": 9.8,
    "okx": {"BTC/USDT": 7, "ETH/USDT": 8},
    "kraken": 10.1
  }
}

In this example:

  • Binance has a fee of 0.098% (9.8 bps) for all symbols
  • OKX has a fee of 0.07% (7 bps) for BTC/USDT and 0.08% (8 bps) for ETH/USDT
  • Kraken has a fee of 0.101% (10.1 bps) for all symbols

The API applies these fees to the orderbook data as follows:

  • For buy orders (bids), the fee-adjusted price is decreased: adjusted_price = original_price / (1 + fee)
  • For sell orders (asks), the fee-adjusted price is increased: adjusted_price = original_price * (1 + fee)

If the fees_bps field in the orderbook configuration is an empty dictionary, the system will assume zero fees for all exchanges and symbols. This means no fee adjustments will be applied to the orderbook prices.

​
Volume Weighted Average Price (VWAP)

When VWAP is enabled in the orderbook configuration ("vwap": true), the API calculates and uses Volume Weighted Average Prices for the orderbook data.

​
VWAP Configuration

VWAP is configured using the weighting field in the orderbook configuration:

{
  "vwap": true,
  "weighting": {
    "BTC/USDT": {"BTC": 1},
    "ETH/USDT": {"USDT": 10000}
  }
}

In this example, VWAP is calculated for a target amount of 1 BTC for BTC/USDT and 10,000 USDT for ETH/USDT.

​
VWAP Calculation

The VWAP is calculated by taking the sum of the price times the volume for each order up to the specified target amount, then dividing by the total volume. This provides a more accurate representation of the average price you would expect to pay (or receive) when executing a large order.

When VWAP is enabled, the orderbook data will reflect these calculated average prices instead of individual order prices.

​
VWAP Calculation Example

Let’s consider a simplified order book for BTC/USDT with a target of 1 BTC:

Raw Binance Order Book:
  Bids:
    57,900 - 0.5 BTC
    57,800 - 0.4 BTC
    57,600 - 0.3 BTC

Raw Coinbase Order Book:
  Bids:
    57,700 - 0.7 BTC
    57,500 - 0.8 BTC

The VWAP calculation for each exchange would be:

  1. Binance VWAP (1 BTC target):

    • Use 0.5 BTC at 57,900
    • Use 0.4 BTC at 57,800
    • Use 0.1 BTC at 57,600 VWAP = (57900 * 0.5 + 57800 * 0.4 + 57600 * 0.1) / 1 = 57,830

  2. Coinbase VWAP (1 BTC target):

    • Use 0.7 BTC at 57,700
    • Use 0.3 BTC at 57,500 VWAP = (57700 * 0.7 + 57500 * 0.3) / 1 = 57,640

The resulting VWAP orderbook would look like:

[57,830, 1, 'binance']
[57,640, 1, 'coinbase']
[57,600, 0.2, 'binance']   # Remaining volume after VWAP calculation
[57,500, 0.5, 'coinbase']  # Remaining volume after VWAP calculation

This VWAP calculation provides a more accurate representation of the average price for larger orders, helping to make more informed trading decisions.

​
Session Management

Your configurations and stream states are tied to your session. If your session expires due to inactivity (1 hour without any API calls or active WebSocket connections), your streams will be automatically stopped, and you’ll need to log in again and restart your streams.

By leveraging the market data capabilities of the Bjarkan SOR API, including fee-aware orderbooks and VWAP calculations, you can make more informed trading decisions and fully utilize the smart order routing features for optimal trade execution.