Execution

You never pass a symbol — the client already has one.

# market: split across your venues, cheapest first
order = await sory.place(side="buy", qty=Decimal("5"), order_type="market")

# limit: rests on one venue at your price
order = await sory.place(
    side="buy",
    qty=Decimal("5"),
    exchanges=["binance"],
    order_type="limit",
    price=Decimal("95000"),
)

What happens to your order

`order_type`	`exchanges`	What happens
`market`	omitted, or several	Split across them, cheapest first.
`market`	exactly one	All of it goes there.
`limit`	exactly one	Rests at your price on that venue.

A limit order is never split. Splitting one across venues is not one order at a price — it is several orders in several queues, which behaves differently and is not something SORY will do without you asking.

`place()`

Param	Type	Required	Example	Description
`side`	`"buy"` \| `"sell"`	yes	`"buy"`	Direction.
`qty`	`Decimal`	yes	`Decimal("5")`	How much, in the base currency.
`order_type`	`"limit"` \| `"market"`	no — `"limit"`	`"market"`
`price`	`Decimal`	for `limit`	`Decimal("95000")`	Rounded to the venue’s tick size.
`exchanges`	`list[str]`	for `limit`	`["binance"]`	Which venues. Omit on a market order to use all of them.
`dry_run`	`bool`	no — `False`	`True`	Build everything, send nothing. See below.

Returns an Order.

How long an order lives

A limit order rests until it is filled or cancelled. That is what every venue does when it is sent no time-in-force at all, so SORY sends none — there is no parameter, and nothing for a venue to disagree about. No stop orders, no trigger orders, no icebergs, no algos, no post-only, no IOC or FOK. Build those on top.

What you get back

A market order across several venues produces one child per venue. Everything else produces one.

order.filled           # how much filled, across all venues
order.remaining        # qty - filled
order.achieved_price   # what you actually paid, on average
order.children         # what was sent where
order.plan             # why it split that way (None when there was nothing to decide)

Field	Type	Description
`id`	`str`	SORY’s id for the parent order.
`symbol` `side` `order_type` `qty` `price`		Exactly what you asked for.
`children`	`list[VenueOrder]`	One per venue that got a slice.
`plan`	`RoutingPlan \| None`	See Routing.
`updates`	`dict[str, OrderUpdate]`	What each venue reported.
`dry_run`	`bool`	Whether anything actually left the process.
`filled` `remaining`	`Decimal`	Summed over children.
`expected_price` `achieved_price`	`Decimal`	Predicted, then actual.
`unfilled_reason`	`str \| None`	Why `remaining` is not zero.

Each VenueOrder has venue, symbol, side, order_type, amount, price, client_order_id and venue_order_id.

Knowing what happened to your order

Three ways, depending on what you are doing. The order object stays current. The Order you get back from place() updates itself as the venues report. You do not look it up again:

order = await sory.place(side="buy", qty=Decimal("5"), exchanges=["binance"],
                         order_type="limit", price=Decimal("95000"))

order.filled       # 0 now, 2 after a partial, 5 when it is done
order.remaining    # qty - filled

Or react to each report as it arrives, which is what you want if you are quoting:

async for update in sory.order_updates():
    if update.status == "closed":
        ...

Or ask the venues what is still working, which is the only thing that survives a restart:

for resting in await sory.open_orders():
    print(resting.venue, resting.id, resting.price, resting.remaining)

Or ask the venues about one order directly, when the stream has gone quiet and you need to know before you act:

await sory.confirm(order)    # fetches every child, files the answers against the order
order.filled                 # now the venues' own view, not the stream's

Method	Param	Type	Required	Example	Returns
`open_orders`	—			`await sory.open_orders()`	`list[OrderUpdate]` — everything resting on your venues for this symbol.
`order_updates`	—			`sory.order_updates()`	`AsyncIterator[OrderUpdate]` — every report, as it lands.
`confirm`	`order`	`Order`	yes	`await sory.confirm(order)`	The same `Order`, updated in place from the venues.

An order that has reported nothing has not necessarily done nothing. A venue can report a fill late, under an identifier it chose rather than the one SORY sent, or not at all. order.filled == 0 means nothing has been reported, which is a different claim from nothing happened.That difference costs money in both directions: re-sending the remainder of a hedge that already filled leaves you with a position twice over, and reading a silent fill as a miss leaves you unhedged while believing you are flat. Before you act on an absence — retrying, re-sending, giving up — confirm() it. A child that never reached a venue is skipped, and a venue that cannot answer leaves the order untouched rather than guessed at.

open_orders() asks the venues, so it sees everything working under the same API key — including orders left behind by a previous run of your process. SORY stores nothing on disk, so this is the whole recovery story.For just the orders this process sent, sory.store holds them: store.get(id), store.open_orders(), store.all(), store.open_count().

What the venue says back

async for update in sory.order_updates():
    update.venue, update.status, update.filled, update.average

OrderUpdate is the venue’s own report with the numbers converted to Decimal and the venue name attached. Nothing is computed from anything but the venue’s own numbers; raw holds the untouched payload. The one exception is average, which is filled in as cost / filled when the venue reported both and left the average out — as several do on a market order. That is the venue’s own cost over the venue’s own fill. Without it you would hold a fill you cannot price.

Field	Description
`venue`	Who said it.
`id`	The venue’s order id.
`client_order_id`	Ours, for matching against `order.children`.
`status`	`open`, `closed`, `canceled`, `rejected`, `expired`.
`symbol` `type` `side`	As the venue reports them.
`price` `average` `amount` `filled` `remaining` `cost`	`None` means the venue did not say — never zero.
`fee`	The venue’s own fee report.
`timestamp`	Venue time, ms.
`raw`	The untouched payload.

Cancelling

await sory.cancel(order.id)   # returns once every venue has confirmed
await sory.cancel_all()       # everything resting, every venue

Method	Param	Type	Required	Example	Description
`cancel`	`order_id`	`str`	yes	`order.id`	Cancels every child. Returns the `Order`.
`cancel_all`	—			`await sory.cancel_all()`	Pulls everything resting for your symbol.

Wait for the confirmation before you repost. A cancel that races a fill is how you end up filled twice, so cancel returns when the venues have answered — not when the requests went out.

State

In memory only. No file, no database. After a restart, ask the venues what is resting — that is the whole recovery story.

Testing safely

order = await sory.place(
    side="buy", qty=Decimal("2"), order_type="market", dry_run=True,
)

Everything runs — routing, rounding, building each venue order — and nothing is sent. It is what catches “this slice is too small for kraken” before a live run does. The order comes back exactly as it would have gone out: order.plan shows the split and why, and order.children holds the venue orders, already rounded. It is one flag on the call you were going to make anyway, so the rehearsal and the real thing cannot drift apart.

Start here

Core concepts

Going further

What happens to your order

`place()`

How long an order lives

What you get back

Knowing what happened to your order

What the venue says back

Cancelling

State

Testing safely

​What happens to your order

​place()

​How long an order lives

​What you get back

​Knowing what happened to your order

​What the venue says back

​Cancelling

​State

​Testing safely

What happens to your order

`place()`

How long an order lives

What you get back

Knowing what happened to your order

What the venue says back

Cancelling

State

Testing safely