Market data

book = sory.book()

book.best_bid.price     # best price to sell into
book.best_ask.venue     # who is offering it
book.venues             # who is in this book
book.excluded           # {venue: why it is not}

Every level knows which venue it came from, so you always know where the liquidity is.

Methods

Method	Param	Type	Required	Example	Returns
`book`	—			`sory.book()`	`Book \| None` — the latest book, or `None` if no venue has sent one yet.
`health`	—			`sory.health()`	`dict[str, Health]` — per-venue status.
`on_book`	`callback`	`async (Book) -> None`	yes	`sory.on_book(fn)`	`None`. Fires every `throttle_ms`.
`trades`	`venue`	`str`	no — all venues	`sory.trades("okx")`	`list[Trade]`.
`on_trade`	`callback`	`async (Trade) -> None`	yes	`sory.on_trade(fn)`	`None`.
`start`	—			`await sory.start()`	`None`. Only needed outside `async with`.
`close`	—			`await sory.close()`	`None`. Closes everything.

What a `Book` holds

Field	Type	Description
`symbol`	`str`	What you configured.
`bids` `asks`	`tuple[Level, ...]`	Best price first, up to `depth`.
`venues`	`tuple[str, ...]`	Who is contributing.
`excluded`	`dict[str, str]`	Everyone who is not, and why.
`all_in`	`bool`	Whether fees are included in these prices.
`crossed`	`bool`	Whether a bid was above an ask.
`timestamp`	`int`	When SORY built it, ms.
`venue_timestamp`	`int \| None`	Newest venue timestamp in it, ms.
`best_bid` `best_ask`	`Level \| None`	Top of book.

A Level is price, amount, venue and symbol. A Trade is venue, symbol, id, side, price, amount, timestamp.

Venue health

Status	Meaning
`Online`	sending updates
`Stale`	connected, but silent for longer than `stale_ms`
`Offline`	disconnected, or does not list the symbol

sory.health()   # {'binance': Health.ONLINE, 'okx': Health.STALE}

Only Online venues appear in the book or receive orders. Silence is treated as a fault, not as a quiet market — a feed that stops publishing without disconnecting is what fills an order far from where you expected. Dropped connections come back on their own, with a log line when a venue leaves and one when it returns.

Streaming

async def on_book(book):
    ...

sory.on_book(on_book)

Called every throttle_ms — 100ms by default. One slow handler cannot hold up another.

Average price to fill a size

Ask for the price to fill 1, 5 or 10 units and you get the average you would pay, plus the worst price you would have to accept. The gap between them is your slippage.

config = {"symbol": "BTC/USDT", "size_buckets": [1, 5, 10]}

for level in sory.book().asks:
    print(level.target, level.amount, level.price, level.limit_price)
# 1   1   100.00   100.00
# 5   5   101.20   103.50   <- 230 bps of slippage to fill 5

Each one is measured from the top of the book independently — [1, 5, 10] means “to fill 1”, “to fill 5”, “to fill 10”, not three slices in a row.

Field	Meaning
`target`	what you asked for
`amount`	what that buys — the same as `target` under `size_buckets`, in base units under `amount_buckets`
`price`	the VWAP you would average across the sweep
`limit_price`	the worst price the sweep had to reach for the whole size to fill
`venue`	always `"aggregated"` — a bucket is filled from however many venues it took

Use amount_buckets instead to measure in quote currency. Then target is a notional and amount is the base size it buys, which is why both are reported:

config = {"symbol": "BTC/USDT", "amount_buckets": [50_000, 100_000]}
# target 50000  ->  amount 0.7665 BTC  @ VWAP 65,216.94

These are a read-only view of the book. Routing never uses them — a market order is always allocated against the full per-venue book, because filling an order means knowing which venue each unit sits on, and a bucket has deliberately forgotten that. Bucketing changes what sory.book() shows you, never what place() does.

If the book cannot fill a size, that entry is left out rather than reported short. There is no average price for a fill that cannot happen.

Average price to fill a size, on some of your venues

size_buckets prices a sweep across every venue in the book. Sometimes the venues you would actually trade are a subset of that — and the difference is not small.

book = sory.book()

book.vwap(Decimal("5"), "sell")                         # what selling 5 would net
book.vwap(Decimal("5"), "sell", exclude=["kraken"])     # ...without kraken

side is what you would do, the same as in place(): "sell" walks the bids, "buy" walks the asks. You get back a Level shaped exactly like a bucket — price is the VWAP, limit_price the worst price the sweep reaches, target what you asked for — or None when what is left cannot fill the size.

Param	Type	Required	Example	Description
`qty`	`Decimal`	yes	`Decimal("5")`	The size to fill, in base units.
`side`	`"buy"` \| `"sell"`	yes	`"sell"`	What you would do. `"sell"` walks the bids.
`exclude`	`list[str]`	no	`["kraken"]`	Venues to leave out of the walk.

Why exclude exists. A market maker quoting on one venue and hedging on the others cannot price its quote off the whole book. The venue it is quoting on is excluded from the hedge — and it is frequently the best price in the book, because the cheapest taker fees float to the top of a fee-adjusted one. Pricing against liquidity you will never touch flatters your edge by exactly the amount that venue was better by, every time, in the same direction.size_buckets cannot answer this: it pools every venue into one number that cannot be taken apart afterwards.

Crossed books

When you merge venues, a bid on one can sit above an ask on another — especially once fees move prices around. book.crossed tells you when that happened. Set resolve_crossed: True and the overlap is trimmed out before you see it.

Trades

Set trades: True and the public tape streams alongside the book, from every venue you subscribe to.

config = {"symbol": "BTC/USDT", "exchanges": ["binance", "okx"], "trades": True}

async with SoryClient(config) as sory:
    sory.on_trade(handler)
    sory.trades()        # every venue, oldest first
    sory.trades("okx")   # just one

Reading does not clear the buffer, so two consumers can both use it. Trade prices are always the venue’s own, never adjusted by your fees — you did not pay a fee on someone else’s trade.

Start here

Core concepts

Going further

Market data

Methods

What a `Book` holds

Venue health

Streaming

Average price to fill a size

Average price to fill a size, on some of your venues

Crossed books

Trades

​Methods

​What a Book holds

​Venue health

​Streaming

​Average price to fill a size

​Average price to fill a size, on some of your venues

​Crossed books

​Trades

Methods

What a `Book` holds

Venue health

Streaming

Average price to fill a size

Average price to fill a size, on some of your venues

Crossed books

Trades