Configuration

Configuration is validated on construction, so mistakes surface with a message naming the field — not at 3am against a live book.

config = {
    "market_data": {
        "exchanges": ["binance", "okx", "bybit"],
        "symbols": ["BTC/USDT"],
        "aggregated": True,
        "depth": 20,
    },
    "fees_bps": "fees.toml",
}

Top level

Field	Type	Default	Meaning
`market_data`	object	required	What to subscribe to, and how to shape the book.
`fees_bps`	path or mapping	required	Your fee schedule.
`dry_run`	`bool`	`False`	Run every path without sending.
`max_order_notional`	`Decimal`	off	Optional cap.
`max_open_orders`	`int`	off	Optional cap.

Market data

Field	Type	Default	Meaning
`exchanges`	`list[str]`	required	Venue ids — see Venues.
`symbols`	`list[str]`	required	e.g. `BTC/USDT`. See Symbols.
`aggregated`	`bool`	`False`	Merge venues into one book.
`depth`	`int`	`10`	Levels in the emitted book.
`size_buckets`	`dict[str, list]`	—	VWAP to fill N base units.
`amount_buckets`	`dict[str, list]`	—	VWAP to fill N quote units.
`group`	`dict[str, list]`	—	Pool several symbols into one book.
`emit_interval_ms`	`int`	`100`	How often callbacks fire.
`stale_after_ms`	`int`	`2000`	Silence beyond this excludes the venue.
`resolve_crossed`	`bool`	`True`	Net off crossed levels before routing.

depth is how many levels are emitted to you. The book routing walks keeps every level from every venue, so a large order is allocated against all available liquidity rather than a truncated view of it.

Credentials

From the environment, with the venue id upper-cased:

SORY_BINANCE_API_KEY=...
SORY_BINANCE_API_SECRET=...
SORY_BINANCE_API_PASSWORD=...   # only where the venue uses one

Or pass them directly:

from sory import Credentials

SoryClient(config=config, credentials={
    "binance": Credentials(api_key="...", secret="..."),
})

Market data needs no credentials on most venues. A few authenticate their book feed too — those report Offline with that reason until you supply keys.

Pooling equivalent pairs

BTC/USD, BTC/USDC and BTC/USDT are different instruments but often interchangeable. Group them and their liquidity pools into one book:

group = {"BTC": ["BTC/USD", "BTC/USDC", "BTC/USDT"]}

Routing to BTC can then send BTC/USD on one venue and BTC/USDT on another — each allocation carries the instrument it will actually trade.

Grouping assumes those quote currencies are interchangeable at par. Stating the group explicitly is what keeps that assumption visible instead of buried.

Bucketing

Exactly one mode per book. depth is the default; naming a book under size_buckets or amount_buckets switches it to VWAP mode. Naming it under both is a configuration error.

Start here

Core concepts

Configuration

Top level

Market data

Credentials

Pooling equivalent pairs

Bucketing

​Top level

​Market data

​Credentials

​Pooling equivalent pairs

​Bucketing

Top level

Market data

Credentials

Pooling equivalent pairs

Bucketing