Configuration

Two lines is a working config. Everything else has a sensible default.

config = {"symbol": "BTC/USDT", "licence_key": "..."}

It is validated when the client is built, so a mistake shows up immediately with the field named — not at 3am against a live book.

Options

Param	Type	Required	Example	Description
`symbol`	`str`	yes	`"BTC/USDT"`	What to trade. Upper-cased for you. See Symbols.
`licence_key`	`str`	yes, or `SORY_LICENCE_KEY`	`"..."`	See Licensing.
`exchanges`	`list[str]`	no — all that list it	`["binance", "okx"]`	Venue ids, lower-cased for you. See Venues.
`depth`	`int`	no — `10`	`50`	How many price levels you get back.
`fees_bps`	path or mapping	no	`"fees.toml"`	Your fee rates. See Fees.
`fee_offset`	`dict[str, str]`	no — none applied	`{"binance": "taker"}`	Which venues to apply fees to: `"maker"` or `"taker"`.
`credentials`	`dict[str, Credentials]`	no — read from env	`{"binance": Credentials(...)}`	Needed only to send orders.
`trades`	`bool`	no — `False`	`True`	Also stream the public trade tape.
`resolve_crossed`	`bool`	no — `False`	`True`	Trim overlapping bids and asks out of the book.
`throttle_ms`	`int`	no — `100`	`250`	How often the book updates.
`stale_ms`	`int`	no — `2000`	`500`	Silence longer than this and the venue drops out.
`size_buckets`	`list[Decimal]`	no	`[1, 5, 10]`	Average price to fill 1, 5, 10 units.
`amount_buckets`	`list[Decimal]`	no	`[100000]`	Same, measured in quote currency.
`group_liquidity`	`list[str]`	no	`["BTC/USD", "BTC/USDT"]`	Treat several pairs as one book.
`log_dir`	`str`	no	`"./logs"`	Where to write the log.

The client takes exactly one argument:

Param	Type	Required	Example	Description
`config`	`dict` or `SoryConfig`	yes	`{"symbol": "BTC/USDT"}`	Everything above.

One symbol per client

A client streams one symbol. That is why book() takes no argument — there is only one book to ask for. Trading several symbols means several clients, which is one line each:

base = {"licence_key": "...", "fees_bps": "fees.toml"}

btc = SoryClient({**base, "symbol": "BTC/USDT"})
eth = SoryClient({**base, "symbol": "ETH/USDT"})

Each one runs on its own, with its own venues, depth and fees. Nothing is shared, so nothing surprises you.

One venue or many

The length of exchanges decides whether there is anything to merge:

{"symbol": "BTC/USDT", "exchanges": ["binance"]}                       # one venue's book
{"symbol": "BTC/USDT", "exchanges": ["binance", "okx", "kraken"]}      # merged
{"symbol": "BTC/USDT"}                                                # every venue that has it

Credentials

Market data is public on most venues, so you only need keys to send orders. SORY reads them 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 in:

from sory import Credentials

SoryClient({
    "symbol": "BTC/USDT",
    "credentials": {"binance": Credentials(api_key="...", secret="...")},
})

A venue with no keys still contributes to the book — it just cannot receive orders, and says so.

Treating several pairs as one book

BTC/USD, BTC/USDC and BTC/USDT are different instruments but often interchangeable. Pool them:

config = {
    "symbol": "BTC",
    "group_liquidity": ["BTC/USD", "BTC/USDC", "BTC/USDT"],
}

An order can then fill BTC/USD on one venue and BTC/USDT on another. Each slice knows which instrument it is.

This assumes those quote currencies are worth the same. Writing the list out is what keeps that assumption visible.

Start here

Core concepts

Going further

Configuration

Options

One symbol per client

One venue or many

Credentials

Treating several pairs as one book

​Options

​One symbol per client

​One venue or many

​Credentials

​Treating several pairs as one book

Options

One symbol per client

One venue or many

Credentials

Treating several pairs as one book