The Bjarkan SOR SDK uses two main configurations: Orderbook Configuration and Trades Configuration. These configurations define the exchanges, trading pairs, and other essential parameters for your trading activities.

​
Setting Configurations

You configure the SDK using the set_config method:

await sdk.set_config(
    type="orderbook",  # or "trades"
    # Configuration parameters specific to the type
    **config_params
)

This method returns a dictionary with the status and a message:

{"status": "success", "message": "Orderbook configuration set"}

​
Orderbook Configuration

The orderbook configuration defines parameters for fetching and processing orderbook data.

​
Orderbook Config Parameters

ParameterTypeRequiredDefaultDescription
aggregatedboolNoFalseWhether to aggregate orderbooks across exchanges
exchangesList[str]Yes-List of exchange IDs to connect to
sandbox_modeDict[str, bool]No{}Dictionary of exchange IDs to sandbox mode flags
symbolsList[str]Yes-List of symbols to monitor
depthintYes-Number of price levels to include
fees_bpsDict[str, Union[float, Dict[str, float]]]NoNoneExchange fee rates in basis points
weightingDict[str, Dict[str, float]]NoNoneVWAP weighting configuration
groupDict[str, str]NoNoneSymbol grouping configuration

​
Example Orderbook Config

await sdk.set_config(
    type="orderbook",
    aggregated=True,
    exchanges=["binance", "okx", "kraken"],
    sandbox_mode={"binance": True},
    symbols=["BTC/USDT", "ETH/USDT"],
    depth=20,
    fees_bps={
        "binance": 9.8,
        "okx": {"BTC/USDT": 7, "ETH/USDT": 8},
        "kraken": 10.1
    },
    weighting={
        "BTC/USDT": {"BTC": 1},
        "ETH/USDT": {"USDT": 10000}
    },
    group={"BTC/USDT": "BTC/USDC"}
)

​
Fee-Aware Orderbooks

The fees_bps parameter allows you to account for exchange fees in orderbook prices. This is essential for accurate cross-exchange price comparisons and arbitrage detection.

Fees are specified in basis points (1 bp = 0.01%). You can set:

  • A single fee for all symbols on an exchange: "binance": 9.8
  • Different fees per symbol: "okx": {"BTC/USDT": 7, "ETH/USDT": 8}

The SDK 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 parameter is omitted, no fee adjustments will be applied.

​
Symbol Grouping

The group parameter allows you to treat different but related symbols as equivalent. This is useful for stablecoins or similar assets where you want to combine liquidity.

"group": {"BTC/USDT": "BTC/USDC"}  # Treat USDT and USDC markets as equivalent

This will combine orderbooks for BTC/USDT and BTC/USDC into a single view.

​
VWAP Weighting

The weighting parameter enables Volume Weighted Average Price (VWAP) calculations. This calculates what price you would pay/receive when executing a specific order size, accounting for slippage.

"weighting": {
    "BTC/USDT": {"BTC": 1},  # Calculate VWAP for 1 BTC
    "ETH/USDT": {"USDT": 10000}  # Calculate VWAP for $10,000 worth of ETH
}

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.

​
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

​
Trades Configuration

The trades configuration defines parameters for streaming real-time trade data.

​
Trades Config Parameters

ParameterTypeRequiredDefaultDescription
exchangesList[str]Yes-List of exchange IDs to connect to
sandbox_modeDict[str, bool]No{}Dictionary of exchange IDs to sandbox mode flags
symbolsList[str]Yes-List of symbols to monitor
fees_bpsDict[str, Union[float, Dict[str, float]]]NoNoneExchange fee rates in basis points
sizeDict[str, Dict[str, float]]NoNoneMinimum trade size filters

​
Example Trades Config

await sdk.set_config(
    type="trades",
    exchanges=["binance", "okx", "kraken"],
    sandbox_mode={"binance": True},
    symbols=["BTC/USDT", "ETH/USDT"],
    fees_bps={
        "binance": 9.8,
        "okx": {"BTC/USDT": 7, "ETH/USDT": 8},
        "kraken": 10.1
    },
    size={
        "BTC/USDT": {"BTC": 0.1},  # Only trades ≥ 0.1 BTC
        "ETH/USDT": {"USDT": 10000}  # Only trades ≥ $10,000
    }
)

​
Trade Size Filtering

The size parameter allows you to filter trades by minimum size. This is particularly useful for:

  • Reducing noise from small trades
  • Focusing on institutional/whale activity
  • Monitoring significant market moves
  • Reducing processing overhead

You can specify minimum sizes in two ways:

  • Base currency: "BTC/USDT": {"BTC": 0.1} (only trades ≥ 0.1 BTC)
  • Quote currency: "ETH/USDT": {"USDT": 10000} (only trades with value ≥ $10,000)

​
Sandbox Mode

For testing without using real funds, you can enable sandbox/testnet mode for specific exchanges:

"sandbox_mode": {
    "binance": True,
    "bybit": True
}

This setting applies to both orderbook data collection and order execution. Make sure your API keys are configured for the respective exchange testnet environments when using sandbox mode.

​
Starting and Stopping Streams

After setting your configurations, you need to explicitly start the data streams:

# Define a callback function
async def process_data(data):
    print(f"Received data: {data}")

# Start the stream
await sdk.start_stream("orderbook", callback=process_data)  # or "trades"

To stop a running stream:

await sdk.stop_stream("orderbook")  # or "trades"

​
Important Notes

  1. The SDK will validate the configurations when you call set_config()
  2. For order execution, the orderbook configuration must have aggregated=True and contain only one symbol
  3. You must start the orderbook stream before attempting to execute orders
  4. When using both orderbook and trades configurations, you need to call set_config() for each type
  5. If you need different configurations for the same type, you should create separate SDK instances

By properly configuring the Bjarkan SOR SDK, you can customize its behavior to suit your specific trading strategies and requirements. The flexibility of the configuration system allows you to fine-tune data collection, filtering, and execution parameters across multiple exchanges.