> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sory.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Every option, in two tables.

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

```python theme={"dark"}
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](/fees).                      |
| `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](/venues).        |
| `symbols`          | `list[str]`       | required | e.g. `BTC/USDT`. See [Symbols](/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.    |

<Note>
  `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.
</Note>

## Credentials

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

```bash theme={"dark"}
SORY_BINANCE_API_KEY=...
SORY_BINANCE_API_SECRET=...
SORY_BINANCE_API_PASSWORD=...   # only where the venue uses one
```

Or pass them directly:

```python theme={"dark"}
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:

```python theme={"dark"}
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.

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

## Bucketing

Exactly one mode per book. `depth` is the default; naming a book under `size_buckets` or `amount_buckets` switches it to [VWAP mode](/market-data#vwap-depth). Naming it under both is a configuration error.