Что это

brokapi - единый интерфейс к торговым API. Один и тот же код бота работает с любым брокером. Начинаем с API брокеров российского рынка: БКС, Т-Банк, Финам и АЛОР, есть также технический коннектор к API Bybit (страница). Дальше другие брокеры и биржевые протоколы под тот же интерфейс.

Для ИИ-агентов: llms.txt / llms-full.txt. Для тех, что пишут на Python: python/llms.txt

Стадия: открытая альфа. Интерфейс до беты может меняться. Перед первой заявкой на настоящем счете: Перед боевым счетом.

Выберите путь

В книге одна общая часть (как устроено, брокеры, ошибки, события) и у каждого продукта свой раздел. Общее написано один раз и верно для любого пути. Работают Rust, Python и Gateway (все в альфе).

Что общее у всех путей

• Переводчик. Бот говорит на одном языке (заявка, стакан, событие) со всеми брокерами. Разница протоколов (REST, WebSocket, gRPC) спрятана внутри. Сменить брокера - поменять коннектор, код бота почти не меняется.
• Предохранитель. Главная задача библиотеки - чтобы бот никогда не поставил заявку дважды и не торговал вслепую. Поэтому команда без ответа не повторяется, а торговля закрывается, когда данные о своих заявках могли потеряться.
• Без памяти. Между запусками библиотека ничего не хранит. Журнал заявок ведет бот, библиотека дает номер cid в каждом событии заявки и сверку со счетом.

Книга устроена так: сначала общая часть (как устроено, брокеры), затем разделы продуктов со своим быстрым стартом и инструкциями, в конце справочник. Код на общих страницах дан вкладками Rust и Python там, где он есть.

Что умеет

Из чего состоит

У каждого брокера два коннектора: MD (рыночные данные, один на брокера) и UD (заявки, свои сделки, портфель, один на счет). Как они связаны с ботом, с лимитами и между собой, показывает Карта.

Общие трейты (OrderBookSource, OrderExecutor, StopOrderExecutor и другие) закрывают то, что умеют все брокеры. Бот, написанный на них, работает с любым брокером. Все остальное, что есть у брокера (купоны, отчеты, избранное, новые методы), доступно через метод raw() каждого коннектора: raw. Сколько методов брокера закрыто общим интерфейсом, а сколько только raw(): Покрытие API.

Три правила, на которых все держится

1. cid придумывает бот и записывает у себя до отправки. Это единственная нить, по которой можно спросить брокера о заявке без ответа. Если номер выдает библиотека, он теряется вместе с ответом, и после падения бот не знает, что за заявка могла встать. Подробно: Круг команд.
2. Команда без ответа не повторяется. Unknown выясняется у брокера, новая попытка идет с новым cid. Заявка без ответа могла встать, и повтор дал бы две заявки на счете. Что делать вместо повтора: Если что-то пошло не так.
3. Торговля только после сверки. После старта, после перегрузки, при сомнении. Пока бот не знает, какие заявки уже стоят у брокера, новая команда может задвоить заявку или спорить с той, которую бот не видит. Подробно: Круг жизни.

Чего библиотека не делает

• Не придумывает номер заявки. cid создает бот, по нему он узнает свою заявку после рестарта.
• Не повторяет команды. Заявка, на которую не пришел ответ, не отправляется второй раз. Ни при каких условиях.
• Не хранит состояние на диске. Журнал своих заявок ведет бот.
• Не собирает общий портфель по счетам и не выбирает счет для заявки. Это слой над коннекторами.
• Не трогает чужие заявки. Заявки, поставленные руками или другим роботом, она только показывает.
• Не снимает заявки при остановке. Заявка на бирже переживает процесс бота.

С чего начать

• Хочу запустить: сначала Установка, потом Быстрый старт на Rust или на Python.
• Пишу бота (сам или с ИИ-агентом): сначала Контракт для агентов, затем инструкция по задаче: торговый бот (Rust, Python), несколько брокеров и счетов (Rust, Python), исследовательский движок, история свечей на Python.
• Несколько ботов на одном счете или бот не на Rust и Python: Gateway, затем быстрый старт.
• Хочу понять устройство: Карта, затем три круга: события, команды, жизнь коннектора.
• Что делать при старте, рестарте и остановке бота: Запуск, рестарт и остановка.
• Пришла ошибка или странное состояние: Ошибки и что с ними делать.
• Особенности конкретного брокера: Брокеры.
• Хочу поставить заявку на настоящем счете: сначала Перед боевым счетом.
• Нужен метод, тип или ошибка до последнего поля: Справочник API Rust (rustdoc, лежит рядом с книгой в api/) или Python.
• Что появилось нового: Изменения.

Установка

Как получить библиотеку и убедиться, что она встала. Это первый шаг обоих быстрых стартов: Rust, Python.

Открытая альфа: интерфейс до беты может меняться. Перед первой заявкой на счете прочитайте Перед боевым счетом. Код открыт: https://github.com/runinfra/brokapi. Ниже в каждом разделе команда для пакета и для самой свежей версии из репозитория.

Что понадобится

Брокеры включаются флагами, как у tokio: bcs, tbank, finam, alor, bybit, можно несколько. В Python все брокеры уже в пакете.

Rust

Флаг выбирает брокера, здесь БКС:

cargo add brokapi --features bcs

Самая свежая версия, из репозитория:

cargo add --git https://github.com/runinfra/brokapi brokapi --features bcs

Обе команды добавляют зависимость в Cargo.toml. Для программ из быстрого старта нужны еще tokio и dotenvy:

cargo add tokio --features full
cargo add dotenvy

Из клона репозитория (без доступа в сеть к GitHub во время сборки, например на закрытой машине):

[dependencies]
brokapi = { path = "../brokapi", features = ["bcs"] }

Проверка: cargo build собирает проект без ошибок (первая сборка занимает несколько минут: компилируются зависимости). В коде все лежит под brokapi::: общее в brokapi::core и brokapi::runtime, брокеры в brokapi::bcs, brokapi::tbank, brokapi::finam, brokapi::alor, brokapi::bybit. Дальше: быстрый старт на Rust.

Python

Готовые пакеты есть для Linux (x86_64 и aarch64), macOS (Intel и Apple silicon) и Windows, на остальных системах pip соберет расширение сам (нужен Rust):

python -m venv .venv && . .venv/bin/activate
pip install brokapi

Самая свежая версия, из репозитория (нужен Rust: расширение собирается при установке, это несколько минут):

python -m venv .venv && . .venv/bin/activate
pip install "git+https://github.com/runinfra/brokapi#subdirectory=crates/python"

Из клона репозитория: pip install ./crates/python.

pip install brokapi дает только библиотеку для Python. Команды brokapi (служба Gateway, brokapi check, brokapi cancel-all) после него нет: программа ставится отдельно, см. Программа brokapi (Gateway) ниже. Имя brokapi одно у библиотеки на Rust, пакета для Python и программы.

Проверка:

python -c "import brokapi; print(brokapi.__version__)"

Должен напечататься номер версии. Не напечатала: смотрите таблицу ниже. Дальше: быстрый старт на Python.

Если что-то пошло не так

Программа brokapi (Gateway)

Gateway - это программа brokapi: служба и команды в одном бинарнике (что это). Ставится готовым файлом (Rust не нужен) или через cargo install.

Готовый файл

Файлы лежат на странице выпусков, в выпуске v0.1.0-alpha.5 и в каждом следующем. В выпуске пять архивов и файл с суммами SHA256SUMS:

Файлы для Linux статические: им не нужна определенная версия glibc, они запускаются на Debian, Ubuntu, RHEL, Alpine и в пустом контейнере. Файл для Windows не просит установить Visual C++. Файлы не подписаны сертификатом разработчика, поэтому macOS и Windows могут предупредить о неизвестном издателе: сверьте сумму (ниже) и подтвердите запуск.

Linux и macOS, на примере Linux x86_64 (для другой системы замените имя архива):

V=0.1.0-alpha.5
F=brokapi-$V-linux-x86_64.tar.gz
curl -fLO https://github.com/runinfra/brokapi/releases/download/v$V/$F
curl -fLO https://github.com/runinfra/brokapi/releases/download/v$V/SHA256SUMS
grep "$F" SHA256SUMS | sha256sum -c -        # на macOS: shasum -a 256 -c -
tar -xzf $F
mkdir -p ~/.local/bin && cp brokapi-$V-linux-x86_64/brokapi ~/.local/bin/

Последняя команда кладет программу в ~/.local/bin: этот каталог должен быть в PATH (можно любой другой каталог из PATH). Строка с sha256sum должна ответить OK. Если на macOS браузер скачал архив сам и система не дает запустить brokapi, снимите пометку скачанного файла: xattr -d com.apple.quarantine ~/.local/bin/brokapi. Через curl пометки нет.

Windows, PowerShell:

$V = "0.1.0-alpha.5"
$F = "brokapi-$V-windows-x86_64.zip"
curl.exe -fLO "https://github.com/runinfra/brokapi/releases/download/v$V/$F"
curl.exe -fLO "https://github.com/runinfra/brokapi/releases/download/v$V/SHA256SUMS"
(Get-FileHash $F -Algorithm SHA256).Hash.ToLower()   # эта сумма должна совпасть
Select-String -Path SHA256SUMS -Pattern $F           # с суммой в этой строке
Expand-Archive $F -DestinationPath .

Дальше положите brokapi-0.1.0-alpha.5-windows-x86_64\brokapi.exe в каталог из PATH (или вызывайте по полному пути). В архиве рядом лежат README.md и лицензии.

Через cargo

Нужен Rust 1.88 или новее. Версия предварительная (альфа), поэтому номер указывается явно: без --version cargo install ищет только стабильные выпуски и ответит, что крейта нет.

cargo install brokapi-gateway --version 0.1.0-alpha.5 --locked

Сборка занимает несколько минут. Бинарник brokapi попадает в ~/.cargo/bin.

Самая свежая версия, из клона репозитория:

git clone https://github.com/runinfra/brokapi
cd brokapi
cargo install --path crates/gateway --locked

Проверка

brokapi --version

Должно напечататься brokapi 0.1.0-alpha.5 (номер как у библиотеки). Не напечатало: убедитесь, что каталог с файлом есть в PATH (для cargo install это ~/.cargo/bin), а при ошибке сборки смотрите таблицу выше (rustc, cargo). Дальше: быстрый старт Gateway.

Если вы пишете бота на Rust и вам нужен только клиент гейтвея, программа не нужна: Подключить бота.

Перед боевым счетом

brokapi в открытой альфе. Заявки, сверка и лимиты проверены на имитациях брокеров. Коннектор Bybit проверен вживую (что именно и что нет). БКС, Т-Банк, Финам и АЛОР проверены только на имитациях, на настоящих счетах их пока не запускали, поэтому первый запуск на них делайте осторожно.

0. Правило 0. Боевой токен выдает человек, чей это счет, и первую боевую заявку ставят только с его слова. Если код пишет ИИ-агент, он сам не создает токен с правом торговли и не включает флаги записи (BCS_IS_WRITE и подобные). Что попросить у человека: Контракт для агентов, правило 0.
1. Начните без токена: имитации (brokapi.testing, быстрый старт на Python). Потом Т-Банк: песочница. У БКС и Финама песочницы нет, заявка уйдет на настоящий счет. У АЛОРа есть тестовый контур со своим счетом, у Bybit демо-счет с виртуальными деньгами.
2. Первая заявка - лимитная, минимальное количество, цена заведомо далеко от рынка, сразу отмена.
3. Перезапустите бота при стоящей заявке и убедитесь, что сверка ее узнала.
4. Не оставляйте бота без присмотра, пока не проверили оба пункта выше на своем счете.
5. Заранее решите, как остановить бота, и проверьте это: Аварийная остановка бота. Остановка бота заявки на бирже не снимает.

Что сделает брокер в спорных случаях, мы берем из его документации. Если на вашем счете оно работает иначе, нажмите «Сообщить об ошибке». На страницах брокеров в разделе «Что учесть» собрано то, что меняет код бота.

Аварийная остановка бота

Инструкция. Цель: остановить бота, который ведет себя не так, и твердо знать, что при этом останется на счете. Заранее, до первой боевой заявки, решите, какой из путей ниже ваш, и проверьте его на имитации или песочнице.

Главное, что надо знать: остановка бота заявок на бирже не снимает. Заявка живет у брокера дольше, чем процесс, который ее поставил. Стоп-заявки тоже остаются. Позицию не закрывает ничто из того, что описано здесь.

Что остается на счете после каждого действия

flowchart TB
  A[Бот ведет себя не так] --> B[Остановить процесс бота]
  B --> C[Что должно остаться на счете]
  C -- ничего, позицию закрою сам --> D[brokapi cancel-all]
  C -- позиция под защитой стопа --> E[Снять только заявки бота из журнала]
  E --> F[Сверить позиции и стопы]

На схеме: сначала всегда останавливают бота, чтобы он не ставил новые заявки, а потом выбирают, снимать ли все подряд или только заявки бота. От выбора зависит, останется ли позиция защищенной.

Что делает close()

await client.close() останавливает два коннектора клиента (рыночных данных и счета), дает им до deadline секунд закончить дела (по умолчанию 5, None - сразу) и завершает поток событий. Он безопасен при повторном вызове и возвращает отчеты коннекторов. Заявки на бирже он не снимает, как и shutdown в Rust (Контракт для агентов, правило 10). Если бот должен уйти, не оставив заявок, он снимает их сам до close().

У клиента, подключенного через гейтвей, close() только закрывает его соединение. Гейтвей продолжает работать, заявки и стопы остаются, подписки этого бота гейтвей отпускает сам, когда бот долго не появляется.

brokapi cancel-all

brokapi cancel-all <гейтвей>

Команда снимает все активные заявки и все стоп-заявки счета. В том числе защитные стопы вашего бота и чужие заявки, поставленные руками или другой программой. После нее открытая позиция остается без стопа, а заявки, о которых вы не знали, исчезают.

Это аварийная кнопка на случай, когда важнее всего очистить счет, а позицию вы защитите или закроете сами. Гейтвей при этом продолжает работать. Команда заявок не ставит. На отказ по лимиту она ждет и повторяет, пока не снимет. Нужен запущенный гейтвей (Команды brokapi, Запуск и обслуживание). Ту же работу с остановкой гейтвея делает brokapi stop <гейтвей> --cancel-orders.

Прежде чем запускать, посмотрите, что будет снято:

brokapi orders <гейтвей>    # активные заявки счета
brokapi stops <гейтвей>     # активные стоп-заявки счета

Агент запускает cancel-all только со слова человека: команда меняет настоящий счет, и защитные стопы после нее придется ставить заново.

Снять заявки бота и оставить позицию защищенной

Нужен список cid бота, то есть его журнал (Контракт, правило 1). Скрипт открывает клиента, сверяется с журналом и снимает только то, что в журнале, живое и найдено у брокера. Стопы он не трогает, чужие заявки (foreign) тоже.

async def cancel_own_orders(client: brokapi.Client, ledger: Iterable[uuid.UUID]) -> list[uuid.UUID]:
    """Cancels the live orders of the bot (the cids of its journal). Stop orders and foreign orders stay.

    Returns the cids whose outcome is not clear: look at them with `order_state`, do not cancel them again blindly."""
    report = await client.reconcile(list(ledger))  # the gate of the commands is closed in a new process, `cancel` too
    unclear = []
    for order in report.confirmed:  # the orders of the journal that are alive at the broker; `foreign` is not touched
        try:
            await client.cancel(order.cid)
        except brokapi.Rejected:
            pass  # not found: it was filled or cancelled a moment ago. `order_state(cid)` tells which
        except brokapi.RateLimited as limited:
            await asyncio.sleep(limited.retry_after.total_seconds())  # nothing was sent: wait and try this one again
            try:
                await client.cancel(order.cid)
            except brokapi.BrokapiError:
                unclear.append(order.cid)
        except (brokapi.Unknown, brokapi.Transport):
            unclear.append(order.cid)
    return unclear

Что здесь важно:

• reconcile нужен и скрипту: в новом процессе шлюз торговых команд закрыт, и cancel без него вернет NotReconciled.
• Заявки в confirmed взяты из вашего журнала. Заявки в foreign (их нет в журнале) скрипт не снимает: это решение человека.
• Rejected на cancel значит «брокер такой заявки не знает»: она уже исполнилась или снята. Что именно, скажет order_state(cid).
• Unknown и Transport на cancel значат, что исход неясен. Повторять вслепую не нужно: спросите order_state(cid). Скрипт возвращает такие cid списком.
• За время работы скрипта заявка могла частично исполниться. Позиция тогда выросла, а стоп остался прежним по размеру.

После снятия сверьте позиции и стопы и, если стопа не хватает, поставьте недостающий: Бот со стопом: старт и рестарт. Тот же рецепт делает бот при каждом запуске, поэтому после аварии достаточно запустить его заново.

Скрипт идет в паре с остановкой самого бота. В Rust порядок тот же (Запуск, рестарт и остановка): остановить поток решений, снять свои заявки по журналу, shutdown, и только потом процесс.

Что делает человек

Бот и скрипт позицию не закрывают. Если позицию надо закрыть, это делается в приложении или кабинете брокера: библиотека для этого не предназначена, а команды brokapi заявок не ставят (Команды brokapi).

Как проверить

Скрипт «снять заявки бота» проверен на имитациях всех четырех брокеров: две заявки бота и одна чужая стоят вместе с защитным стопом, бот закрывается, скрипт в новом процессе снимает две, чужая и стоп остаются. Потерянный ответ на cancel попадает в список неясных. Для этих тестов нужен клон репозитория (в пакете pip тестов и примеров нет):

git clone https://github.com/runinfra/brokapi && cd brokapi
pip install brokapi pytest pytest-asyncio
cd crates/python && pytest tests/test_guides.py -k emergency

Свой путь остановки проверьте так же: поставьте заявку и стоп на имитации или песочнице, остановите бота выбранным способом и посмотрите active_orders() и active_stop_orders() (или brokapi orders и brokapi stops).

Карта: сущности и три круга

Эта страница - карта библиотеки: из чего она состоит, по каким кругам ходят данные и команды и на каких правилах это держится. Подробности каждого круга лежат на своей странице, здесь только то, что нужно, чтобы не потеряться. Термины в таблице ниже - словарь всей книги: везде они значат ровно это.

Сущности и связи

Бот сам поднимает коннекторы, глобального реестра в библиотеке нет. Коннекторов два вида: MD - рынок, один на брокера, и UD - заявки и портфель, один на счет. Все пишут в один канал событий. Запускаются они одинаково: start(конфиг, счетчик_лимитов, канал_событий).

На схеме: бот, библиотека с коннекторами, брокер, общий канал событий и счетчик лимитов.

flowchart TB
  BR[Брокер<br>REST, WebSocket, gRPC]
  subgraph lib[Библиотека brokapi]
    MD[MD, рыночные<br>данные, один<br>на брокера]
    UD1[UD, данные<br>счета 1: заявки,<br>портфель]
    UD2[UD, данные<br>счета 2]
  end
  L[Счетчик лимитов<br>один на область квоты]
  Q[(Канал событий<br>один на всех)]
  Bot[Бот]
  BR <--> lib
  L -. квота .- lib
  lib -- события в конверте --> Q
  Q --> Bot
  Bot -- команды --> lib

Из схемы следует три вещи, и у каждой есть причина:

• MD и UD разделены. Всплеск в потоке стакана не должен задерживать отмену заявки. Если бы команды и стакан шли через одно соединение, отмена стояла бы в очереди за стаканом. У MD и UD разные соединения и разные лимиты, они ничего не знают друг о друге и не делят сокет.
• Счетчик лимитов один на ту область, где брокер считает квоту. У Т-Банка это пользователь (все счета вместе), у БКС - токен, то есть счет (по документации). Дать двум коннекторам разные счетчики на одну квоту нельзя: вместе они превысят ее, и брокер начнет отказывать. Дать один счетчик там, где лимиты независимы, тоже плохо: коннекторы будут мешать друг другу без нужды. Как устроен счетчик: Лимиты запросов, какая область у какого брокера: Несколько счетов и брокеров.
• Канал событий один, коннектор не знает, кто его читает. Бот отдал канал при старте и может дать один всем коннекторам или по каналу каждому. Если читатель отстает, коннектор не блокируется: что тогда происходит, решает буфер подписки (Круг событий).

Словарь:

Слои

Крейты разложены так, чтобы логика брокера не знала про сеть, а сеть - про логику. Стрелка на схеме значит «пользуется». Что лежит в каждом крейте, до отдельного типа: Справочник API.

flowchart TB
  CONN[brokapi-bcs, brokapi-tbank, brokapi-finam,<br>brokapi-alor, brokapi-bybit<br>коннекторы: склеивают слои]
  PROTO[brokapi-bcs-protocol, brokapi-tbank-protocol,<br>brokapi-finam-protocol, brokapi-alor-protocol,<br>brokapi-bybit-protocol<br>клиент брокера: сеть]
  RT[brokapi-runtime<br>лимиты, буферы, шлюз,<br>очередь по бумаге, сверка]
  SANS[brokapi-sansio<br>ядро без сети: разбор,<br>машина состояний заявки]
  CORE[brokapi-core<br>общие типы и трейты:<br>то, что видит бот]
  CONN --> PROTO & RT & SANS
  RT --> SANS --> CORE
  MOCK[brokapi-mocks<br>имитации брокеров] -. для тестов .-> PROTO
  CONF[brokapi-conformance<br>общие сценарии] -. проверяет .-> CONN

Что из этого следует:

• Бот видит только brokapi-core. Сменить брокера - поменять коннектор, код бота почти не меняется.
• Ядро без сети проверяется записанными сообщениями брокера и виртуальным временем, быстро и без интернета.
• Внизу - тестовый контур: имитация брокера с настоящим протоколом и общие сценарии, которые гоняются против каждого коннектора.

Зачем ядро без сети

Ядро коннектора (sans-io) - чистая логика: «пришло такое сообщение брокера -> вот события для бота» и «чтобы подписаться, нужно отправить вот такое сообщение». Оно не открывает сокеты, не держит таймеры, не знает про асинхронность. Сеть и время ему подает внешний слой. Интерфейс ядра (BrokerCore) - пять действий: on_frame (разобрать пришедшее сообщение), poll_transmit (что отправить брокеру), poll_timeout (когда разбудить ядро), on_timeout (обработать наступивший срок), apply (привести подписки к нужному набору).

Зачем так:

• Ядро проверяется быстро и без сети. Тест кормит его записанными сообщениями брокера и проверяет события. Время в таких тестах виртуальное.
• Ошибки разбора и перевода ищутся отдельно от ошибок сети. Если смешать, сбой в сети похож на ошибку разбора, и причину ищут не там.
• Записанные настоящие сообщения (когда будут живые прогоны) становятся тестами без правок.

У Т-Банка и Финама запросы типизированы (gRPC), поэтому вместо poll_transmit у ядра Т-Банка есть свой метод выдачи запросов. На работу бота это не влияет.

Три круга

Вся работа - три круга, которые крутятся одновременно и почти не мешают друг другу: события (брокер -> бот), команды (бот -> брокер) и жизнь коннектора (шлюз команд и сверка). Бот общается с коннекторами двумя путями: команды - вызовы методов, ответ приходит как результат вызова, события - все подписки всех коннекторов складываются в один канал.

Круг событий: брокер -> бот

Внутри коннектора сообщение брокера проходит три ступени. Ядро только разбирает и подсказывает, что отправить и когда его разбудить, а сокеты и таймеры держит внешний слой. На схеме: путь сообщения от брокера до бота и служебные сигналы ядра.

flowchart TB
  BR[Брокер] -- сообщение --> P[Протокол<br>сокет, поток gRPC]
  P -- кадр --> C[Ядро без сети<br>on_frame: разбор]
  C -- события в общих типах --> B[Буфер подписки<br>Conflate, DropNewest<br>или Lossless]
  B --> Q[(Канал событий)]
  Q --> Bot[Бот читает<br>отдельной задачей]
  C -. poll_transmit:<br>что отправить .-> P
  C -. poll_timeout:<br>когда разбудить .-> T[Таймер]
  T -. on_timeout .-> C

Поток брокера читается всегда и никогда не ждет бота. Если бот отстает, решает режим буфера:

• Conflate - старый снимок заменяется свежим. Для стакана и котировок.
• DropNewest - лишнее отбрасывается со счетчиком. Для некритичного.
• Lossless - ничего не теряется. Для своих заявок и сделок. Переполнился - Overflow и закрытый шлюз. Оборвался и открылся заново поток заявок или исполнений - Reconnected и тоже закрытый шлюз (круг жизни ниже).

Почему режимов три: стакану нужен только последний снимок, а своим сделкам нужны все, и один режим на все подписки либо потерял бы деньги, либо копил бы устаревший стакан. Подробно, с обрывами и восстановлением соединений: Круг событий.

Круг команд: бот -> брокер

Команда проходит три проверки без сети, и только потом уходит к брокеру. На схеме: путь place и все его исходы.

flowchart TB
  A[place с cid] --> G{Шлюз открыт}
  G -- нет --> E1[NotReconciled, Degraded<br>или ShuttingDown]
  G -- да --> V{Вход верный}
  V -- нет --> E2[Rejected]
  V -- да --> L{Квота есть}
  L -- нет --> E3[RateLimited]
  L -- да --> O[Очередь по бумаге:<br>ждет прежние команды]
  O --> M[cid помечен использованным<br>повтор cid: Rejected]
  M --> S[Отправка брокеру]
  S --> R{Ответ}
  R -- принял --> OK[OrderAck]
  R -- отказал --> RJ[Rejected]
  R -- нет ответа --> U[Unknown<br>без повтора]

Что из этого следует:

• Все, что выше «Отправки», до брокера не доходит. Заявки точно нет, а при отказе на первых трех проверках cid не потрачен: после устранения причины его можно использовать снова. cid помечается только после очереди, поэтому пока вызов ждет в очереди, номер еще чистый.
• Unknown не повторяется никогда. Заявка без ответа могла встать, повтор дал бы две заявки. Бот выясняет судьбу через order_state(cid): Если что-то пошло не так.
• Очередь по бумаге: отмена не обгонит постановку той же бумаги. Разные бумаги идут параллельно. Отмена тратит отдельное ведро квоты, поэтому поток постановок ее не вытесняет (Лимиты запросов).

Исходы, коды отказов и порядок проверок подробно: Круг команд.

Круг жизни: шлюз торговли

У каждого UD есть шлюз торговых команд. Чтение и подписки работают всегда, закрывается только торговля. На схеме: три состояния шлюза и переходы между ними.

stateDiagram-v2
  state "Не сверен<br>NotReconciled" as NR
  state "Торговля открыта" as OPEN
  state "Перегрузка<br>Degraded" as DEG
  state "Остановка<br>ShuttingDown" as SD
  [*] --> NR: start
  NR --> OPEN: reconcile успешен
  OPEN --> DEG: Overflow в Lossless-буфере<br>или Reconnected потока заявок
  DEG --> OPEN: бот дочитал канал и reconcile
  OPEN --> SD: shutdown
  NR --> SD: shutdown
  DEG --> SD: shutdown
  SD --> [*]

Из обоих закрытых состояний выход один - сверка. Это и есть ответ на вопрос «можно ли торговать»: только когда список заявок бота совпал со счетом и в данных о своих заявках нет дыры. Остановка необратима: коннектор закрывается, торговать дальше нельзя.

Сверка, ее результат и причины порядка действий: Круг жизни. Что делать по шагам: Запуск, рестарт и остановка бота.

Круг событий: подписки, буферы, обрывы

Страница описывает путь события от брокера к боту и то, что происходит, когда бот отстает или связь рвется. Схема пути - на Карте, здесь ее подробности: подписки, режимы буфера, переполнение, Resync, восстановление соединений и токены.

Подписка

Метод subscribe_* (стакан, сделки, котировки, свечи, статусы заявок, исполнения, портфель) возвращает SubscriptionId. События этой подписки приходят в общий канал в конверте с этим номером. Снять подписку можно методом unsubscribe(sub) (для рыночных подписок).

Что важно:

• subscribe_* возвращается, когда поток открыт (у Финама есть оговорка, см. ниже). Событие, которое случилось после возврата, до бота дойдет: заявку можно ставить сразу после subscribe_order_state и subscribe_executions. Раньше нельзя: заявка, исполненная до открытия потока, оставила бы бота без события. Поток не открылся за subscribe_ack_timeout (3 секунды, у Т-Банка request_timeout) - ошибка Transport, подписка снята, вызов можно повторить. Отказ брокера (нет такого инструмента, нет прав) - Rejected { subscription_refused }. Что считается «поток открыт», зависит от брокера:

  Брокер	Признак
  БКС, заявки, исполнения, портфель	сокет orders/events/ws или portfolio/ws открыт (брокер присылает данные сам, подтверждения в протоколе нет)
  БКС, рынок	кадр подтверждения брокера (...Success), либо первые данные подписки
  Т-Банк	ответ брокера о подписке в самом потоке (Ok), для портфеля оба потока
  Финам	брокер открыл поток (заголовки ответа получены). Оговорка ниже
  АЛОР	кадр 200 на подписку (guid подписки)
  Bybit	ответ на подписку с тем же req_id и success: true

  Вызов может идти до этого срока. Если за него поток не открылся, это Transport (сеть, медленный брокер), а не отказ брокера. У БКС и Финама брокер подтверждения не присылает: между открытием сокета или потока и моментом, когда брокер начинает слать события, остается промежуток на его стороне, и библиотека его не видит.

  Финам - исключение. Финам работает по gRPC, а gRPC-сервер может отправить заголовки ответа потока только вместе с первым сообщением. Поток статусов заявок молчит, пока заявок нет, поэтому здоровый поток может выглядеть «не открытым» до первой заявки. Поэтому у Финама subscribe_* ждет открытия потока до subscribe_ack_timeout, и если за это время поток не открылся, все равно возвращает Ok: поток дооткрывается в фоне, подписка не снимается, а гарантии «все после возврата дойдет» до открытия потока нет (состояние покажет sub_status). Отказ брокера внутри срока по-прежнему возвращается ошибкой Rejected.

• Повторная подписка. У Т-Банка подписка на статусы заявок, исполнения и портфель одна на коннектор: повторный вызов вернет тот же SubscriptionId. Стакан и котировки одного инструмента идут одной проводной подпиской, отписка от одной не рвет другую.

• Квота. У Финама открытие потока тратит квоту, как любой запрос. Число одновременных потоков ограничено (subscription_quota).

Режимы буфера

Между потоком брокера и общим каналом стоит буфер на каждую подписку. Поток брокера читается в любом случае и никогда не ждет, пока бот разберет канал. Если бот отстает, события копятся в буфере подписки, а режим решает, что с ними будет. Режим бот выбирает при подписке (SubscribeOpts).

Для статусов своих заявок и исполнений годится только Lossless: библиотека сама ставит этот режим, размер буфера задается в конфиге UD (order_state_buffer, по умолчанию 1024). Для портфеля режим выбирает бот.

Получается два простых правила:

• Стакан, котировки - Conflate. Старый снимок бесполезен, нужен последний.
• Все, что нельзя потерять, - Lossless с достаточным cap и быстрое чтение канала ботом.

Переполнение: Overflow и Degraded

Если Lossless-буфер заполнился:

1. Коннектор присылает Event::Overflow { sub, lost_from }: этой подписке не хватило места, события начиная с lost_from могли быть потеряны. Событие приходит один раз на подписку, раньше обычных данных.
2. Новые события этой подписки отбрасываются, пока не будет сверки. Тихой потери нет: бот знает, что дыра образовалась.
3. Коннектор переходит в состояние Degraded: торговые команды возвращают Error::Degraded. Продолжать торговлю при дыре в данных о своих заявках нельзя.

На схеме: как медленное чтение канала доходит до закрытой торговли.

flowchart TB
  A[Бот читает канал медленно] --> B[Lossless-буфер заполнен]
  B --> C[Event::Overflow<br>и состояние Degraded]
  C --> D[Команды: Error::Degraded]
  D --> E[Выход: бот дочитывает канал<br>и зовет reconcile]

Почему торговля закрывается, а не продолжается с пометкой «возможна дыра»: бот видит свои заявки только по событиям, и потерянное событие о частичном исполнении или снятии значит, что бот торгует по неверной картине. Закрытый шлюз заставляет сначала сверить ее со счетом. Порядок действий боту: Если что-то пошло не так.

Чтобы переполнения не было: читайте канал отдельной задачей и не делайте в ней долгих операций. Размер буфера подберите с запасом на всплеск.

У всех брокеров механизм одинаковый. Буферы подписок у Т-Банка и БКС - один и тот же код (Emitter из brokapi-runtime), у Финама свой, с теми же правилами.

Для рыночных подписок сверки нет (сверка - это про заявки), поэтому после Overflow подписку нужно снять (unsubscribe) и оформить заново. Для рыночных данных обычно хватает Conflate, и переполнения нет.

Resync: стакан мог потерять данные

Стакан у всех брокеров приходит полным снимком, не приращениями. Поэтому следующий снимок сам заменяет прежний. Но бывает, что прежнему верить уже нельзя. Тогда приходит Event::Resync { sub, instrument, reason }.

Когда:

У БКС и АЛОРа SequenceGap не бывает: стакан приходит полным снимком, и сверять нечего. SubscriptionReset идет по одному разу на каждую подписку на стакан, сразу после переподключения WebSocket и до снимков восстановленных подписок. Первое подключение Resync не дает: терять нечего. Коннектор узнает о подключении от самой сессии WebSocket, отдельным служебным сообщением в том же потоке, что и данные, поэтому Resync не может обогнать данные и не может опоздать за ними.

Что делать: выбросить стакан, который хранится у бота, не торговать по нему, дождаться следующего Event::OrderBook. У Финама Resync идет вне очереди склейки. У Т-Банка и БКС он проходит через буфер подписки, и если бот сильно отстает, его может заменить более свежий снимок (он тоже свежий, так что бот в любом случае получит актуальные данные).

Reconnected: поток заявок или исполнений оборвался

Потоки своих заявок (subscribe_order_state) и своих исполнений (subscribe_executions) тоже обрываются и переоткрываются сами. Но в отличие от стакана, здесь за время обрыва могло произойти то, о чем бот не узнает из потока: заявка исполнилась, снялась, была отклонена. Поэтому после того как поток открылся заново, приходит Event::Reconnected { sub, gap_from } на подписку, чей поток оборвался.

• sub - подписка, у которой оборвался поток. Приходит по одному событию на подписку заявок и на подписку исполнений (если подписаны на обе).
• gap_from - время (локальные часы, наносекунды), когда коннектор заметил обрыв. Дыра начинается в этот момент или раньше, поэтому историю читайте с запасом назад.

Что делает коннектор: закрывает торговый шлюз, как при Overflow. Команды получают Degraded и в сеть не уходят, пока не пройдет reconcile. Шлюз закрывается раньше, чем событие дойдет до бота, поэтому команда после события уже отказана.

Что делать боту: то же, что после Overflow. Дочитать канал до конца (события до дыры нужны как обычно), прочитать состояние у брокера (active_orders, order_state по своим cid, executions с момента чуть раньше gap_from), вызвать reconcile. Успешная сверка открывает шлюз. Подробно: Если что-то пошло не так.

Для портфеля такого события нет: каждое сообщение потока портфеля и так целое состояние, следующее заменит прежнее. Для рыночных данных вместо него Resync (выше).

Восстановление соединений

Все коннекторы сами переоткрывают оборванные соединения и восстанавливают подписки. Бот ничего для этого не делает. На схеме: что происходит после обрыва, пока поток снова не заработает.

flowchart TB
  W[Поток работает] --> X[Обрыв: молчание,<br>ошибка, закрытие]
  X --> P[Пауза: 0,5 с, дальше<br>удваивается до 30 с]
  P --> R[Переподключение]
  R -- не вышло --> P
  R -- вышло --> S[Подписки восстановлены]
  S --> RS[Resync по стакану:<br>старый выбросить]
  RS --> W

Из схемы следует, что бот не видит обрыва как отдельного события: он видит Resync по стакану, когда поток вернулся, и Reconnected по потокам заявок и исполнений. Стакан у всех брокеров приходит полным снимком, поэтому после Resync достаточно дождаться следующего. А после Reconnected бот обязан прочитать состояние и позвать reconcile (Если что-то пошло не так). Параметры по брокерам:

Почему паузы одинаковые. Ни в коде, ни в документации брокеров нет причины для разных диапазонов: ни один брокер не называет, как часто можно переподключаться. Поэтому у всех один диапазон. Начало в 0,5 с не бьет по серверу в первую секунду обрыва, а потолок в 30 с не оставляет бота без данных дольше половины минуты. У БКС, АЛОРа и Bybit границы можно поменять в настройке коннектора. Сколько подключений в секунду терпит БКС, в документации не названо. У Т-Банка и Финама паузы пока зашиты в код.

Особенности:

• Финам: подписка, которую сервер отверг (нет прав, нет инструмента), помечается Failed и пробуется снова примерно раз в 30 секунд, на случай, если права появятся. subscribe_* вернет ошибку сразу, если отказ пришел при открытии.
• Т-Банк: поток с истекшим сроком жизни (ошибка 80005) обрабатывается как обычный обрыв. Отказ открыть поток, который повтор не вылечит (токен не подошел, нет права, открыто максимум потоков, 80001), останавливает поток: subscribe_* возвращает ошибку, а у потока заявок или сделок, оборвавшегося позже, закрывается шлюз. Новая подписка пробует открыть поток заново.
• БКС: при отказе 403 при подключении токен обновляется принудительно.

Токены и их обновление

Один JWT Финама можно разделить между несколькими коннекторами одного секрета (shared_tokens): Несколько счетов и брокеров.

Симптомы, которые видит бот, и что с ними делать: Ошибки и что с ними делать.

Круг команд: заявки

Страница объясняет, что происходит с заявкой от вызова place до исполнения и что бот делает в каждом случае. Три правила, на которых держится вся библиотека, - в начале книги. Схема самого круга - на Карте, здесь ее подробности. Исходы и коды отказов собраны на странице Ошибки и что с ними делать, порядок действий после неясного исхода - на странице Если что-то пошло не так.

cid: номер заявки

cid (ClientOrderId) - это UUID, который бот создает сам: ClientOrderId::new_v4(). Библиотека номера не придумывает. Причины:

• Библиотека ничего не помнит между запусками. Она не пишет на диск. После рестарта бот приносит список своих cid, и по нему заявки на счете делятся на свои и чужие (Круг жизни).
• Номер нужен до отправки. Если ответа нет, cid - единственная нить, по которой можно спросить брокера: «что с заявкой, которую я пытался поставить?». Если бы номер выдавала библиотека, он потерялся бы вместе с ответом.
• Случайный UUID не требует согласования. Столкновение практически невозможно, ни один процесс ни с кем не координируется.

Правила для бота:

• Один cid - одна заявка. Новая попытка - новый cid. Старый cid библиотека повторно не отправит: вернет Rejected с кодом duplicate_place, в сеть ничего не уйдет. Это касается и тех попыток, которые закончились отказом брокера. Зачем так жестко: после таймаута первая заявка могла дойти. Что брокер сделает с повтором того же номера, зависит от брокера (LabelOnly, см. ниже), и надеяться, что он отбросит дубль, нельзя.
• Единственное исключение: вызов отвергнут до отправки, когда cid еще не помечен использованным. Так бывает при NotReconciled, Degraded и ShuttingDown, при ошибке входа (missing_price, invalid_qty, идентификатор инструмента другого брокера) и при RateLimited. Заявки нет, cid годен, после устранения причины его можно использовать снова (у всех брокеров). Не уверены - берите новый cid, это всегда безопасно.
• Перед вызовом place запишите cid в свой журнал (состояние «отправляю»). Иначе после падения процесса между отправкой и записью вы потеряете заявку, о которой не знаете.
• Для изменения заявки (replace) нужен новый cid: старый указывается как original_cid.

Как cid уходит к брокеру

У всех «защиту от повторной отправки той же заявки» библиотека пока считает отсутствующей (LabelOnly). Что делает брокер с повтором, измерят только живые прогоны. Это не меняет правило: повторять заявку нельзя.

Что происходит в place

Порядок проверок у всех брокеров один, и он показан на схеме круга: Карта. Сначала шлюз команд, потом проверка входа без сети, потом квота у счетчика лимитов, потом очередь по бумаге, потом шлюз еще раз, и только после этого cid помечается использованным и команда уходит к брокеру. Почему именно так:

• Дешевые проверки первыми. Шлюз, вход и квота не требуют ни сети, ни ожидания. Отказ на любой из них ничего не тратит: ни cid, ни времени в очереди.
• Квота до очереди. Отказ по квоте приходит сразу, а не после ожидания за другими командами по бумаге.
• Шлюз проверяется второй раз после очереди. Команда могла простоять в очереди за другой командой по той же бумаге, и за это время шлюз закрылся: оборвался поток заявок или исполнений (Event::Reconnected), переполнился буфер (Overflow), началась остановка. Закрытый шлюз значит, что в сеть ничего не уходит, и это верно и для команды, которая уже стоит в очереди: она получает Degraded или ShuttingDown, а не уходит к брокеру. Для cancel и cancel_stop так же.
• cid помечается как можно позже, прямо перед отправкой. Пока вызов стоит в очереди, номер чистый: если вызов отменили или он не дошел до отправки, номером можно воспользоваться снова. Пометка сразу после очереди и до сети: второй place с тем же cid увидит ее и не уйдет.
• Отказ duplicate_place приходит уже после квоты и очереди, поэтому единица квоты на него потрачена, хотя в сеть ничего не ушло.

Все, что находится выше отправки, не доходит до брокера: можно не сомневаться, что заявки нет. На схеме ниже

• тот же путь во времени: бот, UD-коннектор и брокер.

%%{init: {'sequence': {'width': 90, 'actorMargin': 40, 'mirrorActors': false}}}%%
sequenceDiagram
  participant Bot as Бот
  participant UD as UD-коннектор
  participant Br as Брокер
  Bot->>UD: place(cid, бумага, цена)
  UD->>UD: шлюз, квота, очередь по бумаге
  UD->>Br: заявка с cid
  alt принята
    Br-->>UD: номер брокера
    UD-->>Bot: OrderAck
  else отказ
    Br-->>UD: ошибка
    UD-->>Bot: Rejected
  else нет ответа
    UD-->>Bot: Unknown, без повтора
    Bot->>UD: order_state(cid)
  end
  Br-->>UD: статусы и исполнения
  UD-->>Bot: Event::Order, Event::Execution

Ответ на place и статусы приходят разными путями: ответ - результатом вызова, статусы и исполнения - событиями в общем канале. Порядок между результатом вызова и событием не гарантирован: событие может прийти и после ответа, и раньше него. Поэтому после OrderAck заявка еще не исполнена, это только «брокер принял». Ждать исполнения нужно по Event::Order и Event::Execution, а не по ответу.

Исходы команды

Любая команда (place, cancel, replace, стоп-команды) заканчивается одним из трех видов исхода, и они отвечают на главный вопрос: дошла ли команда до брокера.

1. Не дошла. Закрыт шлюз (NotReconciled, Degraded, ShuttingDown), не прошла проверка входа или Unsupported, не хватило квоты (RateLimited), неверная настройка (Config). Заявки нет, делать с ней нечего, исправляется причина.
2. Дошла и получила ответ. Ok(OrderAck) - брокер принял. Rejected - брокер точно отказал, заявки нет.
3. Дошла, ответа нет. Unknown (и Transport на команде, если брокер мог ее получить). Заявка могла встать. Это единственный исход, где нельзя ни повторять, ни считать, что заявки нет.

Таблица «исход -> что значит -> почему бывает -> что делать» лежит в справочнике ошибок, там же коды Rejected. Особенности перевода ответов в исходы:

• БКС. Отказ может прийти не ошибкой HTTP, а внутри обычного ответа 200 (статус заявки 8, rejectReason). Библиотека читает оба случая и возвращает Rejected.
• Т-Банк. Брокер может принять запрос и ответить статусом «отклонено» внутри ответа. Это тоже Rejected (код REJECTED).
• Проверка входа до отправки у всех одна. Количество: положительное, целое там, где брокер берет целые (БКС, Т-Банк), и кратное лоту, если лот известен. Иначе Rejected с кодом invalid_qty. Ничего не округляется: дробное количество там, где брокер берет целые, это отказ. Количество в единицах инструмента, не в лотах, у любого брокера (Деньги, цены и количества). Цену коннектор сверяет с шагом, если шаг ему передан (price_grid()): цена не на шаге - Rejected { price_off_step } до отправки, квота и cid не тратятся. Идентификатор инструмента другого брокера (например SymbolMic Финама у Т-Банка) это Config, без сети. Как округлить цену точно и как передать шаг - Деньги, цены и количества.

Как это выглядит в коде

Номер придумывает бот и записывает в журнал до вызова. Вкладка выбирает язык, выбор запоминается для всей книги.

let cid = request.cid; // made by the bot: ClientOrderId::new_v4()
journal.sending(cid)?; // on disk BEFORE the call
let result = ud.place(request).await;

cid = brokapi.new_cid()  # made by the bot
journal.sending(cid)  # on disk BEFORE the call
result = await client.place(cid=cid, instrument=instrument, side=brokapi.Side.BUY, qty=qty, price=price)

Исходы разбираются так, что «заявки точно нет» и «заявка могла встать» никогда не путаются. На Unknown и Transport повтора нет, есть вопрос брокеру по тому же cid:

let cid = request.cid;
match ud.place(request).await {
    Ok(_) | Err(Error::Rejected { .. }) => {}
    Err(Error::Unknown | Error::Transport(_)) => {
        // The order may exist. NEVER place again. Ask about THE SAME cid (see the recovery page for the loop).
        let _state = ud.order_state(cid).await;
    }
    Err(other) => return Err(other.into()),
}

cid = brokapi.new_cid()
state = None
try:
    await client.place(cid=cid, instrument=instrument, side=brokapi.Side.BUY, qty=qty, price=price)
except brokapi.Rejected:
    pass  # the broker said no: there is no order
except (brokapi.Unknown, brokapi.Transport):
    # The order may exist. NEVER place again. Ask about THE SAME cid (see the recovery page for the loop).
    state = await client.order_state(cid)

В Python это исключения brokapi.Rejected, brokapi.Unknown и brokapi.Transport из brokapi.errors: те же имена и тот же текст, что у Error в Rust. Если задачу, которая ждет place, отменить в Python, команда все равно доходит до конца: после этого тоже спрашивайте order_state.

Почему нет автоповтора

Заявка, которая ушла к брокеру и осталась без ответа, может находиться в трех состояниях: брокер ее не получил, получил и поставил, получил и отклонил. Из «нет ответа» этого не понять. Если отправить заявку еще раз, а первая все-таки встала, на счете окажутся две заявки. Для денег это худший исход, поэтому библиотека повторяет только то, что безопасно (чтение), и никогда не повторяет команды.

То же относится к тому, что библиотека не делает сама после ошибки: не пробует другую форму запроса, не меняет количество и цену, не ставит заявку заново.

У всех брокеров таймаут на place дает Unknown, второй вызов с тем же cid не уходит в сеть (duplicate_place), а заявка, которую брокер все-таки принял, находится через order_state.

Что делать вместо повтора: спросить брокера по cid, это описано в Если что-то пошло не так.

cancel

cancel(cid) снимает заявку по вашему cid. Исходы те же, что и у place. Особенности:

• Ok(()) значит: брокер подтвердил отмену. У БКС команда синхронная, и «отменено» говорится только тогда, когда брокер сам ответил, что заявка отменена.
• Заявка уже исполнилась: БКС вернет Rejected с кодом already_filled, остальные - отказ брокера.
• Unknown: отмену можно повторить вручную после проверки order_state. Повторная отмена новых заявок не создает. Библиотека сама ее не повторяет.
• У БКС, если после синхронной отмены заявка по ответу еще жива, результат тоже Unknown: «отменено» не объявляется без подтверждения. Так бывает со статусом 6 «Отменяется (в процессе отмены)»: заявка еще стоит в стакане и может исполниться раньше, чем отмена дойдет до конца. Такой статус приходит как состояние Unknown, не Cancelled. Cancelled будет, когда брокер пришлет статус 4, а если заявка успела исполниться, придет Filled.
• Отмена идет через отдельное ведро лимитов, постановка ее не вытесняет (Лимиты запросов).

replace: изменить заявку

replace(ReplaceOrderRequest { cid, original_cid, qty, price }) меняет количество и (или) цену. cid - новый номер, original_cid - заявки, которую меняем. Количество и цена, которых вы не указали, берутся от исходной заявки (коннектор для этого один раз читает ее у брокера).

Unknown на replace неприятнее, чем на place: непонятно, что с обеими заявками. Спрашивайте order_state по обоим номерам, и по исходному, и по новому.

Машина состояний заявки

Состояние приходит в Event::Order (поле state в OrderSnapshot) и в ответе order_state. На схеме: состояния заявки и переходы между ними. Каждый переход - событие Event::Order, и в каждом есть cid.

stateDiagram-v2
  [*] --> InFlight: place ушел к брокеру
  InFlight --> Acked: брокер принял
  InFlight --> Конец: отказ, Rejected
  InFlight --> Unknown: таймаут или обрыв
  Unknown --> Acked: order_state или сверка
  Unknown --> Конец: выяснилось
  Acked --> PartiallyFilled: часть исполнена
  PartiallyFilled --> PartiallyFilled: еще исполнение
  Acked --> Конец
  PartiallyFilled --> Конец
  state "Конец: Filled,<br>Cancelled, Rejected" as Конец
  Конец --> [*]

Из Unknown библиотека сама не выходит: только запрос состояния или сверка. Это сделано намеренно: любое «само выяснилось» было бы догадкой, а на догадке нельзя ставить вторую заявку. Из конечных состояний выхода нет, поэтому событие о конце можно считать окончательным.

Статусы брокеров переводятся в эти состояния. Статус, который библиотека не знает, у Финама считается рабочей заявкой, а неопределенный статус Т-Банка переводится в Unknown.

Порядок команд по бумаге

Команды по одному инструменту выполняются строго по очереди, в порядке вызова: отмена, отправленная после постановки, не обгонит ее. Если бы обгоняла, отмена пришла бы к брокеру раньше заявки, ответила бы «такой нет», а потом заявка встала бы и осталась на счете, хотя бот считает ее снятой. Реализовано блокировкой на инструмент (InstrumentLocks). Особенности:

• Ключ блокировки - symbol@mic, а не весь идентификатор. Один инструмент, названный тикером, uid или figi, - одна очередь.
• Блокировка снимается при любом исходе: отказ, ошибка сети, отмена вызова.
• Отказ брокера бумагу не блокирует. Это проверяется отдельным сценарием (в БКС однажды ошибка оставляла бумагу занятой до перезапуска).
• Для cancel бумага берется из заявок, которые поставил этот процесс. Если заявка осталась с прошлого запуска и бумага процессу неизвестна, cancel в очередь не встает.
• Команды по разным бумагам идут параллельно.

Сколько ждать ответа

Время ожидания ответа на команду задается в настройке клиента брокера: у Т-Банка и БКС 30 секунд по умолчанию, у Финама 10 секунд. По истечении ответ Unknown. Пока команда ждет, она занимает очередь по бумаге, поэтому следующие команды по той же бумаге ждут за ней. Слишком короткий таймаут плодит Unknown на заявках, которые брокер успел бы принять, слишком длинный держит очередь по бумаге.

Что бот хранит

Минимум для работы с заявками: журнал cid (что отправлено, что подтверждено, что закрыто), пометка «проверить» у заявок с неясным исходом и номер брокера (broker_id), если он нужен для отмены стопов у Т-Банка (Стоп-заявки). Что хранит бот, а что библиотека: Круг жизни.

Круг жизни: шлюз и сверка

После запуска библиотека не знает, какие заявки у бота были раньше: она ничего не хранит на диске. А на счете могут стоять заявки с прошлого запуска, заявки, которые исполнились, пока бот был выключен, и заявки, поставленные руками. Сверка (reconcile) разбирает это и только после нее открывается шлюз торговых команд. Это третий круг механики: он решает, можно ли сейчас торговать. Схема трех кругов вместе - на Карте.

Шлюз команд

У каждого UD есть шлюз торговых команд (CommandGate). Чтение работает всегда: order_state, active_orders, executions, portfolio, подписки. Закрывается только торговля: place, cancel, replace, place_stop, cancel_stop возвращают ошибку и в сеть не уходят. На схеме: состояния шлюза и переходы между ними.

stateDiagram-v2
  state "Не сверен<br>NotReconciled" as NR
  state "Торговля открыта" as OPEN
  state "Перегрузка<br>Degraded" as DEG
  state "Остановка<br>ShuttingDown" as SD
  [*] --> NR: start
  NR --> OPEN: reconcile успешен
  OPEN --> DEG: Overflow в Lossless-буфере
  DEG --> OPEN: бот дочитал канал и reconcile
  OPEN --> SD: shutdown
  NR --> SD: shutdown
  DEG --> SD: shutdown
  SD --> [*]

Шлюз закрыт в трех случаях, и у каждого своя причина:

• NotReconciled: после запуска. Пока бот не знает, какие заявки уже стоят у брокера, новая команда может задвоить заявку или спорить с той, которую бот не видит.
• Degraded: переполнился буфер подписки без потерь. События о своих заявках могли пропасть, и локальная картина заявок с дырой. Торговать при дыре нельзя (Круг событий).
• ShuttingDown: идет остановка. Выхода нет, коннектор закрывается (Запуск, рестарт и остановка).

Если закрыто несколько условий одновременно, первым проверяется ShuttingDown, затем Degraded, затем NotReconciled. Успешная сверка снимает NotReconciled и Degraded. Из обоих закрытых состояний выход один - сверка. Что делает каждая ошибка шлюза и как из нее выйти: Ошибки и что с ними делать.

Что бот передает и что получает

Бот передает список cid заявок, которые он считает живыми (открытыми или с неизвестным исходом). Получает ReconcileReport с тремя списками:

У чужих заявок cid подставной: брокер вашего номера не знает. Он стабильный (один и тот же для одной заявки) и выглядит как UUID, но выдан библиотекой из номера брокера, а не вами. Почему foreign нельзя трогать: бот не знает, зачем человек поставил эту заявку, и снятие может сломать чужую стратегию или защитный стоп.

В коде порядок такой. Подписка идет до сверки, сверка принимает список из журнала, три списка разбираются каждый по-своему:

// Second run, after a restart. The gate is closed after `start`: commands return NotReconciled.
let (ud, mut events) = start_ud(cfg).await?;
// Subscribe BEFORE the reconcile: an event between the snapshot and the subscription would be lost.
ud.subscribe_order_state().await?;

// The journal says which orders the bot thinks are alive.
let report = ud.reconcile(&journal).await?;
for order in &report.confirmed {
    println!(
        "confirmed {}: still at the broker, filled {}",
        order.cid,
        order.filled.decimal()
    );
}
for cid in &report.closed_offline {
    // Find out how it ended: order_state(cid) and executions(...), then write it to the journal.
    println!("closed offline {cid}: ask order_state and write the result");
}
for order in &report.foreign {
    // Not ours. Do not touch: a person decides.
    println!("foreign {}: shown to a person", order.cid);
}

# After a restart the gate is closed: commands raise NotReconciled.
# Subscribe BEFORE the reconcile: an event between the snapshot and the subscription would be lost.
await client.subscribe_order_state()

# The journal says which orders the bot thinks are alive.
report = await client.reconcile(ledger)
for order in report.confirmed:
    print(f"confirmed {order.cid}: still at the broker, filled {order.filled}")
for cid in report.closed_offline:
    # Find out how it ended: order_state(cid) and executions(...), then write it to the journal.
    print(f"closed offline {cid}: ask order_state and write the result")
for order in report.foreign:
    # Not ours. Do not touch: a person decides.
    print(f"foreign {order.cid}: shown to a person")

Первая торговая команда идет только после этого. Сначала подписка, потом сверка, потом заявка, а до сверки заявка получает NotReconciled:

ud.subscribe_order_state().await?; // before the reconcile, or an event in between is lost
let report = ud.reconcile(&journal.live()).await?; // an empty slice for a bot without a journal
// report.confirmed, report.closed_offline, report.foreign: handle them (see the lifecycle page)
ud.place(request).await?; // before the reconcile this is Error::NotReconciled

await client.subscribe_order_state()  # before the reconcile, or an event in between is lost
report = await client.reconcile(journal.live())  # an empty list for a bot without a journal
# report.confirmed, report.closed_offline, report.foreign: handle them (see the lifecycle page)
await client.place(cid=brokapi.new_cid(), instrument=instrument, side=brokapi.Side.BUY, qty=qty, price=price)
# Before the reconcile the line above raises brokapi.NotReconciled.

Порядок на схеме такой: бот поднимает UD (шлюз закрыт), подписывается на статусы, берет из журнала cid живых заявок, зовет reconcile, получает три списка, шлюз открывается, итоги идут в журнал.

%%{init: {'sequence': {'width': 90, 'actorMargin': 30, 'mirrorActors': false}}}%%
sequenceDiagram
  participant J as Журнал бота
  participant Bot as Бот
  participant UD as UD, коннектор счета
  participant Br as Брокер
  Bot->>UD: start, шлюз закрыт
  Bot->>UD: подписка на заявки и сделки
  J->>Bot: cid живых заявок
  Bot->>UD: reconcile(cid)
  UD->>Br: заявки счета
  Br-->>UD: список
  UD-->>Bot: три списка
  Note over UD: шлюз открыт
  Bot->>J: итоги в журнал

Если reconcile вернул ошибку (нет связи, лимит), он не открыл шлюз: подождите и вызовите еще раз. Ошибка при этом ничего не говорит о заявках, сверка просто не состоялась. Пока шлюз закрыт, ставить заявки нельзя, и это правильно: бот все еще не знает, что стоит на счете.

Почему порядок именно такой

Пошаговая инструкция - на странице Запуск, рестарт и остановка бота. Здесь причины:

• Подписка идет до сверки. Сверка делает снимок счета в одно мгновение. Событие, которое пришло между снимком и подпиской, иначе было бы потеряно: в снимке его еще нет, а подписка его уже не получит. Подписки при закрытом шлюзе разрешены именно поэтому.
• Список cid берется из журнала бота. Только бот знает, какие заявки он считал живыми. Библиотека не пишет на диск, и без этого списка она не отличит ваши заявки от чужих.
• reconcile только читает, поэтому его можно вызывать в любой момент и сколько угодно раз. Он не снимает и не меняет заявок. Единственное, что он меняет, - состояние шлюза.
• Сверка не открывает шлюз при ошибке. Если часть списка не прочиталась, результат нельзя считать полным.

Как сверка устроена у брокеров

Список БКС ограничен: в нем только заявки с 26 января 2026 года и не больше 1000 последних (ограничение документации БКС). Поэтому живая заявка может в нем не оказаться, и именно поэтому судьбу заявки из вашего списка решает GET, а список нужен только для foreign. Окно поиска списка заканчивается на сутки позже локальных часов: часы машины могут отставать от брокерских, и свежая заявка не должна выпасть.

Стоп-заявки

Обычная сверка стоп-заявки не показывает: ни в confirmed, ни в foreign. cid стоп-заявок в ваш список для reconcile класть не надо: они попадут в closed_offline, потому что среди обычных живых заявок их нет. Для стопов после старта вызывайте active_stop_orders() (см. Стоп-заявки). У Т-Банка после рестарта cid в этом списке пустой, снимать стоп можно только по номеру брокера.

Что хранит бот, а что нет

Библиотека не ведет журнал на диске и не восстанавливает состояние сама. Она дает основу для этого: полный упорядоченный поток событий (каждый переход состояния заявки - событие), cid в каждом событии заявки и сверку, которая сравнивает список бота со счетом.

Когда звать reconcile, кроме старта (после Overflow, после долгого обрыва, при сомнении в журнале): Если что-то пошло не так.

Лимиты запросов

Брокеры ограничивают число запросов и на превышение отвечают отказом. Чтобы не получать отказы в самый неудобный момент, библиотека считает запросы сама и до отправки: если квоты нет, запрос не уходит в сеть вообще. Счетчик один на ту область, где брокер считает квоту (Карта), а область у каждого брокера своя: Несколько счетов и брокеров.

Как устроен счетчик

Счетчик (BrokerLimiter) - это набор «ведер» (token bucket). У каждого ведра три параметра: скорость пополнения (rate запросов за per) и размер (burst). Ведро стартует полным и пополняется равномерно, а не шагами. Один запрос тратит одну единицу. Тихий клиент может отправить burst запросов сразу, занятой удерживается на rate.

Каждый метод API привязан к одному или нескольким ведрам (маршрут). Например, у БКС и Финама:

PlaceOrder  = ["global", "orders"]
CancelOrder = ["global", "cancel"]

Постановка тратит общее ведро global и ведро заявок, отмена - общее и свое. Ведро global общее для всех методов брокера: оно же защищает от суммарного превышения, а отдельные ведра - от перекоса внутри.

Что происходит при вызове

1. Коннектор берет из ведер маршрута по одной единице. Если одного ведра не хватило, уже взятые единицы возвращаются: частично потраченная квота не пропадает.
2. Ведер хватило - запрос уходит к брокеру.
3. Не хватило - вызов сразу возвращает RateLimited { retry_after }, в сеть ничего не ушло.

Счетчик никогда не ждет сам, ждать должен бот. Ожидание внутри вызова скрыло бы задержку от бота и держало бы очередь по бумаге (Круг команд), а решение «подождать, пропустить или отказаться» принадлежит боту. Что делать с RateLimited: Ошибки и что с ними делать.

retry_after - подсказка, сколько ждать до следующей попытки. Это не обещание, что следующий вызов пройдет: другое ведро маршрута может пополняться дольше.

Метод без маршрута (например, вызванный через raw(), см. raw) тратит общее ведро брокера (маршрут "*"). Бесплатных вызовов нет: иначе один неучтенный метод мог бы исчерпать настоящую квоту брокера и вызвать отказы у всех остальных.

Почему отмена в отдельном ведре

Отмена не должна ждать за потоком постановок: если заявка ушла не туда, снять ее нужно именно тогда, когда бот ставит много. Поэтому у отмены свое ведро (cancel у БКС и Финама, order_cancel у Т-Банка), а ведро заявок (orders, у Т-Банка order_post) меньше общего. Поток постановок упирается в него раньше, чем исчерпает global, и для отмены остается место в обоих ведрах.

У этой защиты есть граница: отмена тоже тратит global. Если исчерпать его чтением (стаканы, справочник, история), отказ получит и отмена. Поэтому читайте с запасом и не гоните массовые запросы справочника в то время, когда в рынке стоят ваши заявки.

Свои числа: формат файла

Файл лимитов - TOML: ведра (rate запросов за per, запас burst), маршруты методов к ведрам и квоты соединений. Раздел называется по брокеру ([bcs], [tbank], [finam], [alor], [bybit]) или как угодно, если читать общей функцией.

[bcs.buckets.orders]
rate = 10          # запросов за период
per = "1s"
burst = 3          # сколько можно потратить сразу
[bcs.route]
"*" = ["orders"]   # метод без своего маршрута (см. выше)
PlaceOrder = ["orders"]
[bcs.conns]
max_conns = 4
max_subs_per_conn = 50
supports_multiplex = false

Читают его brokapi::bcs::limits::limits_from_toml_str (и limits_from_toml_path, так же у АЛОРа и Bybit, у Т-Банка brokapi::tbank::limits, у Финама brokapi::finam::limits::parse_limits), либо общая BrokerLimits::from_toml_str из brokapi::runtime, которая берет единственный раздел файла. Дальше BrokerLimiter::new(&limits): он возвращает Arc<BrokerLimiter>, делится он через Arc (.clone() у Arc), а не копией. Полный разбираемый файл, который дает «первая заявка прошла, вторая получила RateLimited». Лишние ключи разбор пропускает: старый файл с dedicated_command_conns читается, ключ ничего не делает (его убрали, потому что ни один коннектор его не читал). retry_after показывает, сколько ведру нужно до одного токена (при per = "2s" порядка 1,8 секунды сразу после траты):

[bcs.buckets.orders]
rate = 1
per = "2s"
burst = 1
[bcs.route]
"*" = ["orders"]
PlaceOrder = ["orders"]
[bcs.conns]
max_conns = 4
max_subs_per_conn = 50
supports_multiplex = false

Рабочий пример малого бюджета, чтобы поймать RateLimited, - small_budget в examples/research.rs. burst = 0 не пропускает ничего никогда, а retry_after в этом случае все равно показывает период: ведро не пополнится само. Чтобы получить «один раз отказали, потом прошло»: burst = 1 и длинный per, первый вызов проходит, второй сразу получает RateLimited.

Откуда числа

Из файлов limits.toml в каталогах крейтов (crates/bcs, crates/tbank, crates/finam, crates/alor, crates/bybit). Каждый файл встроен в свой крейт и доступен как limits::default_limits() (у всех одинаково). Свои числа можно загрузить из строки или файла (limits_from_toml_str, limits_from_toml_path, у Финама parse_limits).

Это осторожные значения, и они разной надежности:

• Т-Банк публикует свои лимиты, они взяты из документации (в ней же сказано, что реальные значения динамические и их возвращает GetUserTariff).
• Финам называет одну цифру на весь API: 200 запросов в минуту. Остальное выбрано ниже этой цифры.
• АЛОР публикует 100 HTTP-запросов в секунду на пользователя, 10 соединений WebSocket, 5000 подписок на соединение и 5000 необработанных сообщений в буфере соединения. Ведро на 100 в секунду для всех методов и мягкое ведро place на 60 для постановки, замены и стоп-заявки (запас для отмены). Защиту «социальный рейтинг» (баллы за действия, блокировка логина на 2 часа) брокер описывает без порогов, коннектор их не считает.
• БКС публикует таблицу: 10 запросов в секунду на каждый сервис, 3 для неторговых операций (история операций), для
• Bybit публикует лимиты на пользователя и метод (10 запросов в секунду на создание, изменение, отмену и «снять все», 50 на чтения) и на адрес (600 запросов за 5 секунд, сверх этого HTTP 403 и бан адреса на 10 минут). Библиотека держит ведро на каждый вид команды и общее ведро адреса на 100 в секунду. Заголовки остатка лимита (X-Bapi-Limit-Status) она не читает, счет ведется у нее самой. сервиса заявок еще 200000 запросов в сутки. Ведро на сервис, всплеск 10 (одна секунда), для постановки заявки еще мягкие ворота на 8 в секунду (не лимит брокера: поток заявок не съест весь бюджет сервиса и отмене остается место), суточное ведро считает только то, что отправил этот процесс. Как БКС считает секунду и сутки (окно или скольжение, календарные сутки или 24 часа), в документации не сказано.

Занижать безопаснее, чем завышать: лишнее ожидание стоит секунд, а отказ брокера приходит на боевом счете в произвольный момент.

Квоты соединений

Счетчик хранит и квоты соединений (ConnQuota): сколько соединений и подписок на соединение допускает брокер. Он их только хранит. Коннектор решает, что с ними делать. Сейчас это использует Финам: число одновременных потоков ограничено, и при превышении подписка получает Rejected с кодом subscription_quota.

Деньги, цены и количества

Цена, количество, лот, баланс и комиссия в библиотеке - точные десятичные числа. f64 для них нигде не используется. Страница объясняет, почему так, как создавать числа, как округлять цену до шага и что делает библиотека при переводе форматов брокеров.

Python. Цена, количество и деньги - decimal.Decimal. В вызов можно передать Decimal, int или строку, float отвергается с TypeError. Округление до шага - brokapi.round_to_step(цена, шаг, RoundMode.DOWN), правила те же, что у round_to_step в Rust. Время - datetime с часовым поясом.

Три типа

Внутри у каждого Decimal (крейт rust_decimal): целое на 96 бит и до 28 знаков после запятой. Типы разные нарочно: количество нельзя подставить вместо цены, а сумму в рублях вместо количества. Библиотека отдает Decimal и макрос dec! из brokapi_core.

Почему не f64

Брокеры присылают цены десятичными числами, и сетка биржи тоже десятичная. В двоичной дроби 244.3 не лежит ровно:

assert_ne!(0.1_f64 + 0.2, 0.3);          // 0.30000000000000004
assert_ne!(244.3_f64 % 0.01, 0.0);       // остаток 6.3e-15: цена «не на шаге»
assert_ne!((109.32_f64 / 0.01).fract(), 0.0); // 10931.999999999998 шагов

Для заявки это значит: цена, которая на бирже верная, у вас «не кратна шагу», а округление до шага уезжает на одну копейку. Суммы портфеля набегают копейками. С Decimal те же числа точные: 0.1 + 0.2 == 0.3, 244.3 кратно 0.01.

Эталон, NautilusTrader, хранит цену, количество и деньги целыми числами с фиксированным масштабом. Мы взяли другое: Decimal со своим масштабом у каждого числа. Брокеры дают разное число знаков (Т-Банк до девяти, БКС до восьми у цены, Финам строку любой длины), и один общий масштаб либо режет цену, либо сужает диапазон. Скорость целых нам не нужна: это слой подключения, а не движок, между числом и биржей сетевая задержка в миллисекунды.

Как создать число

use brokapi::core::{Decimal, Price, Qty, dec};

let a = Price::new(dec!(250.15));            // из литерала
let b: Price = "250.15".parse()?;            // из текста: файл, форма, переменная окружения
let c = Price::from(250);                    // из целого
let d = Price::from_scaled(25015, 2);        // из мантиссы и числа знаков: 250.15
assert_eq!(a, b);

let lots = Qty::from(10);
let sum: Qty = [Qty::from(1), Qty::from(2)].into_iter().sum();

• Запятая не разделитель: "12,5" - ошибка разбора (NumberError::Parse).
• Числа сравниваются по значению: Price 244.30 равно 244.3. А текст сохраняет запись: 244.30 печатается 244.30.
• Price * Decimal дает Price (так считается «на 1% ниже»: bid * Decimal::new(99, 2)). Масштаб произведения больше: 244.30 * 0.99 печатается 241.8570. После round_to_step до шага 0.01 значение 241.85, а печать может быть 241.8500: значение то же, масштаб записи не важен.
• Из f64 число делается только явно и с округлением до заданного числа знаков: Price::from_f64_lossy(244.3, 2). Имя говорит, что точность потеряна: f64 уже принес двоичный шум, округление его только прячет. Обратно - to_f64_lossy(), для графика или строки лога, но не для цены заявки.
• В JSON число - строка: "244.30". Так его не округлит ни один читатель.

Как округлить до шага цены

Шаг цены и размер лота лежат в TradingParams (Справочник API). Округление точное, сетка начинается с нуля:

use brokapi::core::{Price, RoundMode, dec};

let step: Price = "0.05".parse()?;
let p: Price = "101.03".parse()?;
assert_eq!(p.round_to_step(step, RoundMode::Down)?, "101.00".parse()?);     // покупка: не дороже расчета
assert_eq!(p.round_to_step(step, RoundMode::Up)?, "101.05".parse()?);       // продажа: не дешевле расчета
assert_eq!(p.round_to_step(step, RoundMode::Nearest)?, "101.05".parse()?);  // ближайшая, половина - от нуля
assert!(p.round_to_step(step, RoundMode::Up)?.is_on_step(step));

Если параметры инструмента уже прочитаны (trading_params), короче так: params.round_price(price, mode) и params.round_qty(qty, mode). Нулевой или отрицательный шаг - ошибка NumberError::StepNotPositive.

Проверка цены коннектором

Коннектор не знает шаг сам: он узнает его от вас. У каждого коннектора заявок есть price_grid(). Заполните его один раз на инструмент:

let params = md.trading_params(&sber).await?;
ud.price_grid().learn(&params);

Дальше place, replace и place_stop проверяют цену заявки (и stop_price, limit_price). Цена не на шаге - Rejected с кодом price_off_step, до отправки: квота не тратится, cid остается свободным. Если шаг инструменту не передан, цена не проверяется, решает брокер. Таблицу можно задать и при создании: поле price_grid конфига UserDataConfig, одну на несколько коннекторов (копии таблицы - один и тот же список).

Количество проверяется так же и по той же таблице: price_grid().learn(&params) запоминает и шаг цены, и размер лота. Количество, которое не является целым числом лотов, это Rejected с кодом invalid_qty, до отправки. Если размер лота инструменту не передан, количество с лотом не сверяется, решает брокер (у Т-Банка лот коннектор читает сам, см. ниже). Нуль, отрицательное и дробное количество отказывают всегда, где брокер берет только целые. Ничего не округляется: округленная заявка купила бы не то, что вы просили.

Количество: единицы инструмента, не лоты

Qty везде значит число единиц инструмента: штук акций, облигаций, единиц валюты, контрактов. Одно и то же в заявке, в уровне стакана, в сделке рынка, в исполнении, в позиции и в объеме свечи, у любого брокера. Так же считает NautilusTrader и сама биржа. Брокер, который считает лотами (Т-Банк), переводится коннектором в обе стороны: ваш код лотов не видит.

Что такое лот и единица на разных рынках:

Правила, одинаковые для всех:

• Количество заявки положительное и кратное лоту. Иначе Rejected с кодом invalid_qty, ничего не отправлено, cid не потрачен.
• Лот узнается из TradingParams::lot_size (в единицах), минимальное количество min_qty равно одному лоту.
• Позиция, сделка и объем свечи приходят в единицах так, как их присылает брокер, коннектор пересчитывает только то, что брокер считает лотами.

Что делает каждый коннектор:

Как числа переводятся из формата брокера

Ни один путь не идет через f64. Что делает каждый коннектор:

Что именно сохраняется: 244.30 не теряет нуль на конце, 0.0001 остается 0.0001, число с 19 знаками не обрезается. Это проверено тестами на всех форматах, в том числе случайными числами туда и обратно.

Проценты в моделях БКС (доля в портфеле, доходность, изменение в процентах, ставка купона) - это отношения, а не деньги, цены или количества: поэтому они f64. Деньги и цены в brokapi-bcs-protocol - Decimal.

Брокеры

Общий интерфейс одинаков для всех брокеров, но сами брокеры отличаются. Эта страница - сводка различий, дальше по странице на каждого: БКС, Т-Банк, Финам, АЛОР, Bybit. Bybit - зарубежный сервис, остальные - российские брокеры.

Что общее у всех

• Два коннектора: MD и UD. UD на один счет (у АЛОРа на один портфель, у Bybit на один счет или субсчет ключа).
• cid бота и правила заявок одинаковы (Круг команд). Меняется только то, куда cid кладется.
• Все ответы на неясные команды - Unknown, повторов нет.
• Стакан приходит полным снимком (у Bybit коннектор сам собирает его из снимка и изменений и отдает целиком).
• Шлюз команд после запуска закрыт до reconcile, и закрывается снова при Overflow и при Reconnected (оборвался поток своих заявок или исполнений), и команда, которая стояла в очереди, проверяется шлюзом еще раз.
• Ошибки одного вида: отказ токена это Config, “не найдено” это Rejected с кодом not_found, идентификатор инструмента другого брокера это Config без сети.
• raw() у каждого коннектора.

Что у брокеров устроено по-разному

• Счета. У БКС счет задает токен, у Т-Банка и Финама - account_id, у АЛОРа - портфель и биржа в настройке, у Bybit счет определяет ключ.
• Лимиты. У каждого брокера своя область, см. Несколько счетов и брокеров.
• Единицы количества. Одинаковые: Qty это число единиц инструмента (штуки, контракты), лотов бот не видит ни у одного брокера. Т-Банк и АЛОР считают лотами, коннектор переводит. Размер лота дает TradingParams::lot_size, заявка кратна ему (Деньги, цены и количества).
• Что не поддерживает брокер. Помечено на странице брокера. Такие вызовы возвращают Unsupported сразу, без сети.

БКС

Крейты: brokapi-bcs-protocol (REST и WebSocket клиент) и brokapi-bcs (коннекторы).

Вход

Где взять токен

Токен выпускает человек, чей это счет (правило 0). Нужен хотя бы один брокерский счет в БКС Мир инвестиций. Шаги по документации БКС:

1. Войти в веб-версию БКС Мир инвестиций (lk.bcs.ru).
2. Открыть «Профиль», под заголовком «Счета и тарифы» нажать на брокерский счет, к которому нужен доступ.
3. В настройках счета выбрать «Токены API», нажать «Выпустить токен» и следовать инструкциям.
4. Скопировать токен и сохранить сразу: брокер показывает его один раз.

Какой токен выбрать. Токены бывают двух видов: «для торговли и чтения данных» и «только для чтения». Для первого запуска возьмите «только для чтения»: им работают портфель, стакан и свечи, а заявку брокер не примет. Токен для торговли нужен, когда человек решил поставить первую боевую заявку, и тогда же включается BCS_IS_WRITE=true.

Сколько живет и как отозвать. Refresh-токен действует 90 суток, токен доступа из него 24 часа (его получает коннектор). Токен привязан к одному счету, одновременно действующих токенов можно выпустить сколько угодно. Удалить токен можно в тех же «Токенах API». После удаления токена для торговли его токен доступа перестает работать сразу, у токена «только для чтения» может работать до 24 часов. Номер счета в настройках не нужен: счет определяет токен.

Идентификатор инструмента

NativeId::TickerClass { ticker, class_code }, например SBER и TQBR. Ключ библиотеки - SBER@TQBR. Любой другой вид идентификатора даст ошибку настройки (Config): справочник для БКС не нужен, идентификатор собирается сам без сети. Расписание торгов у БКС по инструменту: в schedule передается "SBER@TQBR", иначе Config.

Единицы и стакан

Как устроены команды

БКС работает синхронными методами: POST /orders/sync, /orders/cancel/sync, /orders/edit/sync. Они ждут решения брокера и отвечают состоянием заявки. Из этого следует:

• Отказ известен сразу как Rejected, а не через минуту из потока. Отказ может прийти кодом HTTP 4xx или внутри ответа 200 со статусом заявки 8 и причиной. Оба случая дают Rejected.
• В OrderAck приходит настоящий номер брокера (orderId), тот же, что в списке заявок и в потоке.
• Отмена объявляется успешной, только если брокер ответил, что заявка отменена (статус 4). Заявка исполнилась раньше - Rejected { already_filled }. Ответ оставил заявку живой - Unknown. Статус 6 «Отменяется (в процессе отмены)» это не отмена: заявка еще в стакане и может исполниться. В потоке и в ответах он приходит как состояние Unknown (не Cancelled), cancel() возвращает Unknown, сверка считает такую заявку живой. Cancelled придет со статусом 4, Filled - если заявка исполнилась.
• Прежние формы запросов (с номером заявки в пути) коннектор не вызывает. Они остались в brokapi-bcs-protocol и доступны через raw().

Как cid уходит к брокеру

В поле clientOrderId как UUID с дефисами. Обратимо. В списке активных заявок БКС поля clientOrderId нет, только номер брокера. Поэтому active_orders и reconcile определяют cid так: по тому, что процесс видел сам, иначе одним запросом на каждую неизвестную заявку (по ее номеру), иначе дают заявке подставной cid. Если на счете много чужих заявок, сверка тратит много запросов, учитывайте квоту.

Порядок как у Т-Банка и Финама: шлюз команд, проверка входа, квота, очередь по бумаге, шлюз еще раз и только потом cid помечается использованным. Поэтому после RateLimited (и после ошибки входа вроде missing_price) тот же cid годен: заявка никуда не ушла. То же для place_stop. Общее правило: Круг команд.

Сообщение канала orders/events/ws несет два идентификатора: clientOrderId (по документации идентификатор заявки, в примере для исполнения он пустой) и originalClientOrderId (идентификатор измененной заявки). cid берется так: если один из них не UUID, то другой. Если оба UUID и сообщение об отмене, замене или отмене в процессе (статусы 4, 5, 6), то originalClientOrderId, иначе clientOrderId. Так сообщение об отмене, где clientOrderId это номер запроса на отмену, попадает на ту заявку, которую отменили, а не на чужой cid. Какой идентификатор в каком поле приходит для каждого вида сообщения, взято из документации БКС. Исправление (executionType 13) не создает новое исполнение: оно пересказывает прежнее сообщение, настоящую поправку сделок дает история (executions). Ошибка подписки на рыночные данные не содержит подписки, только код и текст: она валит ту подписку, чей тикер назван в тексте, а если подписка одна в ожидании, то ее. Если по тексту не понять, ошибка валит все ожидающие.

Изменение заявки

Есть: POST /orders/edit/sync, брокер снимает исходную заявку и ставит новую под новым cid. Количество и цена, которых вы не указали, берутся от исходной (один запрос). Если заявка исполнена частично, количество нужно указать явно, иначе Rejected { qty_required }.

Свои сделки, портфель

Стоп-заявки

Условные заявки (orderType = 5). Принимается только срок «до отмены» (срок жизни условной заявки документация не описывает), поле срока не отправляется. Направление срабатывания выбирает брокер. Пара «стоп-лосс плюс тейк-профит» не создается. Потока статусов нет. Подробно: Стоп-заявки.

Чего БКС не поддерживает или делает иначе

Лимиты

crates/bcs/limits.toml, по таблице «Ограничения» из документации брокера: у каждого сервиса свое ведро на 10 запросов в секунду (портфель, лимиты, справочник, заявки, статус заявки, сделки, дисконты, рыночные данные), у неторговых операций (история операций) 3 в секунду, у заявок еще суточное ведро на 200000. Заявка, отмена, замена, стоп-заявка и список заявок тратят общее ведро сервиса заявок. До 4 соединений (канал заявок). Всплеск 10, то есть одна секунда. Постановка, замена и стоп-заявка проходят еще через ведро place на 8 в секунду (всплеск 4): это не лимит брокера, а запас, чтобы поток заявок не занял весь бюджет сервиса и отмене осталось место. Как БКС считает секунду (фиксированное окно или скользящее) и сутки (календарные или 24 часа), в документации не сказано: если упретесь в RateLimited раньше времени, уменьшите значения в limits.toml. Суточное ведро считает только этот процесс: на одном счете из двух процессов оно не видит общего числа.

Что учесть

1. Количество в уровнях стакана и ленты в документации БКС не названо. Для расчета объема сверяйтесь с количеством в своей заявке.
2. Если на запрос заявки по неизвестному cid БКС ответит не NOT_FOUND, сверка отнесет заявку к неопределенным. Проверьте это на минимальной заявке.
3. Суточный лимит на заявки считает только ваш процесс. Два процесса на одном счете его не видят совместно.

Т-Банк

Крейты: brokapi-tbank-protocol (gRPC клиент, собранный из официальных .proto) и brokapi-tbank (коннекторы). С песочницы Т-Банка рекомендуется начинать: Перед боевым счетом.

Вход

Где взять токен и счет

Токен выпускает человек, чей это счет (правило 0). Шаги по документации Т-Банка:

1. Открыть настройки профиля Т-Инвестиции на компьютере (с телефона страница может переадресовать в приложение, где раздела токенов нет) и войти. Выпустить токен можно только на сайте tbank.ru. Если страница не открывается, нужны сертификаты НУЦ Минцифры или Яндекс Браузер.
2. Убедиться, что «Подтверждение сделок кодом» выключено: по документации Т-Банка оно должно быть отключено. Сделки на сумму больше 30 000 000 рублей требуют подтверждения и через API недоступны.
3. Выпустить токен T-Invest API для биржи и/или для песочницы. Система может попросить войти еще раз.
4. Скопировать токен сразу: его показывают один раз, позже получить его нельзя.

Какой токен выбрать. Виды: только чтение, полный доступ, токен для переводов между счетами (его не берите), токен с доступом к одному счету (права чтения или полного доступа настраиваются) и токен песочницы. Для первого запуска возьмите токен песочницы (быстрый старт на Python). Для чтения боевого счета берите токен «только чтение». Токен с полным доступом нужен, когда человек решил поставить первую боевую заявку, и лучше с доступом к одному счету. Токен песочницы к боевому адресу не подойдет.

Номер счета. Если токен выпущен для одного счета, TBANK_ACCOUNT_ID задавать не нужно: берется его единственный открытый счет. Если токен на все счета и счетов несколько, коннектор не запустится и просит указать счет. Для Инвесткопилки, Счета под ключ и Смарт-счета токен «на один счет» выпустить нельзя, у них только токен на все счета. Где в кабинете смотреть номер счета, документация Т-Банка не говорит: в Rust список счетов дает TbankClient::list_accounts.

Счет песочницы. Токен песочницы сам счета не открывает. Счет создает вызов OpenSandboxAccount, пополняет SandboxPayIn (только рубли, до 30 000 000 рублей), счета живут 3 месяца с последнего использования. В Rust это методы sandbox()-клиента (crates/tbank/tests/live_sandbox.rs), в Python и Gateway готовых команд нет, остается raw или любой другой клиент T-Invest API.

Срок. Новый токен надо начать использовать в течение 7 дней после выпуска, иначе его отзовут. Токен живет три месяца с даты последнего использования. Ответ 40003 значит, что токен неактуален. Посмотреть и отозвать токены: настройки безопасности, блок «Приложения, у которых есть доступ к данным для входа».

Идентификатор инструмента

Коннектор принимает любую из трех форм:

Ключ библиотеки - SBER@TQBR. Найти инструмент и его uid: md.find(InstrumentQuery::ByTicker { .. }). Событие потока несет тот InstrumentId, который вы указали при подписке.

Единицы и стакан

Как cid уходит к брокеру

В поле order_id запроса PostOrder. По документации Т-Банка это ключ идемпотентности «в формате UID, до 36 символов». UUID с дефисами занимает ровно 36, поэтому влезает без потерь. Тот же ключ брокер возвращает как order_request_id в ответе и потоке, а CancelOrder и GetOrderState принимают его с типом идентификатора «запрос».

Идемпотентность не используется: что сервер делает с повторным ключом, никто не измерял (LabelOnly, вопрос 1 ниже). Библиотека place сама не повторяет в любом случае.

Заявка, поставленная не вами (с телефона, другим роботом), приходит без order_request_id. Чтобы она могла попасть в foreign, коннектор выдает ей подставной стабильный cid, вычисленный из номера заявки на бирже.

Ответы брокера

Номер ошибки Т-Банка (пятизначный, из таблицы ошибок) коннектор читает из текста статуса, а если там пусто, из начала заголовка message. Статус RESOURCE_EXHAUSTED у Т-Банка не всегда означает лимит запросов: так же отвечает про лимит стоп-заявок по инструменту. Поэтому его различают по номеру. Номер, которого нет в таблице, остается лимитом запросов.

Изменение заявки

ReplaceOrder. Нужны биржевой номер и количество исходной заявки: берутся из того, что коннектор уже знает, иначе один запрос GetOrderState. Цена не указана - берется цена исходной. Новый cid становится ключом идемпотентности. Биржевой номер после замены может измениться, ориентируйтесь на cid.

Свои сделки, портфель

Справочник

• find по тикеру и ISIN: быстрый поиск (запись короткая, поле currency пустое, нужную валюту берите через get).
• find(ByKind): списки акций, облигаций, ETF, фьючерсов, опционов, валют (базовый список, торгуемое через API). Запросы тяжелые, у них свое ведро лимитов (15 в минуту), кеша нет. Для опционов используется метод, помеченный как устаревший: если Т-Банк его уберет, станет Unsupported.
• MutualFund и Other: Unsupported.
• price_step_value равен шагу цены. Для фьючерсов стоимость шага в деньгах не вычисляется.

Стоп-заявки

Отдельный сервис стоп-заявок: PostStopOrder, GetStopOrders, CancelStopOrder. Срок: «до отмены» и «до даты». «До конца дня» нет. Количество в штуках, как у заявок (брокеру уходят лоты). Брокер не возвращает cid стоп-заявки. Связь с номером хранится в памяти процесса, после рестарта в списке cid пустой и снимать стоп нужно по номеру брокера. Потока статусов в API нет. Длинный список. Брокер не отдает слишком много стоп-заявок в одном ответе: ошибка 30261 «ограничьте запрос параметрами from и to». active_stop_orders сначала просит весь список, а на 30261 делит период от 1970 до 2099 года пополам, пока каждый кусок не поместится, и склеивает ответы (повтор заявки на стыке отбрасывается по номеру). Это тратит запросы GetStopOrders (60 в минуту, всплеск 10 в crates/tbank/limits.toml): если квота кончилась посреди чтения, будет RateLimited, а читать придется заново. При длинном списке поднимите burst ведра stop_orders_get. Не больше 40 запросов за чтение, дальше Rejected { code: "stop_orders_response_limit" }: снимите лишние стоп-заявки. По какому времени заявки (создания, срока) брокер отбирает период и сколько заявок помещается в один ответ, документация не говорит. Потерянный ответ. Если place_stop кончился Unknown, а стоп у брокера есть, cid в списке не вернется сам: брокер его не отдает. Коннектор запоминает, что просили (бумага, сторона, вид, лоты, цена активации, цена заявки) и когда отправил, и при следующем active_stop_orders дает стопу этот cid, если подходит ровно один стоп без cid и создан он, пока запрос был в пути (плюс-минус 10 секунд на расхождение часов). Два одинаковых ожидания или два подходящих стопа (один может быть чужой) - cid не назначается. Это опирается на create_date стопа в списке брокера: как Т-Банк его пишет, вживую не проверено. Если cid не вернулся, стоп с cid: None на той же бумаге и в ту же сторону не считайте отсутствующим. Повтор запроса с тем же order_id библиотека не использует: ключ ли это идемпотентности для стопов, неизвестно. Подробно: Стоп-заявки.

Чего Т-Банк не поддерживает или делает иначе

Лимиты

Т-Банк считает лимиты на пользователя: на все счета и все токены вместе. Поэтому счетчик один на программу. В crates/tbank/limits.toml значения из документации брокера, отмена вынесена в отдельное ведро. Реальные значения отдает GetUserTariff и заголовки x-ratelimit-*: их можно проверить через raw(). До 11 одновременных соединений, до 300 подписок в одном потоке рыночных данных.

Что учесть

1. Повтор order_id: что сделает Т-Банк (вернет прежний отчет, ошибку или примет вторую заявку), в документации не сказано. Коннектор повторов не делает, поэтому на вас это не влияет, но свой код на повтор order_id не закладывайте.
2. Единицы количества в потоке своих сделок - штуки (по описанию протокола).
3. Номер биржевой заявки после ReplaceOrder может измениться. Ориентируйтесь на cid.

Финам

Крейты: brokapi-finam-protocol (gRPC клиент по официальным .proto и менеджер токенов) и brokapi-finam (коннекторы). Песочницы у Trade API нет: любая проверка идет на настоящем счете, см. Перед боевым счетом.

Вход

Где взять секрет и номер счета

Секрет выпускает человек, у которого счет в Финаме (правило 0). Секрет Trade API и номер счета берутся в кабинете Финама, в разделе про Trade API (токены или ключи доступа). Пошагового описания кабинета в документации Trade API, на которую мы опираемся, нет, поэтому порядок кнопок здесь не приводится: ищите раздел API в кабинете. Что известно из самой документации:

• Секрет обменивается на короткоживущий JWT (метод Auth), коннектор делает это сам. Метод TokenDetails показывает срок токена, доступ к рыночным данным и список счетов секрета. Номер счета для FINAM_ACCOUNT_ID берется из этого списка, в примерах документации он выглядит как A12345. Счет не из списка - Config при старте.
• В TokenDetails есть признак readonly: сессия и счета секрета помечаются «только чтение». Если кабинет позволяет выпустить такой секрет, для первого запуска берите его: портфель, стакан и свечи работают, заявку брокер не примет. Секрет с правом торговли нужен, когда человек решил поставить первую боевую заявку.
• Песочницы нет, поэтому после чтения идет первый день на боевом счете.

Первый день на Финаме

У Финама нет песочницы, и любая проверка идет на настоящем счете. План на первый день, от безопасного к боевому. Каждый шаг начинается, когда прошел предыдущий, а шаги 3 и 4 - только со слова владельца счета.

1. Имитация. Весь код сначала проходит на brokapi.testing.mock_finam(): быстрый старт на Python, там first_order работает с клиентом любого брокера.
2. Чтение боевого счета. FINAM_SECRET (лучше только для чтения) и FINAM_ACCOUNT_ID, затем connect("finam"), portfolio(), order_book(...). Неверный секрет или чужой счет видны на connect (Config). Заявок на этом шаге нет.
3. Минимальная заявка далеко от рынка и отмена. Один лот (trading_params(...).lot_size), цена в 90% от лучшей покупки, округленная вниз до шага. Если биржа отвергла цену как выходящую из допустимого коридора, подвиньте ее ближе к рынку на 5% и повторите с новым cid.
4. Проверка, что комментарий вернулся. Библиотека кладет полный cid в комментарий заявки, а Финам должен вернуть его без изменений (Как cid уходит к брокеру). От этого зависит reconcile: если комментарий искажен, ваши заявки придут как чужие, а бот не узнает свою заявку после рестарта. Проверка: поставить заявку, закрыть клиента (заявка остается на бирже), открыть нового и сверить его с журналом из одного cid. Заявка должна оказаться в confirmed, а foreign остаться пустым.

async def first_day(connect: Callable[[], Awaitable[brokapi.Client]]) -> bool:
    """Places one lot far below the market, 'restarts' the bot and checks that the broker gave the order back as ours.

    `connect` makes a client of the account. Returns True when the comment of the order came back and the order was
    cancelled. Anything else is a reason to stop: do not trade on this account until it is clear."""
    first = await connect()
    sber = await first.instrument("SBER", "MISX")
    params = await first.trading_params(sber)
    book = await first.order_book(sber, depth=1)
    price = brokapi.round_to_step(book.bids[0].price * Decimal("0.9"), params.price_step, brokapi.RoundMode.DOWN)

    await first.reconcile([])
    cid = brokapi.new_cid()  # in a real bot it is in the journal before the next line
    await first.place(cid=cid, instrument=sber, side=brokapi.Side.BUY, qty=params.lot_size, price=price)
    await first.close()  # the process "dies": the order stays at the exchange

    # The second run knows only the journal: the cid. If Finam gave the comment back untouched, the order is recognised.
    second = await connect()
    try:
        report = await second.reconcile([cid])
        recognised = [order.cid for order in report.confirmed] == [cid]
        print(f"the order {'came back as ours' if recognised else 'was NOT recognised'}: {len(report.foreign)} foreign")
        for order in report.confirmed:
            await second.cancel(order.cid)
        print(f"orders left after the cancel: {len(await second.active_orders())}")
        return recognised and not report.foreign
    finally:
        await second.close()

Программа печатает the order came back as ours: 0 foreign и orders left after the cancel: 0. Любой другой результат - повод остановиться и не торговать на этом счете, пока причина не ясна: сообщите о нем через «Сообщить об ошибке» со строкой вывода (без секрета).

Заявка у Финама всегда «на день», replace нет. Если заявка осталась на счете после остановки бота, ее снимает бот: Аварийная остановка бота.

Идентификатор инструмента

NativeId::SymbolMic, строка SBER@MISX (тикер и код биржи MIC). Ключ библиотеки тот же. Построить идентификатор без сети: brokapi::finam::util::instrument_from_symbol("SBER@MISX"). Любой другой вид идентификатора - Config.

Единицы и стакан

Как cid уходит к брокеру

Поле Финама client_order_id вмещает 20 символов, UUID (128 бит) туда не помещается. Поэтому:

• полный номер кладется в комментарий заявки (до 128 символов) в виде bc1: и 32 символа. Финам возвращает заявку целиком в состоянии и в сделках, и номер читается оттуда.
• в client_order_id идет метка из 20 символов, полученная из UUID. Обратно в UUID она не превращается, это запасной ключ на случай, если комментарий в ответе пропал.

На старте коннектор проверяет, что оба формата вмещаются в поля брокера: иначе это ошибка настройки, а не поломка на ходу. Заявка, поставленная не коннектором (из приложения), получает подставной стабильный cid, и такие заявки попадают в foreign.

Механизм держится на том, что Финам возвращает комментарий заявки без изменений, как сказано в его документации. Если комментарий придет искаженным, сверка не узнает ваши заявки: проверьте это на минимальной заявке до боевого счета.

Ответы брокера

Чтения один раз повторяются после обновления JWT. Команды не повторяются никогда, в том числе после UNAUTHENTICATED: это Config, и новую попытку бот делает сам с новым cid. Обновление JWT при этом запускается, следующий вызов встретит свежий токен.

Заявки

• Срок обычной заявки всегда «на день» (TIME_IN_FORCE_DAY).
• Изменение заявки отсутствует. replace возвращает Unsupported("replace_order") сразу и без сети (caps().supports_replace = false). Отмена и новая заявка не атомарны, поэтому библиотека не подменяет одно другим.
• Отмена и чтение заявки идут по номеру брокера. Номер коннектор запоминает после постановки, иначе ищет по списку заявок счета.
• Статусы брокера переводятся в общие: новая и ожидающие - Acked, частично исполненная - PartiallyFilled, исполненная - Filled, снятая и истекшая - Cancelled, отклоненная - Rejected. Неизвестный статус считается рабочей заявкой.

Свои сделки, портфель

Стоп-заявки

Стоп-лосс и стоп-лимит - обычной заявкой типа стоп (PlaceOrder). Тейк-профит - отдельным методом PlaceSLTPOrder. Особенности: у тейк-профита нельзя задать цену после срабатывания (там защитный спред, вернется Rejected { unsupported_limit_price }), срок «до даты» только у тейк-профита, стоп-заявки не показываются в active_orders и reconcile, cid читается из комментария. Если у чужой SL/TP-заявки единица объема - процент от позиции (sl_qty_measure или tp_qty_measure равны PERCENT), количество в штуках неизвестно и в StopOrderSnapshot::qty стоит 0, а не процент. Свои тейк-профиты коннектор ставит в штуках. Подробно: Стоп-заявки.

Подписки и потоки

Один поток gRPC на подписку, поверх одного соединения HTTP/2 на коннектор. После обрыва поток переоткрывается с паузой от 0,5 до 30 секунд. Подписка, которую сервер отверг (нет прав, нет инструмента), помечается Failed и пробуется снова примерно раз в 30 секунд. Открытие потока тратит квоту, как любой запрос. sub_status(sub) показывает состояние подписки (Connecting, Active, Reconnecting, Failed, Erroring). Когда поток заявок или поток сделок был открыт, оборвался и открылся снова, бот получает Event::Reconnected на эту подписку, и шлюз закрывается до reconcile. Поток счета (портфель) такого события не дает: каждое его сообщение целое состояние.

Чего Финам не поддерживает или делает иначе

Лимиты

Единственная цифра, которую публикует Финам: 200 запросов в минуту. Отдельных лимитов на заявки и на потоки нет. Область лимита (на секрет, пользователя или счет) брокер словами не называет. Считаем, что на пользователя, поэтому счетчик один на программу. Значения в crates/finam/limits.toml заниженные, отмена вынесена в отдельное ведро. Если упретесь в RateLimited раньше времени, уменьшите значения.

Что учесть

1. Комментарий заявки: Финам должен возвращать его без изменений (GetOrders, GetOrder, SubscribeOrders, сделки). От этого зависит reconcile.
2. Повтор client_order_id: что сделает Финам, в документации не сказано. Коннектор повторов не делает.
3. Заголовок JWT уходит как есть. Если сервер откажет, включите FinamApiConfig::bearer.

АЛОР Брокер

Крейты: brokapi-alor-protocol (клиент HTTP и WebSocket: все методы описания API брокера и оба канала WebSocket) и brokapi-alor (коннекторы).

Вход

Где взять токен и портфель

Токен выпускает человек, чей это счет (правило 0). Права у refresh-токена АЛОР не выбираются: по документации брокера он равносилен логину и паролю торгового аккаунта, то есть дает и чтение, и торговлю. Токена «только для чтения» в документации нет, поэтому для первого запуска безопаснее тестовый контур, а на боевом контуре токен хранят как пароль. Шаги по документации АЛОР:

Боевой контур (нужен брокерский счет в АЛОР Брокер):

1. Зарегистрировать учетную запись разработчика на портале alor.dev (кнопка «Зарегистрироваться» на странице входа, подтвердить почту).
2. Открыть страницу «Токены для доступа к API» (alor.dev/open-api-tokens), ввести логин и пароль торгового аккаунта и нажать «Привязать». К одной учетной записи разработчика привязывается один торговый аккаунт.
3. Нажать «Выписать токен», затем «Показать» у нового токена в списке. Он действует год. Токены общие для всех разработчиков, у которых привязан этот аккаунт: отзыв одним отзывает для всех.

Тестовый контур (ALOR_TEST=true):

1. Учетная запись разработчика та же, что выше.
2. Тестовый торговый аккаунт выдает брокер: заявка на support@alor.ru или через личный кабинет lk.alor.ru. К учетной записи разработчика он не привязывается.
3. Refresh-токен тестового контура выписывается со страницы alor.dev/oauth-authorization по ссылке «Begin OAuth authorization flow», вход логином и паролем тестового аккаунта. Одновременно существует один такой токен, он действует месяц.

Портфель. ALOR_PORTFOLIO - номер портфеля вида D12345 (по примерам в документации). Если у токена один портфель, переменную можно не задавать. Если портфелей несколько, коннектор не запустится и просит назвать нужный. Где в кабинете АЛОР смотреть номера портфелей, мы документацией не подтверждаем: ищите в личном кабинете брокера.

Идентификатор инструмента

NativeId::TickerClass { ticker, class_code }, например SBER и TQBR: класс это режим торгов (борд). Ключ библиотеки - SBER@TQBR. Биржа берется из режима торгов: SPBX это биржа SPBX, любой другой режим это MOEX. Любой другой вид идентификатора даст ошибку настройки (Config): справочник для АЛОРа не нужен, идентификатор собирается сам без сети.

Единицы и стакан

Как устроены команды

Команды идут по HTTP, по одному запросу, без повтора: заявка, замена и отмена. У брокера есть те же команды по WebSocket (канал /cws), но выигрыш в скорости по его словам до 5 мс, а HTTP проще и надежнее разбирается при обрыве. Канал /cws доступен через raw().connect_cws(...).

• Отказ известен сразу: Rejected с кодом http_<статус> и текстом брокера.
• В OrderAck приходит номер заявки брокера (orderNumber).
• Нет ответа, обрыв, таймаут, 5xx и ответ без номера заявки это Unknown: повторов нет, выход из неизвестности - order_state и reconcile (Круг команд).
• Отмена (DELETE) успешна, когда брокер принял запрос. Брокер отвечает до того, как биржа подтвердила отмену: подтверждение приходит событием статуса Cancelled (подписка subscribe_order_state) или чтением order_state.

Как cid уходит к брокеру

Дважды: в заголовке X-REQID команды и в поле comment заявки, как UUID с дефисами (36 знаков, комментарий вмещает 100). Обратимо. Комментарий возвращается в списке заявок, в потоке заявок и в сделках, так cid находится в ответах.

Брокер хранит номер заявки, а не cid, и читает заявку по номеру. Поэтому коннектор помнит пары cid и номер, а для заявки, которую не ставил этот процесс, ищет cid в комментарии списка заявок дня. Заявка с чужим комментарием получает подставной cid (стабильный: тот же номер дает тот же cid), по нему ее можно снять.

Документация брокера говорит, что повторный X-REQID получает копию первого ответа и второй заявки не создает. Библиотека на это не опирается: place_idempotency = LabelOnly, а повтор того же cid она сама не отправляет (duplicate_place).

Порядок как у остальных брокеров: шлюз команд, проверка входа, размер лота (чтение справочника, если лот еще неизвестен), квота, очередь по бумаге, шлюз еще раз и только потом cid помечается использованным. После RateLimited и после ошибки входа тот же cid годен. Общее правило: Круг команд.

Изменение заявки

Есть: PUT лимитной заявки по номеру. Брокер снимает исходную заявку и ставит новую, ответ несет номер новой, под новым cid в комментарии. Количество и цена, которых вы не указали, берутся от исходной (одно чтение). Если заявка исполнена частично, количество нужно указать явно, иначе Rejected { qty_required }. Рыночную заявку заменить нельзя: Rejected { not_replaceable }.

Свои сделки, портфель

Стоп-заявки

У брокера два вида: стоп-заявка (при срабатывании выставляется рыночная) и стоп-лимит (лимитная со своей ценой).

Срок: «до отмены» уходит как год вперед (брокер требует время окончания), «до конца дня» это конец дня по Москве, «до даты» это дата. При чтении стоп-заявка получает вид StopLoss или TakeProfit (по стороне и условию), а стоп-лимит всегда StopLimit: брокер не хранит, какой из видов имел в виду бот. Потока стоп-заявок нет (subscribe_stop_orders отвечает Unsupported), список читает active_stop_orders. Подробно: Стоп-заявки.

Чего АЛОР не поддерживает или делает иначе

Подписки

Все подписки идут по одному WebSocket (/ws), у каждой свой guid, и ответные кадры несут тот же guid, поэтому кадр всегда относится к своей подписке. subscribe_* возвращается, когда брокер подтвердил подписку: события заявки, поставленной сразу после возврата, не потеряются. Отказ брокера внутри subscribe_ack_timeout (3 секунды по умолчанию) возвращается как Rejected { subscription_refused }, а если подтверждения нет за это время - Transport, подписка снята и вызов можно повторить. Пауза перед переподключением от 0,5 с до 30 с. Брокер разрешает до 10 соединений на пользователя и до 5000 подписок на соединение.

Лимиты

crates/alor/limits.toml: брокер называет 100 HTTP-запросов в секунду на пользователя, 10 соединений WebSocket, 5000 подписок на соединение и 5000 необработанных сообщений в буфере соединения. Библиотека держит ведро на 100 запросов в секунду для всех методов и меньшее ведро place (60 в секунду, всплеск 30) для постановки, замены и стоп-заявки: это не лимит брокера, а запас, чтобы поток заявок не занял весь бюджет и отмене осталось место. У брокера есть и непубликуемая защита («социальный рейтинг» с блокировкой логина на 2 часа, например за запрос несуществующей заявки или некорректный JSON): ее порогов в документации нет и коннектор их не считает. Не слать лишнего: чтение заявки по cid идет через список заявок дня, а не через запрос несуществующего номера. Лимит общий на логин, поэтому все коннекторы одного логина берут один BrokerLimiter.

Что учесть

1. Единицы объема в стакане, ленте и свечах документация АЛОРа не называет (у котировок - лоты). Количество в этих данных берите как пришло.
2. Повтор X-REQID: что сделает брокер, в документации не сказано. Коннектор команды не повторяет.
3. Срок стоп-заявки без времени окончания и регистр значений (condition, side, timeInForce) брокер описывает неоднозначно. Задавайте срок явно.

Bybit: подключение к API

Эта страница о техническом подключении к публичному API стороннего сервиса. Она не является рекламой, предложением услуг или рекомендацией совершать сделки с цифровой валютой. Законность таких операций зависит от вашей юрисдикции. Для резидентов РФ действует 282-ФЗ «О цифровых валютах и цифровых правах», с 1 июля 2027 года сделки с цифровой валютой допускаются только через российских организаторов обращения. Проверьте требования закона до использования.

Крейты: brokapi-bybit-protocol (клиент HTTP и WebSocket: подпись запросов, методы API V5 и оба канала WebSocket) и brokapi-bybit (коннекторы). Bybit - зарубежный сервис, не российский брокер: у него нет торговых сессий и лотов, и книга отмечает отличия там, где они меняют код.

Что поддержано. Контракты с расчетом в USDT (категория linear API V5). Спота пока нет, как и инверсных контрактов и опционов: категория входит в идентификатор инструмента, поэтому спот добавится рядом, не ломая существующий код.

Вход

Где взять ключ

Ключ выпускает человек, чей это счет (правило 0). Шаги по документации Bybit:

Демо-счет (виртуальные деньги, с него начинайте):

1. Войти на сайт Bybit и включить режим «Demo Trading».
2. В этом режиме открыть страницу API и создать ключ с правами на чтение и торговлю по деривативам (Unified Trading) и чтение кошелька.
3. Положить ключ и секрет в BYBIT_DEMO_API_KEY и BYBIT_DEMO_API_SECRET. Демо-счет пустой: бот пополняет его методом POST /v5/account/demo-apply-money (через raw, не чаще раза в минуту, до 100 000 USDT за запрос).

Основной контур: ключ выпускают для отдельного субсчета, без права вывода и с привязкой к IP-адресу. Ключ основного счета программе не давайте.

Первый запуск

План от безопасного к боевому. Каждый шаг начинается, когда прошел предыдущий.

1. Имитация. Код сначала проходит на brokapi.testing.mock_bybit() (тестовый инструмент MOCKUSDT): быстрый старт на Python.
2. Демо-счет. Тот же код с env="demo": деньги виртуальные, поэтому проверка идет вживую и без риска, но с настоящей подписью, настоящими потоками и настоящими отказами биржи.
3. Основной контур - только с минимальной заявкой далеко от рынка и сразу с отменой, на субсчете.

Программа делает на любом контуре одно и то же: читает контракт и его правила, сверяется со счетом, ставит самую малую заявку вдвое ниже лучшей покупки, видит ее в потоке, снимает, ставит стоп-заявку и тоже снимает. Ничего не может исполниться: обе цены далеко от рынка.

async def order_event(client: brokapi.Client, cid: uuid.UUID) -> brokapi.OrderSnapshot:
    """The first event of the stream that is a state of the order with this cid."""
    async for event in client.events:
        if isinstance(event.payload, brokapi.OrderSnapshot) and event.payload.cid == cid:
            return event.payload
    raise RuntimeError("the stream ended")


async def first_day(client: brokapi.Client, symbol: str) -> None:
    """Reads the contract, puts the smallest order at half of the best bid, sees it in the stream, takes it off, and
    puts a stop order that is also taken off. Nothing here can fill: both prices are far from the market."""
    # 1. The contract and its rules: the quantity step, the smallest order and the price step. They come from the exchange.
    perp = await client.instrument(symbol)  # "BTCUSDT" becomes "BTCUSDT@linear": the category is part of the id
    params = await client.trading_params(perp)
    book = await client.order_book(perp, depth=1)
    bid = book.bids[0].price
    print(f"{perp}: bid {bid}, ask {book.asks[0].price}, smallest order {params.min_qty}, quantity step {params.lot_size}")

    # 2. Subscribe to the orders, and only then reconcile: no event is lost between the two.
    await client.subscribe_order_state()
    report = await client.reconcile([])  # a new bot has an empty ledger
    print(f"reconcile: {len(report.foreign)} foreign order(s) on the account")

    # 3. The order: half of the best bid, rounded down to the price step. The exchange refuses a price too far from the
    # market with a code of its own, then try a nearer one with a NEW cid.
    price = brokapi.round_to_step(bid / 2, params.price_step, brokapi.RoundMode.DOWN)
    cid = brokapi.new_cid()  # a real bot writes the cid to its journal here, before `place`
    ack = await client.place(cid=cid, instrument=perp, side=brokapi.Side.BUY, qty=params.min_qty, price=price)
    print(f"placed: order {ack.broker_id} at {price}")
    seen = await asyncio.wait_for(order_event(client, cid), timeout=10)  # waits for the event, not for a pause
    print(f"in the stream: {seen.state.kind.value}")

    # 4. Take it off and ask the exchange what became of it. The answer of `order_state` is the proof.
    await client.cancel(cid)
    state = await client.order_state(cid)
    print(f"after cancel: {state.state.kind.value}, orders alive: {len(await client.active_orders())}")

    # 5. A stop order is a conditional order of Bybit. It waits apart from the ordinary orders: `active_stop_orders`.
    stop_cid = brokapi.new_cid()
    await client.place_stop(
        cid=stop_cid,
        instrument=perp,
        side=brokapi.Side.SELL,
        kind=brokapi.StopOrderKind.STOP_LOSS,
        qty=params.min_qty,
        stop_price=brokapi.round_to_step(bid / 2, params.price_step, brokapi.RoundMode.DOWN),
    )
    print(f"stop orders waiting: {len(await client.active_stop_orders())}, ordinary orders: {len(await client.active_orders())}")
    await client.cancel_stop(stop_cid)
    print(f"stop orders after cancel: {len(await client.active_stop_orders())}")

Запуск на имитации (сеть и деньги не нужны) и на демо-счете:

async def on_the_imitation() -> None:
    async with await mock_bybit() as mock:
        client = await mock.connect()
        await first_day(client, "MOCKUSDT")
        await client.close()

async def on_the_demo_account() -> None:
    # BYBIT_DEMO_API_KEY and BYBIT_DEMO_API_SECRET from the environment: a key of the demo account is not valid on the
    # main host, so the contour is chosen by the name, not by the address.
    client = await brokapi.connect("bybit", env="demo")
    try:
        await first_day(client, "BTCUSDT")
    finally:
        await client.close()

На имитации программа печатает MOCKUSDT@linear: bid 100.00, ask 100.01, ..., in the stream: Acked, after cancel: Cancelled, orders alive: 0 и stop orders after cancel: 0. Если биржа отвергла цену как слишком далекую от рынка (окно допустимых цен у контрактов разное), подвиньте цену ближе и повторите с новым cid.

Идентификатор инструмента

NativeId::SymbolMic, ключ библиотеки BTCUSDT@linear: тикер контракта и категория Bybit (у Bybit нет кода рынка MIC, его место занимает категория). Построить идентификатор без сети: brokapi::bybit::util::instrument_id("BTCUSDT"). В Python await client.instrument("BTCUSDT") или "BTCUSDT@linear". Идентификатор другого брокера или другой категории - Config до сети. Неизвестный тикер биржа отвергает кодом 10001 (symbol invalid), коннектор отдает это как Rejected { code: "not_found" }.

У контрактов Bybit два вида: бессрочный (InstrumentKind::Perpetual, без срока, с ставкой финансирования) и срочный фьючерс (InstrumentKind::Future, с датой исполнения, например BTC-26DEC26). Поиск по виду Other дает Unsupported, остальные виды вне категории linear - пустой список.

Единицы и стакан

Как устроены команды

Команды идут по HTTP, по одному запросу, без повтора: заявка, отмена, стоп-заявка. Канал команд по WebSocket (/v5/trade) коннектор не использует, на демо-счете его нет.

• Отказ известен сразу: Rejected с кодом bybit_<код биржи> и текстом.
• В OrderAck приходит номер заявки биржи (orderId).
• Нет ответа, обрыв, таймаут, 5xx и коды 10000 и 10016 это Unknown: повторов нет, выход из неизвестности - order_state и reconcile (Круг команд).
• Отмена успешна, когда биржа приняла запрос. Подтверждение - событие статуса Cancelled или чтение order_state.
• Рыночная заявка у Bybit исполняется сразу или отменяется (IOC), лимитная держится до отмены (GTC). Других сроков и условий (post-only, FOK) в общем интерфейсе нет, они доступны через raw().

Как cid уходит к бирже

В поле orderLinkId заявки, как UUID с дефисами (36 знаков из 36 допустимых). Обратимо: orderLinkId возвращается в списке заявок, в потоке и в сделках, так cid находится в ответах. Повтор orderLinkId биржа отвергает (код 110072), это видно как Rejected { code: "bybit_110072" }. Как долго она помнит закрытую заявку, в документации не названо, поэтому place_idempotency = LabelOnly, а повтор того же cid библиотека сама не отправляет. Заявка без нашего orderLinkId (из приложения, чужая программа) получает подставной cid (стабильный: тот же номер дает тот же cid), по нему ее можно снять.

Порядок как у остальных брокеров: шлюз команд, проверка правил контракта, квота, очередь по инструменту, шлюз еще раз и только потом cid помечается использованным. После RateLimited тот же cid годен. Общее правило: Круг команд.

Изменение заявки

Общего replace у Bybit нет (supports_replace = false, ответ Unsupported). Биржа меняет заявку на месте: номер и orderLinkId остаются, а общий replace обещает новую заявку под новым cid и отмену старой. Выдавать одно за другое нельзя: после перезапуска бота сверка искала бы заявку по новому cid и сказала бы «закрыта». Поменять цену или количество можно двумя способами: снять заявку и поставить новую под новым cid (так надежнее) или вызвать POST /v5/order/amend через raw() и помнить, что cid остается прежним.

Свои сделки, портфель

Стоп-заявки

Стоп-заявка Bybit - обычная заявка с ценой срабатывания (triggerPrice). StopLoss и TakeProfit при срабатывании ставят рыночную заявку, StopLimit - лимитную по limit_price (без нее Rejected { missing_price }). Направление срабатывания (рост или падение цены) коннектор выводит из вида и стороны.

Подробно: Стоп-заявки, для Python Стоп-заявки, Python.

Чего Bybit не поддерживает или делает иначе

Что закрыто общим интерфейсом, что через raw()

Через raw() годится любой метод по глаголу и пути: "GET /v5/market/time", "POST /v5/position/set-leverage". Параметры GET идут в query, тело POST в body. Пути /v5/market/... читаются без подписи, остальные подписываются ключом. Каждый вызов тратит квоту и идет через общий счетчик лимитов.

Ошибки

Общая таблица ошибок: Ошибки.

Лимиты

crates/bybit/limits.toml: по документации Bybit 10 запросов в секунду на создание, изменение, отмену и «снять все» (по пользователю и методу), 50 в секунду на чтения, 600 запросов за 5 секунд на адрес (сверх этого HTTP 403 и бан адреса на 10 минут). Библиотека держит по ведру на каждый вид команды, чтобы поток заявок не занял бюджет отмен, и общее ведро адреса (100 в секунду, всплеск 100): оно держит адрес в пределах 600 за 5 секунд, даже если рядом работает другая программа. Заголовки X-Bapi-Limit-Status, которые биржа присылает с каждым ответом, библиотека не читает, счет ведется у нее самой. Лимит общий на логин (ключ), поэтому все коннекторы одного ключа берут один BrokerLimiter. Демо-счет по документации считает так же, вживую это не сверяли.

Что проверено вживую

Проверено на настоящем сервисе, не на имитации:

• Демо-счет, сценарий службы и гейтвея, 12 шагов из 12, с первого раза. Подпись принята, приватные потоки подписываются, пополнение демо-счета работает. Гейтвей читает котировки и стакан, бот видит счет и ставит лимитную заявку на 30% ниже рынка (принята), получает событие, order_state и отмену. Лимитная и стоп-заявка оставлены стоять, процесс гейтвея убит, служба подняла его, журнал помнит заявку, бот переподключился, сверка подтвердила обе заявки, обе сняты.
• Основной контур, отдельный субсчет, минимальные заявки. Лимитная заявка далеко от рынка принята, событие пришло в потоке заявок, отмена подтверждена. Рыночная заявка и обратная ей исполнены, исполнения пришли с cid и полем execFee, позиций и заявок на счете не осталось.
• Публичные данные: справочник, стакан, лента, свечи и публичные потоки на основном контуре и на демо.

Не проверено вживую, учитывайте в боте:

Прогон на демо-счете повторяется: tools/bybit-demo-run (служба, гейтвей, бот, убитый гейтвей и сверка, ключ только демо-счета, без ключей и сети сценарий проверяет себя на имитации: --self-test). Допущения, на которые опирается код, собраны в Допущениях по документации брокеров.

Что учесть

1. Контур выбирается именем, а не адресом: BYBIT_ENV=demo берет пару BYBIT_DEMO_API_KEY и BYBIT_DEMO_API_SECRET. Забытая BYBIT_ENV оставит основной контур и основной ключ.
2. Количество в базовой монете и с шагом контракта (lot_size). Заявка меньше min_qty или дешевле минимальной стоимости (около 5 USDT) уйдет к бирже и вернется Rejected.
3. Замены нет: меняйте заявку отменой и новой заявкой под новым cid.
4. Стоп-заявки не входят в active_orders: проверяйте оба списка при сверке и в скрипте аварийной остановки (Аварийная остановка бота).
5. Рыночная заявка исполняется как IOC: если ликвидности не хватает, остаток отменяется, проверяйте filled в order_state.
6. Один ключ - один BrokerLimiter: все коннекторы и боты одного ключа берут общий счетчик.

brokapi на Rust

Ядро brokapi - библиотека на Rust. Стадия: открытая альфа.

Раздел для тех, кто пишет бота на Rust. Устройство, правила и особенности брокеров общие для всех путей и лежат в общих частях книги. Здесь то, что зависит от языка: как подключить крейт и как решить конкретную задачу кодом.

С чего начать

Один крейт brokapi, брокеры включаются флагами bcs, tbank, finam, alor, bybit. Команда - cargo add brokapi --features bcs, самая свежая версия из репозитория - cargo add --git https://github.com/runinfra/brokapi brokapi --features bcs. Подробности: Установка. Первый шаг быстрого старта - получить библиотеку, дальше переменные .env: Быстрый старт на Rust.

Инструкции по задачам

Общее, что нужно прочитать

• Контракт для агентов: обязательные правила на одной странице, нужны и человеку.
• Карта и три круга: события, команды, жизнь коннектора.
• Ошибки и что с ними делать, события и возможности, Брокеры.
• Справочник по типам и методам, собранный из кода: Справочник API: Rust.

Каждый пример в этом разделе - тест против имитаций брокеров, он собирается и запускается при каждой проверке репозитория.

Быстрый старт на Rust

Цель страницы: за один заход получить работающую программу, которая подключается к брокеру, смотрит стакан, ставит одну заявку далеко от рынка, читает события и снимает заявку. Для каждого брокера свой короткий main, а общая часть одна.

На настоящем счете БКС, Т-Банка, Финама и АЛОРа библиотеку пока не запускали (Bybit проверен вживую). Начинайте с песочницы Т-Банка. Для БКС и Финама песочницы нет, заявка уйдет на настоящий счет (у АЛОРа есть тестовый контур со своим счетом, у Bybit демо-счет с виртуальными деньгами): ставьте минимальное количество и цену заведомо ниже рынка, кратную шагу цены. Подробнее: Перед боевым счетом.

Шаг 1. Получить библиотеку

Нужен Rust 1.88 или новее (редакция 2024). Подключается один крейт brokapi, брокеры включаются флагами, как у tokio (tbank, bcs, finam, alor, bybit, можно несколько):

cargo add brokapi --features tbank
cargo add tokio --features full
cargo add dotenvy

Самая свежая версия из репозитория - вместо первой строки (подробности и проверка - на странице Установка):

cargo add --git https://github.com/runinfra/brokapi brokapi --features tbank

Должно получиться в Cargo.toml:

[dependencies]
brokapi = { git = "https://github.com/runinfra/brokapi", version = "0.1.0-alpha.5", features = ["tbank"] }   # после беты без git
tokio   = { version = "1", features = ["full"] }
dotenvy = "0.15"

Из клона репозитория подключают по пути: brokapi = { path = "../brokapi", features = ["tbank"] }. В коде все лежит под brokapi::: общее в brokapi::core и brokapi::runtime, брокеры в brokapi::bcs, brokapi::tbank, brokapi::finam, brokapi::alor, brokapi::bybit, их клиенты нижнего слоя в brokapi::bcs::protocol и так далее. cargo build должен собрать проект без ошибок. Не собрал: таблица «Если что-то пошло не так» на странице Установка.

Что делает каждый крейт: Карта.

Сначала без токена: на имитации

Токен и счет нужны не сразу. В клоне репозитория (git clone https://github.com/runinfra/brokapi) пример БКС запускается на имитации, которая живет в вашем процессе и говорит на протоколе БКС: без сети, без счета, без денег.

cargo run --example quickstart_bcs                 # имитация: токен не нужен
BROKAPI_LIVE=1 cargo run --example quickstart_bcs  # настоящий БКС: токен на запись и слово владельца счета

Пример читает портфель, стакан и свечи, ставит заявку далеко от рынка и снимает ее: ровно то, что делают программы ниже. Цена в имитации стоит на месте, заявка сама не исполнится, ее исполняет тест (server.fill). Имитации всех четырех брокеров, рычаги и ограничения описаны на странице Тесты против имитаций, Rust. Крейт brokapi-mocks в crates.io не публикуется, поэтому в своем проекте его подключают по пути к клону. Токены и счет для следующих шагов выдает человек, чей это счет: правило 0.

Шаг 2. Переменные .env

Файл .env лежит рядом с программой, в git не попадает. Токены не печатайте в логи и не кладите в коммиты.

Счет Т-Банка в песочнице нужно открыть. Список своих счетов: TbankClient::new(&cfg)?.list_accounts().await (brokapi::tbank::protocol::TbankClient). Открывает счет песочницы метод open_sandbox_account клиента sandbox(), пример в crates/tbank/tests/live_sandbox.rs.

Шаг 3. Общая часть

Эта функция одинакова для всех брокеров, потому что работает через общие трейты OrderBookSource и OrderExecutor. Положите ее в тот же файл, что и main нужного брокера.

use std::time::Duration;

use brokapi::core::{
    Backpressure, ClientOrderId, Envelope, Error, Event, InstrumentId, OrderBook, OrderBookSource,
    OrderExecutor, OrderType, PlaceOrderRequest, Price, Qty, Side, SubscribeOpts,
};
use tokio::sync::mpsc;
use tokio::time::timeout;

/// Читает события из общего канала заданное время и печатает самое интересное.
async fn show_events(events: &mut mpsc::Receiver<Envelope>, how_long: Duration) {
    let _ = timeout(how_long, async {
        while let Some(env) = events.recv().await {
            match env.payload {
                Event::OrderBook(OrderBook::Snapshot { bids, asks, .. }) => println!(
                    "[{} sub {:?}] стакан: покупка {:?}, продажа {:?}",
                    env.source,
                    env.sub,
                    bids.first().map(|l| l.price),
                    asks.first().map(|l| l.price),
                ),
                Event::Order(order) => println!("заявка {}: {:?}", order.cid, order.state),
                Event::Execution(fill) => {
                    println!("исполнение {}: {} по {}", fill.trade_id, fill.qty, fill.price)
                }
                Event::Resync { .. } => println!("стакан надо брать заново"),
                Event::Overflow { .. } => println!("буфер переполнился, нужна сверка"),
                _ => {}
            }
        }
    })
    .await;
}

/// Сверка, подписки, одна заявка, события, отмена.
async fn trade_once<M, U>(
    md: &M,
    ud: &U,
    instrument: InstrumentId,
    qty: Qty,
    price: Price,
    events: &mut mpsc::Receiver<Envelope>,
) -> Result<(), Box<dyn std::error::Error>>
where
    M: OrderBookSource,
    U: OrderExecutor,
{
    // 1. Подписки, ДО сверки: событие между снимком сверки и подпиской иначе теряется. Стакан можно
    //    склеивать: важен только свежий. Статусы своих заявок всегда идут без потерь, режим выбирает
    //    сама библиотека.
    let opts = SubscribeOpts { backpressure: Backpressure::Conflate, depth: Some(10) };
    let book = md.subscribe_order_book(&instrument, opts).await?;
    ud.subscribe_order_state().await?;

    // 2. Сверка. Пока она не прошла, UD отвечает NotReconciled на любую торговую команду.
    //    Журнал бота пуст, поэтому список своих заявок пустой.
    let report = ud.reconcile(&[]).await?;
    println!("чужих заявок на счете: {}", report.foreign.len());

    // 3. Одна заявка. Номер cid придумывает бот, не библиотека.
    let cid = ClientOrderId::new_v4();
    let request = PlaceOrderRequest {
        cid,
        instrument: instrument.clone(),
        side: Side::Buy,
        order_type: OrderType::Limit,
        qty,
        price: Some(price),
    };
    match ud.place(request).await {
        Ok(ack) => println!("заявка принята, номер брокера {}", ack.broker_id.as_str()),
        Err(Error::Rejected { code, message }) => {
            println!("брокер отказал: {code}, {message}");
            return Ok(());
        }
        Err(Error::Unknown) => {
            // Неизвестно, дошла ли заявка. Повторять нельзя: спрашиваем брокера.
            let snapshot = ud.order_state(cid).await?;
            println!("итог был неясен, брокер говорит: {:?}", snapshot.state);
        }
        Err(other) => return Err(other.into()),
    }

    // 4. События: стакан, статус заявки.
    show_events(events, Duration::from_secs(5)).await;

    // 5. Снимаем заявку, дочитываем события, отписываемся.
    ud.cancel(cid).await?;
    show_events(events, Duration::from_secs(2)).await;
    md.unsubscribe(book).await?;
    Ok(())
}

Разбор шагов: сверка - Круг жизни, заявка и ее исходы - Круг команд, режимы подписки - Круг событий, события и их поля - События и возможности.

Шаг 4. Программа для Т-Банка

Количество в штуках, как у любого брокера в библиотеке: у Т-Банка API считает лотами, но коннектор переводит сам, лот должен укладываться в заявку целое число раз (лот SBER 10, поэтому ниже заявка на одну бумагу была бы отказана invalid_qty). Цена за одну бумагу. Инструмент ищем через справочник: он отдает uid, которым пользуется брокер.

use brokapi::core::{InstrumentQuery, InstrumentSource, ShutdownMode};
use brokapi::runtime::BrokerLimiter;
use brokapi::tbank::limits::default_limits;
use brokapi::tbank::{MarketDataConfig, MarketDataConnector, UserDataConfig, UserDataConnector};
use brokapi::tbank::protocol::TbankConfig;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // TBANK_TOKEN, TBANK_SANDBOX, TBANK_ACCOUNT_ID берутся из .env
    let cfg = TbankConfig::from_env()?;
    let price: Price = std::env::var("EXAMPLE_PRICE")?.parse()?;

    // Один счетчик лимитов на пользователя: Т-Банк считает лимит на все счета и токены сразу.
    let limiter = BrokerLimiter::new(&default_limits());
    // Один канал событий на оба коннектора. Кто прислал, видно по полю source.
    let (tx, mut events) = mpsc::channel::<Envelope>(1024);

    let md = MarketDataConnector::start(
        MarketDataConfig::new(cfg.clone(), "tbank-md"),
        limiter.clone(),
        tx.clone(),
    )
    .await?;
    let ud = UserDataConnector::start(UserDataConfig::new(cfg, "tbank-ud"), limiter, tx).await?;

    let sber = md
        .find(InstrumentQuery::ByTicker { ticker: "SBER".into(), exchange: Some("TQBR".into()) })
        .await?
        .into_iter()
        .next()
        .ok_or("SBER не найден")?
        .id;

    // один лот SBER: 10 штук
    trade_once(&md, &ud, sber, Qty::from(10), price, &mut events).await?;

    let stop = ShutdownMode::Graceful { deadline: Duration::from_secs(5) };
    ud.shutdown(stop).await;
    md.shutdown(stop).await;
    Ok(())
}

Что важно у Т-Банка: страница Т-Банка.

Шаг 4. Программа для БКС

Счет определяет токен, поэтому account_id нет. Лимиты встроены в крейт: brokapi::bcs::limits::default_limits(), как у двух других брокеров (числа из таблицы ограничений брокера). Инструмент БКС задается тикером и классом (SBER, TQBR), справочник для этого не нужен.

use brokapi::bcs::protocol::config::BcsConfig;
use brokapi::bcs::{MarketDataConfig, MarketDataConnector, UserDataConfig, UserDataConnector};
use brokapi::bcs::limits::default_limits;
use brokapi::core::{InstrumentKey, NativeId, ShutdownMode};
use brokapi::runtime::BrokerLimiter;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // BCS_REFRESH_TOKEN и BCS_IS_WRITE берутся из .env
    let cfg = BcsConfig::from_env()?;
    let price: Price = std::env::var("EXAMPLE_PRICE")?.parse()?;

    // Один счетчик лимитов на токен: оба коннектора пользуются одним.
    let limiter = BrokerLimiter::new(&default_limits());
    let (tx, mut events) = mpsc::channel::<Envelope>(1024);

    let md = MarketDataConnector::start(
        MarketDataConfig::new(cfg.clone(), "bcs-md"),
        limiter.clone(),
        tx.clone(),
    )
    .await?;
    let ud = UserDataConnector::start(UserDataConfig::new(cfg, "bcs-ud"), limiter, tx).await?;

    let sber = InstrumentId::new(
        InstrumentKey::new("SBER", "TQBR"),
        NativeId::TickerClass { ticker: "SBER".into(), class_code: "TQBR".into() },
    );

    trade_once(&md, &ud, sber, Qty::from(1), price, &mut events).await?;

    let stop = ShutdownMode::Graceful { deadline: Duration::from_secs(5) };
    ud.shutdown(stop).await;
    md.shutdown(stop).await;
    Ok(())
}

У БКС заявка идет в штуках (так в документации брокера): страница БКС. Лот инструмента передайте коннектору (ud.price_grid().learn(&params)), тогда некратное количество будет отказано до отправки.

Шаг 4. Программа для Финама

Количество в штуках. Инструмент задается строкой SBER@MISX. Чтобы MD и UD не авторизовались дважды, создаем один менеджер токенов и отдаем его обоим.

use brokapi::core::ShutdownMode;
use brokapi::finam::limits::default_limits;
use brokapi::finam::util::instrument_from_symbol;
use brokapi::finam::{api_config_from_env, MarketDataConfig, MarketDataConnector, UserDataConfig, UserDataConnector};
use brokapi::runtime::BrokerLimiter;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // api_config_from_env сам .env не читает, поэтому загружаем его вручную
    dotenvy::dotenv().ok();
    let (api, account) = api_config_from_env()?;
    let account = account.ok_or("FINAM_ACCOUNT_ID не задан")?;
    let price: Price = std::env::var("EXAMPLE_PRICE")?.parse()?;

    // Один JWT на оба коннектора
    let tokens = api.shared_tokens().await?;
    let api = api.with_tokens(tokens);

    let limiter = BrokerLimiter::new(&default_limits());
    let (tx, mut events) = mpsc::channel::<Envelope>(1024);

    let md = MarketDataConnector::start(
        MarketDataConfig::new(api.clone(), "finam-md"),
        limiter.clone(),
        tx.clone(),
    )
    .await?;
    let ud = UserDataConnector::start(UserDataConfig::new(api, account, "finam-ud"), limiter, tx).await?;

    let sber = instrument_from_symbol("SBER@MISX");

    trade_once(&md, &ud, sber, Qty::from(1), price, &mut events).await?;

    let stop = ShutdownMode::Graceful { deadline: Duration::from_secs(5) };
    ud.shutdown(stop).await;
    md.shutdown(stop).await;
    Ok(())
}

Что важно у Финама: страница Финама.

Что произошло по шагам

1. start поднял коннектор. У БКС и Финама он сразу проходит авторизацию и возвращает ошибку, если токен не подошел. У Т-Банка при заданном счете start в сеть не ходит, о неверном токене скажет первый запрос.
2. Подписки дали SubscriptionId. По source и sub в конверте видно, чье это событие. Они сделаны до сверки нарочно.
3. reconcile(&[]) открыл шлюз команд. До него place вернул бы NotReconciled.
4. place вернул OrderAck (или один из исходов, разобранных в Заявках).
5. События идут в канал сами. Программа их читает, как только они появились.
6. cancel снял заявку, shutdown закрыл подписки. Заявки на бирже при остановке не снимаются: если cancel не прошел, заявка останется.

Как написать торгового бота на событиях (Rust)

Инструкция. Цель: бот, который читает стакан, по сигналу ставит заявку, следит за ее статусами, выходит из неясного исхода (Unknown) и аккуратно останавливается. Правила, на которых он стоит, собраны в Контракте для агентов, причины - в Круге команд и Круге жизни. Код ниже - куски программы trading_bot, весь ее текст в конце страницы. Она запускается тестом против имитаций БКС и Т-Банка, поэтому текст и проверенный код не расходятся.

Стратегия в примере заглушка: когда пришел стакан и своей заявки нет, купить минимальное количество на 1% ниже лучшей цены покупки. Все остальное (журнал, сверка, исходы каждой команды, Resync, Overflow, остановка) нужно любому настоящему боту.

Что получится

Бот написан на трейтах brokapi::core (OrderBookSource, InstrumentSource, OrderExecutor, ExecutionSource), поэтому один и тот же TradingBot работает с любым брокером. На схеме: откуда идут события, где решает бот и что делает с каждым исходом place.

flowchart TB
  BR[Брокер] --> MD[MD: стакан]
  BR --> UD[UD: статусы и сделки]
  MD --> Q[(Канал событий)]
  UD --> Q
  Q --> BOT[TradingBot.on_event]
  BOT -- стакан, заявки нет --> P[place через UD, новый cid,<br>cid в журнал до вызова]
  P -- Ok --> W[Working: ждем<br>событий заявки]
  P -- Rejected --> D[Done: отказ]
  P -- RateLimited<br>или шлюз закрыт --> N[Не отправлено: позже<br>новая попытка с новым cid]
  P -- Unknown --> U[order_state<br>по тому же cid]
  U -- заявка есть --> W
  U -- брокер не знает --> A[подождать<br>и спросить снова]
  A -- так и нет --> D2[Done: не ставилась]

Из схемы следует: ответ на place и статусы приходят разными путями (результат вызова и события), Unknown разбирается запросом, а не повтором, и каждая развилка заканчивается записью в журнал.

Подключение

[package]
name = "my-bot"
edition = "2024"   # нужен Rust 1.88 или новее: в коде книги цепочки let

[dependencies]
brokapi = { version = "0.1.0-alpha.5", features = ["bcs"] }   # или "tbank", "finam", "alor", "bybit"
tokio   = { version = "1", features = ["full"] }

Из клона репозитория его подключают по пути: brokapi = { path = "../brokapi", features = ["bcs"] }.

use brokapi::core::{
    ClientOrderId, Decimal, Envelope, Error, Event, ExecutionSource, InstrumentId, InstrumentQuery,
    InstrumentSource, OrderBook, OrderBookSource, OrderExecutor, OrderSnapshot, OrderState,
    OrderType, PlaceOrderRequest, Price, Qty, RoundMode, ShutdownMode, Side, SubscribeOpts,
    SubscriptionId, TradingParams,
};
use tokio::sync::mpsc;

Журнал

Журнал - память бота. Библиотека не пишет на диск ничего. В примере он в памяти, чтобы код был короче. Настоящий бот пишет каждое изменение в файл или базу до того, как идти дальше: готовый журнал в файле - в инструкции про несколько брокеров и счетов.

/// What the bot knows about one of its orders. The journal is the bot's memory: the library keeps nothing
/// on disk. A real bot writes every change to a file or a database before it goes on (see the infrastructure
/// example). Here the journal is in memory, to keep the example short.
#[derive(Debug, Clone, PartialEq)]
pub enum Entry {
    /// Written BEFORE `place` is called. If the process dies now, the order may or may not exist.
    Sending,
    /// The broker accepted the order, or the stream says it works.
    Working,
    /// The outcome of the command is not known. The bot asks the broker with `order_state`.
    Check,
    /// Final. The text says how it ended.
    Done(String),
}

#[derive(Debug, Default)]
pub struct Journal {
    pub entries: Vec<(ClientOrderId, Entry)>,
}

impl Journal {
    pub fn set(&mut self, cid: ClientOrderId, entry: Entry) {
        match self.entries.iter_mut().find(|(c, _)| *c == cid) {
            Some(slot) => slot.1 = entry,
            None => self.entries.push((cid, entry)),
        }
    }

    pub fn get(&self, cid: ClientOrderId) -> Option<&Entry> {
        self.entries.iter().find(|(c, _)| *c == cid).map(|(_, e)| e)
    }

    /// The cids the bot believes are alive: the ledger it gives to `reconcile`.
    pub fn live(&self) -> Vec<ClientOrderId> {
        self.entries
            .iter()
            .filter(|(_, e)| !matches!(e, Entry::Done(_)))
            .map(|(c, _)| *c)
            .collect()
    }
}

Подключение коннекторов

Один счетчик лимитов на токен (БКС считает лимит на токен) и один канал для событий обоих коннекторов. Канал читает отдельная маленькая задача (forward, ниже): она сразу переносит конверты в очередь бота. Это нужно, потому что бот в ходе работы ждет ответы брокера (place до 30 секунд), а коннектор не умеет ждать читателя: если канал не читается, буфер заполняется и приходит Overflow (Контракт, правило 5).

/// How far below the best bid the bot buys: 99%. (`Decimal::new` is not `const`, `from_parts` is.)
const BUY_AT: Decimal = Decimal::from_parts(99, 0, 0, false, 2);

/// The top of the book the bot trades from. Dropped on `Resync`.
#[derive(Debug, Clone, Copy)]
pub struct Top {
    pub bid: Price,
    pub ask: Option<Price>,
}

/// BCS names an instrument by ticker and board.
fn sber_bcs() -> InstrumentId {
    use brokapi::core::{InstrumentKey, NativeId};
    InstrumentId::new(
        InstrumentKey::new("SBER", "TQBR"),
        NativeId::TickerClass {
            ticker: "SBER".into(),
            class_code: "TQBR".into(),
        },
    )
}

/// The connectors write into a bounded channel and never wait for it. A small task moves every envelope into
/// the bot's own queue at once, so the channel is always empty and the bot may take its time (a command can wait
/// seconds for the broker). The queue is unbounded: watch its length in a real bot.
fn forward(mut events: mpsc::Receiver<Envelope>) -> mpsc::UnboundedReceiver<Envelope> {
    let (queue_tx, queue) = mpsc::unbounded_channel();
    tokio::spawn(async move {
        while let Some(env) = events.recv().await {
            if queue_tx.send(env).is_err() {
                break;
            }
        }
    });
    queue
}

Константы и вспомогательные функции программы: покупка по 99% лучшей цены (Price * Decimal дает Price), идентификатор инструмента у БКС и читатель канала.

use brokapi::bcs::limits::default_limits;
use brokapi::bcs::protocol::config::BcsConfig;
use brokapi::bcs::{MarketDataConfig, MarketDataConnector, UserDataConfig, UserDataConnector};
use brokapi::runtime::BrokerLimiter;

let server = brokapi_mocks::bcs::MockServer::start(Default::default()).await;
let cfg = BcsConfig::for_mock("mock-refresh-token", &server.http_base).with_write(true);

// One limiter for the token (BCS counts limits per token), one channel for all events.
let limiter = BrokerLimiter::new(&default_limits());
let (tx, events) = mpsc::channel::<Envelope>(1024);
let mut queue = forward(events);
let md = MarketDataConnector::start(
    MarketDataConfig::new(cfg.clone(), "bcs-md"),
    limiter.clone(),
    tx.clone(),
)
.await?;
let ud = UserDataConnector::start(UserDataConfig::new(cfg, "bcs-ud"), limiter, tx).await?;
let grid = ud.price_grid().clone();

let mut bot =
    TradingBot::start(&md, &ud, sber_bcs(), Journal::default(), &grid, "bcs-md").await?;

Старт бота: подписка, сверка, правила инструмента

TradingBot::start делает все по порядку: подписка на статусы и сделки, reconcile со списком из журнала, правила инструмента (шаг цены, минимальное количество), подписка на стакан. Пока start не вернулся, бот не торгует.

/// The bot. `M` is the market data connector, `U` the connector of one account.
pub struct TradingBot<'a, M, U> {
    md: &'a M,
    ud: &'a U,
    instrument: InstrumentId,
    params: TradingParams,
    pub journal: Journal,
    /// The latest book. `None` after `Resync`: do not trade from a book that may be stale.
    top: Option<Top>,
    /// The order that works now. One at a time in this bot.
    pub working: Option<ClientOrderId>,
    /// The bot is stopping: no new orders.
    stopping: bool,
    /// A command found the gate closed, or `Overflow` came: reconcile before the next command.
    need_reconcile: bool,
    /// Do not place before this moment (a rate limit asked to wait).
    pause_until: Option<tokio::time::Instant>,
    /// What each of OUR orders has filled so far, from the order snapshots.
    fills: HashMap<ClientOrderId, Qty>,
    /// Which connector the book comes from, and the id of the book subscription: an `Overflow` of THAT
    /// subscription needs a new subscription, an `Overflow` of the order stream needs a reconcile.
    md_label: Arc<str>,
    book_sub: Option<SubscriptionId>,
    /// How many more orders the bot may place. The stand-in strategy buys once.
    pub budget: u32,
    /// The order that `stop` could not take off. A real bot alerts a person.
    pub left_working: Option<ClientOrderId>,
    /// The price of the last order that was accepted.
    pub placed_price: Option<Price>,
}

impl<'a, M, U> TradingBot<'a, M, U>
where
    M: OrderBookSource + InstrumentSource,
    U: OrderExecutor + ExecutionSource,
{
    /// Start-up in the order the library asks for: subscribe, reconcile, only then trade.
    pub async fn start(
        md: &'a M,
        ud: &'a U,
        instrument: InstrumentId,
        mut journal: Journal,
        price_grid: &brokapi::runtime::PriceGrid,
        md_label: &str,
    ) -> Result<TradingBot<'a, M, U>, Error> {
        // 1. Statuses and fills first: an event between the snapshot of the reconcile and the
        //    subscription would be lost otherwise.
        ud.subscribe_order_state().await?;
        ud.subscribe_executions().await?;

        // 2. The ledger comes from the journal. A new bot has an empty one.
        let report = ud.reconcile(&journal.live()).await?;
        for order in &report.confirmed {
            journal.set(order.cid, Entry::Working);
        }
        for cid in &report.closed_offline {
            // Not alive at the broker any more. Find out how it ended and write it down.
            let how = match ud.order_state(*cid).await {
                Ok(order) => format!("{:?}", order.state),
                Err(_) => "the broker does not know it".to_string(),
            };
            journal.set(*cid, Entry::Done(how));
        }
        // report.foreign: somebody else's orders. Look, do not touch.

        // 3. The rules of the instrument. The price step goes to the connector too, so a price off the
        //    step is refused before it is sent.
        let params = md.trading_params(&instrument).await?;
        price_grid.learn(&params);

        // 4. The order book. Only the latest book matters: Conflate.
        let book_sub = md
            .subscribe_order_book(
                &instrument,
                SubscribeOpts {
                    depth: Some(5),
                    ..SubscribeOpts::conflate()
                },
            )
            .await?;

        Ok(Self {
            md,
            ud,
            instrument,
            params,
            journal,
            top: None,
            working: report.confirmed.first().map(|o| o.cid),
            stopping: false,
            need_reconcile: false,
            pause_until: None,
            fills: HashMap::new(),
            md_label: Arc::from(md_label),
            book_sub: Some(book_sub),
            budget: 1,
            left_working: None,
            placed_price: None,
        })
    }

    /// One event from the shared channel.
    pub async fn on_event(&mut self, env: Envelope) -> Result<(), Error> {
        let source = env.source.clone();
        match env.payload {
            Event::OrderBook(OrderBook::Snapshot { bids, asks, .. }) => {
                self.top = bids.first().map(|b| Top {
                    bid: b.price,
                    ask: asks.first().map(|a| a.price),
                });
                if self.working.is_none() && !self.stopping && self.budget > 0 {
                    self.try_buy().await?;
                }
            }
            // The book may have lost data: forget it until the next snapshot.
            Event::Resync { .. } => self.top = None,
            Event::Order(order) => self.on_order(&order),
            // The fills are counted from the order snapshots (`filled`), which a reconcile restores after a hole.
            Event::Execution(_) => {}
            // The book subscription lost events: only the book is void, subscribe again. Own events lost: trading
            // is closed until a reconcile.
            Event::Overflow { sub, .. }
                if Some(sub) == self.book_sub && *source == *self.md_label =>
            {
                self.top = None;
                self.md.unsubscribe(sub).await?;
                self.book_sub = Some(
                    self.md
                        .subscribe_order_book(&self.instrument, SubscribeOpts::conflate())
                        .await?,
                );
            }
            Event::Overflow { .. } => self.need_reconcile = true,
            _ => {}
        }
        Ok(())
    }

    /// The statuses of the stream drive the journal. Final states free the bot to trade again.
    fn on_order(&mut self, order: &OrderSnapshot) {
        // The stream carries every order of the account, also those placed by hand. Only the journal's are ours.
        if self.journal.get(order.cid).is_none() {
            return;
        }
        self.fills.insert(order.cid, order.filled);
        let entry = match &order.state {
            OrderState::Acked { .. } | OrderState::PartiallyFilled { .. } => Entry::Working,
            OrderState::Filled { .. } => Entry::Done("filled".into()),
            OrderState::Cancelled { .. } => Entry::Done("cancelled".into()),
            OrderState::Rejected { reason, .. } => Entry::Done(format!("rejected: {reason}")),
            // `InFlight`, `Unknown`, and a state a later version adds: look at the broker.
            _ => Entry::Check,
        };
        let is_final = matches!(entry, Entry::Done(_));
        self.journal.set(order.cid, entry);
        if is_final && self.working == Some(order.cid) {
            self.working = None;
        }
    }

    /// How much our orders have filled.
    pub fn filled(&self) -> Qty {
        self.fills.values().copied().sum()
    }

    /// A timer, not only the book, drives a retry: after `RateLimited` or a closed gate a quiet book would
    /// never fire the signal again.
    pub async fn on_tick(&mut self) -> Result<(), Error> {
        if self.working.is_none() && !self.stopping && self.budget > 0 && self.top.is_some() {
            self.try_buy().await?;
        }
        Ok(())
    }

Что видно в коде:

• Событие Resync обнуляет сохраненный стакан (self.top = None). Следующий снимок его заменит.
• Overflow не обрабатывается на месте, а ставит флаг: сверку и дочитывание канала делает цикл, у которого есть канал.
• Состояние заявки берется из потока статусов (on_order), а не из ответа на place. Ответ значит «брокер принял».
• В поток статусов попадают все заявки счета, в том числе поставленные руками. on_order пропускает те, которых нет в журнале: чужую заявку бот в свой журнал не вносит (Контракт, правило 11).
• Сколько исполнено, бот считает по полю filled снимков заявок, а не складывает события Execution. Тогда после Overflow сверка сама возвращает правильное число (reconcile и order_state дают снимки).
• Overflow бывает двух видов. Если переполнилась подписка на стакан (ее sub и метка коннектора известны боту), стакан объявляется недействительным и подписка оформляется заново. Если переполнился поток своих заявок, нужна сверка.

Сигнал и заявка со всеми исходами

/// The signal, and the order with every outcome handled.
async fn try_buy(&mut self) -> Result<(), Error> {
    if self.need_reconcile {
        self.reconcile_now().await?;
    }
    if let Some(until) = self.pause_until {
        if tokio::time::Instant::now() < until {
            return Ok(());
        }
        self.pause_until = None;
    }
    let Some(top) = self.top else { return Ok(()) };
    // Exact decimal arithmetic. Round DOWN for a buy so the price never exceeds the plan, and to the step.
    let price = (top.bid * BUY_AT)
        .round_to_step(self.params.price_step, RoundMode::Down)
        .map_err(|e| Error::Config(brokapi::core::ConfigError::Message(e.to_string())))?;

    // The cid is made by the bot, and written to the journal BEFORE the call.
    let cid = ClientOrderId::new_v4();
    self.journal.set(cid, Entry::Sending);
    let request = PlaceOrderRequest {
        cid,
        instrument: self.instrument.clone(),
        side: Side::Buy,
        order_type: OrderType::Limit,
        qty: self.params.min_qty,
        price: Some(price),
    };
    match self.ud.place(request).await {
        Ok(_ack) => {
            self.journal.set(cid, Entry::Working);
            self.working = Some(cid);
            self.budget -= 1;
            self.placed_price = Some(price);
        }
        // The broker said no. The order does not exist. A new try needs a new cid.
        Err(Error::Rejected { code, message }) => {
            self.journal
                .set(cid, Entry::Done(format!("rejected {code}: {message}")));
        }
        // The gate is closed. Nothing was sent. Reconcile, and the next signal will try again.
        Err(Error::NotReconciled | Error::Degraded) => {
            self.journal
                .set(cid, Entry::Done("not sent: gate closed".into()));
            self.need_reconcile = true;
        }
        // The local limiter refused. Nothing was sent. Wait, do not hammer.
        Err(Error::RateLimited { retry_after }) => {
            self.journal
                .set(cid, Entry::Done("not sent: rate limited".into()));
            self.pause_until = Some(tokio::time::Instant::now() + retry_after);
        }
        // The command may have reached the broker. NEVER place again. Ask.
        Err(Error::Unknown | Error::Transport(_)) => {
            self.journal.set(cid, Entry::Check);
            self.settle_unknown(cid).await?;
        }
        // Setup errors, Unsupported, ShuttingDown: the bot cannot go on.
        Err(other) => return Err(other),
    }
    Ok(())
}

Повтор по таймеру: on_tick вызывается раз в четверть секунды. После RateLimited или закрытого шлюза тихий стакан сам повтор не запустит (имитация БКС присылает один снимок), поэтому повтор ведет таймер, а не только следующий стакан.

Таблица исходов этого куска:

Выход из Unknown

Заявку не ставят второй раз. Спрашивают брокера по тому же cid. «Не найдена» сразу после обрыва не окончательно: запрос мог быть в пути, поэтому бот ждет и спрашивает еще раз, а сдается только по истечении терпения.

/// The way out of `Unknown`: ask the broker about the same cid until it answers or patience runs out.
async fn settle_unknown(&mut self, cid: ClientOrderId) -> Result<(), Error> {
    let deadline = tokio::time::Instant::now() + Duration::from_secs(10);
    loop {
        match self.ud.order_state(cid).await {
            Ok(order) => {
                // The order exists. Continue as with any other.
                self.on_order(&order);
                if !matches!(self.journal.get(cid), Some(Entry::Done(_))) {
                    self.working = Some(cid);
                }
                self.budget = self.budget.saturating_sub(1);
                self.placed_price = order.price;
                return Ok(());
            }
            // "Not found" right after a cut is not final: the request may still be on its way.
            Err(e) if e.is_not_found() => {}
            Err(Error::RateLimited { .. } | Error::Transport(_)) => {}
            Err(other) => return Err(other),
        }
        if tokio::time::Instant::now() >= deadline {
            // Still unknown to the broker: it was not placed. A new order will have a new cid.
            self.journal.set(
                cid,
                Entry::Done("not placed (the broker never knew it)".into()),
            );
            return Ok(());
        }
        tokio::time::sleep(Duration::from_millis(100)).await;
    }
}

Тест запускает этот путь по-настоящему: имитация Т-Банка отвечает на place через 1,5 секунды, коннектор ждет 200 миллисекунд и возвращает Unknown, заявка при этом встала. Бот находит ее через order_state, и в журнале ровно одна заявка.

Overflow: дочитать, сверить

/// After `Overflow` or `Degraded`: read what is waiting in the channel to the end, then reconcile.
async fn reconcile_now(&mut self) -> Result<(), Error> {
    let report = self.ud.reconcile(&self.journal.live()).await?;
    for order in &report.confirmed {
        self.on_order(order);
    }
    for cid in &report.closed_offline {
        let how = match self.ud.order_state(*cid).await {
            Ok(order) => {
                self.on_order(&order);
                continue;
            }
            Err(_) => "the broker does not know it".to_string(),
        };
        self.journal.set(*cid, Entry::Done(how));
        if self.working == Some(*cid) {
            self.working = None;
        }
    }
    self.need_reconcile = false;
    Ok(())
}

/// The loop calls this after every event.
pub async fn recover_if_needed(
    &mut self,
    events: &mut mpsc::UnboundedReceiver<Envelope>,
) -> Result<(), Error> {
    if self.need_reconcile {
        // First the events that did arrive: they are the history up to the hole.
        while let Ok(env) = events.try_recv() {
            self.on_event(env).await?;
        }
        self.reconcile_now().await?;
    }
    Ok(())
}

Цикл событий

Бот разбирает свою очередь одним циклом, рядом с ним тикает таймер повторов (on_tick). Тест играет биржу: когда заявка встала, исполняет ее (server.fill) или просит бота остановиться. Задержка deadline нужна только затем, чтобы пример не завис при ошибке.

// The loop: events in, the bot decides. A deadline keeps the example from hanging if something is wrong.
let deadline = tokio::time::Instant::now() + Duration::from_secs(20);
let mut placed = None;
let mut tick = tokio::time::interval(Duration::from_millis(250));
loop {
    tokio::select! {
        env = tokio::time::timeout_at(deadline, queue.recv()) => {
            bot.on_event(env?.ok_or("the channel closed")?).await?;
        }
        _ = tick.tick() => bot.on_tick().await?,
    }
    bot.recover_if_needed(&mut queue).await?;

    // The example plays the exchange: once the order works, fill it, or ask the bot to stop.
    if ending == Ending::Filled
        && placed.is_some()
        && bot.working.is_none()
        && bot.filled().is_positive()
    {
        break; // the order is final and its fill is booked (the two events can come in either order)
    }
    if let Some(cid) = bot.working
        && placed != Some(cid)
    {
        placed = Some(cid);
        match ending {
            Ending::Filled => {
                let price = Price::new(Decimal::new(24200, 2));
                server.fill(&cid.hyphenated().to_string(), Qty::from(1), price);
            }
            Ending::StoppedByBot => break,
        }
    }
}
bot.stop(&mut queue).await?;

Остановка

Результат вызова (place, cancel) и событие о статусе идут разными путями, и порядок между ними не гарантирован: после cancel ответ Ok может прийти раньше события Acked. Поэтому журнал ведется по потоку статусов, а ответ на вызов только решает, что делать дальше.

Бот перестает ставить заявки, снимает свою рабочую заявку, дожидается финального статуса и записывает его. Снимать ли заявки - решение бота: библиотека при shutdown ничего не снимает. Отмена не бросается при первом сбое: RateLimited ждет и повторяет, закрытый шлюз сверяется, Unknown разбирается через order_state (повторная отмена новых заявок не создает).

Остановка по Ctrl-C та же: ловите сигнал в select! рядом с циклом событий и вызывайте тот же stop.

tokio::select! {
    env = queue.recv() => { /* bot.on_event(...) */ }
    _ = tokio::signal::ctrl_c() => break,   // потом bot.stop(&mut queue), shutdown
}

/// A clean stop. No new orders. The bot takes its own working order off (a choice of THIS bot: the
/// library never cancels anything on shutdown), waits for the final status, and writes it down.
pub async fn stop(
    &mut self,
    events: &mut mpsc::UnboundedReceiver<Envelope>,
) -> Result<(), Error> {
    self.stopping = true;
    if let Some(cid) = self.working {
        for _ in 0..5 {
            match self.ud.cancel(cid).await {
                Ok(()) => break,
                // The order was filled before the cancel arrived: read the result instead.
                Err(Error::Rejected { .. }) => break,
                // Nothing was sent: wait, or reconcile, and try again. Leaving the order is not an option.
                Err(Error::RateLimited { retry_after }) => {
                    tokio::time::sleep(retry_after).await
                }
                Err(Error::NotReconciled | Error::Degraded) => {
                    // Drain first: what did arrive is the history up to the hole.
                    while let Ok(env) = events.try_recv() {
                        self.on_event(env).await?;
                    }
                    self.reconcile_now().await?
                }
                // Maybe cancelled, maybe not: ask, and cancel again only if it still works.
                Err(Error::Unknown | Error::Transport(_)) => {
                    if let Ok(order) = self.ud.order_state(cid).await {
                        self.on_order(&order);
                        if self.working != Some(cid) {
                            break;
                        }
                    }
                }
                Err(other) => return Err(other),
            }
        }
        // The final status comes on the stream; the read below is the proof.
        let _ = tokio::time::timeout(Duration::from_secs(5), async {
            while self.working.is_some() {
                match events.recv().await {
                    Some(env) => self.on_event(env).await?,
                    None => break,
                }
            }
            Ok::<(), Error>(())
        })
        .await;
        if self.working.is_some() {
            let order = self.ud.order_state(cid).await?;
            self.on_order(&order);
        }
        // Still working after all this: the order stays on the exchange. Say so, do not hide it.
        self.left_working = self.working;
    }
    Ok(())
}

Потом коннекторы: сначала UD, затем MD. shutdown забирает коннектор по значению, а бот держит на него ссылку, поэтому бота отпускают раньше (drop(bot), иначе ошибка компиляции cannot move out of ... because it is borrowed).

// The bot borrows the connectors and `shutdown` takes them by value: let the bot go first.
drop(bot);
// Stop the account connector first (no more commands), then the market data.
let stop = ShutdownMode::Graceful {
    deadline: Duration::from_secs(5),
};
let report = ud.shutdown(stop).await;
md.shutdown(stop).await;
println!(
    "stopped: {} command(s) were left without an answer",
    report.inflight_abandoned.len()
);

inflight_abandoned в отчете - команды, на которые еще не пришел ответ. После нормально завершенных заявок он пуст.

Как запустить

cargo test --test examples trading_bot      # три теста: исполнение, остановка с отменой, выход из Unknown
cargo run --example trading_bot             # то же на имитации БКС с выводом

Вся программа целиком

Для копирования: файл examples/trading_bot.rs как есть (в Cargo.toml те же зависимости, что выше, плюс brokapi-mocks из страницы про имитации). Часть с run_bcs и run_tbank_unknown запускает бота против имитаций.

//! An event-driven trading bot: order book in, signal, order, statuses, a way out of `Unknown`, a clean stop.
//!
//! The code of the page "Как сделать торгового бота на событиях" of the book (docs/src/rust/howto-trading-bot.md).
//! The bot is written against the traits of `brokapi::core`, so the same `TradingBot` runs on every broker.
//! `run_bcs` plays it on the BCS imitation (the order is filled, or the bot stops and cancels it), `run_tbank_unknown`
//! plays it on the T-Bank imitation where the answer to `place` is lost, so the bot has to leave `Unknown`.
//! Nothing here touches the network or money.
//!
//! The strategy is a stand-in: when the book arrives and there is no order, buy the minimum quantity 1% below the
//! best bid. Everything around it (journal first, reconcile first, outcomes of every command, `Resync`,
//! `Overflow`, stop) is what a real bot needs.
//!
//! ```text
//! cargo run --example trading_bot
//! ```
#![allow(dead_code)]

use std::collections::HashMap;
use std::sync::Arc;
use std::time::Duration;

// ANCHOR: imports
use brokapi::core::{
    ClientOrderId, Decimal, Envelope, Error, Event, ExecutionSource, InstrumentId, InstrumentQuery,
    InstrumentSource, OrderBook, OrderBookSource, OrderExecutor, OrderSnapshot, OrderState,
    OrderType, PlaceOrderRequest, Price, Qty, RoundMode, ShutdownMode, Side, SubscribeOpts,
    SubscriptionId, TradingParams,
};
use tokio::sync::mpsc;
// ANCHOR_END: imports

// ANCHOR: journal
/// What the bot knows about one of its orders. The journal is the bot's memory: the library keeps nothing
/// on disk. A real bot writes every change to a file or a database before it goes on (see the infrastructure
/// example). Here the journal is in memory, to keep the example short.
#[derive(Debug, Clone, PartialEq)]
pub enum Entry {
    /// Written BEFORE `place` is called. If the process dies now, the order may or may not exist.
    Sending,
    /// The broker accepted the order, or the stream says it works.
    Working,
    /// The outcome of the command is not known. The bot asks the broker with `order_state`.
    Check,
    /// Final. The text says how it ended.
    Done(String),
}

#[derive(Debug, Default)]
pub struct Journal {
    pub entries: Vec<(ClientOrderId, Entry)>,
}

impl Journal {
    pub fn set(&mut self, cid: ClientOrderId, entry: Entry) {
        match self.entries.iter_mut().find(|(c, _)| *c == cid) {
            Some(slot) => slot.1 = entry,
            None => self.entries.push((cid, entry)),
        }
    }

    pub fn get(&self, cid: ClientOrderId) -> Option<&Entry> {
        self.entries.iter().find(|(c, _)| *c == cid).map(|(_, e)| e)
    }

    /// The cids the bot believes are alive: the ledger it gives to `reconcile`.
    pub fn live(&self) -> Vec<ClientOrderId> {
        self.entries
            .iter()
            .filter(|(_, e)| !matches!(e, Entry::Done(_)))
            .map(|(c, _)| *c)
            .collect()
    }
}
// ANCHOR_END: journal

// ANCHOR: types
/// How far below the best bid the bot buys: 99%. (`Decimal::new` is not `const`, `from_parts` is.)
const BUY_AT: Decimal = Decimal::from_parts(99, 0, 0, false, 2);

/// The top of the book the bot trades from. Dropped on `Resync`.
#[derive(Debug, Clone, Copy)]
pub struct Top {
    pub bid: Price,
    pub ask: Option<Price>,
}

/// BCS names an instrument by ticker and board.
fn sber_bcs() -> InstrumentId {
    use brokapi::core::{InstrumentKey, NativeId};
    InstrumentId::new(
        InstrumentKey::new("SBER", "TQBR"),
        NativeId::TickerClass {
            ticker: "SBER".into(),
            class_code: "TQBR".into(),
        },
    )
}

/// The connectors write into a bounded channel and never wait for it. A small task moves every envelope into
/// the bot's own queue at once, so the channel is always empty and the bot may take its time (a command can wait
/// seconds for the broker). The queue is unbounded: watch its length in a real bot.
fn forward(mut events: mpsc::Receiver<Envelope>) -> mpsc::UnboundedReceiver<Envelope> {
    let (queue_tx, queue) = mpsc::unbounded_channel();
    tokio::spawn(async move {
        while let Some(env) = events.recv().await {
            if queue_tx.send(env).is_err() {
                break;
            }
        }
    });
    queue
}
// ANCHOR_END: types

// ANCHOR: bot
/// The bot. `M` is the market data connector, `U` the connector of one account.
pub struct TradingBot<'a, M, U> {
    md: &'a M,
    ud: &'a U,
    instrument: InstrumentId,
    params: TradingParams,
    pub journal: Journal,
    /// The latest book. `None` after `Resync`: do not trade from a book that may be stale.
    top: Option<Top>,
    /// The order that works now. One at a time in this bot.
    pub working: Option<ClientOrderId>,
    /// The bot is stopping: no new orders.
    stopping: bool,
    /// A command found the gate closed, or `Overflow` came: reconcile before the next command.
    need_reconcile: bool,
    /// Do not place before this moment (a rate limit asked to wait).
    pause_until: Option<tokio::time::Instant>,
    /// What each of OUR orders has filled so far, from the order snapshots.
    fills: HashMap<ClientOrderId, Qty>,
    /// Which connector the book comes from, and the id of the book subscription: an `Overflow` of THAT
    /// subscription needs a new subscription, an `Overflow` of the order stream needs a reconcile.
    md_label: Arc<str>,
    book_sub: Option<SubscriptionId>,
    /// How many more orders the bot may place. The stand-in strategy buys once.
    pub budget: u32,
    /// The order that `stop` could not take off. A real bot alerts a person.
    pub left_working: Option<ClientOrderId>,
    /// The price of the last order that was accepted.
    pub placed_price: Option<Price>,
}

impl<'a, M, U> TradingBot<'a, M, U>
where
    M: OrderBookSource + InstrumentSource,
    U: OrderExecutor + ExecutionSource,
{
    /// Start-up in the order the library asks for: subscribe, reconcile, only then trade.
    pub async fn start(
        md: &'a M,
        ud: &'a U,
        instrument: InstrumentId,
        mut journal: Journal,
        price_grid: &brokapi::runtime::PriceGrid,
        md_label: &str,
    ) -> Result<TradingBot<'a, M, U>, Error> {
        // 1. Statuses and fills first: an event between the snapshot of the reconcile and the
        //    subscription would be lost otherwise.
        ud.subscribe_order_state().await?;
        ud.subscribe_executions().await?;

        // 2. The ledger comes from the journal. A new bot has an empty one.
        let report = ud.reconcile(&journal.live()).await?;
        for order in &report.confirmed {
            journal.set(order.cid, Entry::Working);
        }
        for cid in &report.closed_offline {
            // Not alive at the broker any more. Find out how it ended and write it down.
            let how = match ud.order_state(*cid).await {
                Ok(order) => format!("{:?}", order.state),
                Err(_) => "the broker does not know it".to_string(),
            };
            journal.set(*cid, Entry::Done(how));
        }
        // report.foreign: somebody else's orders. Look, do not touch.

        // 3. The rules of the instrument. The price step goes to the connector too, so a price off the
        //    step is refused before it is sent.
        let params = md.trading_params(&instrument).await?;
        price_grid.learn(&params);

        // 4. The order book. Only the latest book matters: Conflate.
        let book_sub = md
            .subscribe_order_book(
                &instrument,
                SubscribeOpts {
                    depth: Some(5),
                    ..SubscribeOpts::conflate()
                },
            )
            .await?;

        Ok(Self {
            md,
            ud,
            instrument,
            params,
            journal,
            top: None,
            working: report.confirmed.first().map(|o| o.cid),
            stopping: false,
            need_reconcile: false,
            pause_until: None,
            fills: HashMap::new(),
            md_label: Arc::from(md_label),
            book_sub: Some(book_sub),
            budget: 1,
            left_working: None,
            placed_price: None,
        })
    }

    /// One event from the shared channel.
    pub async fn on_event(&mut self, env: Envelope) -> Result<(), Error> {
        let source = env.source.clone();
        match env.payload {
            Event::OrderBook(OrderBook::Snapshot { bids, asks, .. }) => {
                self.top = bids.first().map(|b| Top {
                    bid: b.price,
                    ask: asks.first().map(|a| a.price),
                });
                if self.working.is_none() && !self.stopping && self.budget > 0 {
                    self.try_buy().await?;
                }
            }
            // The book may have lost data: forget it until the next snapshot.
            Event::Resync { .. } => self.top = None,
            Event::Order(order) => self.on_order(&order),
            // The fills are counted from the order snapshots (`filled`), which a reconcile restores after a hole.
            Event::Execution(_) => {}
            // The book subscription lost events: only the book is void, subscribe again. Own events lost: trading
            // is closed until a reconcile.
            Event::Overflow { sub, .. }
                if Some(sub) == self.book_sub && *source == *self.md_label =>
            {
                self.top = None;
                self.md.unsubscribe(sub).await?;
                self.book_sub = Some(
                    self.md
                        .subscribe_order_book(&self.instrument, SubscribeOpts::conflate())
                        .await?,
                );
            }
            Event::Overflow { .. } => self.need_reconcile = true,
            _ => {}
        }
        Ok(())
    }

    /// The statuses of the stream drive the journal. Final states free the bot to trade again.
    fn on_order(&mut self, order: &OrderSnapshot) {
        // The stream carries every order of the account, also those placed by hand. Only the journal's are ours.
        if self.journal.get(order.cid).is_none() {
            return;
        }
        self.fills.insert(order.cid, order.filled);
        let entry = match &order.state {
            OrderState::Acked { .. } | OrderState::PartiallyFilled { .. } => Entry::Working,
            OrderState::Filled { .. } => Entry::Done("filled".into()),
            OrderState::Cancelled { .. } => Entry::Done("cancelled".into()),
            OrderState::Rejected { reason, .. } => Entry::Done(format!("rejected: {reason}")),
            // `InFlight`, `Unknown`, and a state a later version adds: look at the broker.
            _ => Entry::Check,
        };
        let is_final = matches!(entry, Entry::Done(_));
        self.journal.set(order.cid, entry);
        if is_final && self.working == Some(order.cid) {
            self.working = None;
        }
    }

    /// How much our orders have filled.
    pub fn filled(&self) -> Qty {
        self.fills.values().copied().sum()
    }

    /// A timer, not only the book, drives a retry: after `RateLimited` or a closed gate a quiet book would
    /// never fire the signal again.
    pub async fn on_tick(&mut self) -> Result<(), Error> {
        if self.working.is_none() && !self.stopping && self.budget > 0 && self.top.is_some() {
            self.try_buy().await?;
        }
        Ok(())
    }
    // ANCHOR_END: bot

    // ANCHOR: place
    /// The signal, and the order with every outcome handled.
    async fn try_buy(&mut self) -> Result<(), Error> {
        if self.need_reconcile {
            self.reconcile_now().await?;
        }
        if let Some(until) = self.pause_until {
            if tokio::time::Instant::now() < until {
                return Ok(());
            }
            self.pause_until = None;
        }
        let Some(top) = self.top else { return Ok(()) };
        // Exact decimal arithmetic. Round DOWN for a buy so the price never exceeds the plan, and to the step.
        let price = (top.bid * BUY_AT)
            .round_to_step(self.params.price_step, RoundMode::Down)
            .map_err(|e| Error::Config(brokapi::core::ConfigError::Message(e.to_string())))?;

        // The cid is made by the bot, and written to the journal BEFORE the call.
        let cid = ClientOrderId::new_v4();
        self.journal.set(cid, Entry::Sending);
        let request = PlaceOrderRequest {
            cid,
            instrument: self.instrument.clone(),
            side: Side::Buy,
            order_type: OrderType::Limit,
            qty: self.params.min_qty,
            price: Some(price),
        };
        match self.ud.place(request).await {
            Ok(_ack) => {
                self.journal.set(cid, Entry::Working);
                self.working = Some(cid);
                self.budget -= 1;
                self.placed_price = Some(price);
            }
            // The broker said no. The order does not exist. A new try needs a new cid.
            Err(Error::Rejected { code, message }) => {
                self.journal
                    .set(cid, Entry::Done(format!("rejected {code}: {message}")));
            }
            // The gate is closed. Nothing was sent. Reconcile, and the next signal will try again.
            Err(Error::NotReconciled | Error::Degraded) => {
                self.journal
                    .set(cid, Entry::Done("not sent: gate closed".into()));
                self.need_reconcile = true;
            }
            // The local limiter refused. Nothing was sent. Wait, do not hammer.
            Err(Error::RateLimited { retry_after }) => {
                self.journal
                    .set(cid, Entry::Done("not sent: rate limited".into()));
                self.pause_until = Some(tokio::time::Instant::now() + retry_after);
            }
            // The command may have reached the broker. NEVER place again. Ask.
            Err(Error::Unknown | Error::Transport(_)) => {
                self.journal.set(cid, Entry::Check);
                self.settle_unknown(cid).await?;
            }
            // Setup errors, Unsupported, ShuttingDown: the bot cannot go on.
            Err(other) => return Err(other),
        }
        Ok(())
    }
    // ANCHOR_END: place

    // ANCHOR: unknown
    /// The way out of `Unknown`: ask the broker about the same cid until it answers or patience runs out.
    async fn settle_unknown(&mut self, cid: ClientOrderId) -> Result<(), Error> {
        let deadline = tokio::time::Instant::now() + Duration::from_secs(10);
        loop {
            match self.ud.order_state(cid).await {
                Ok(order) => {
                    // The order exists. Continue as with any other.
                    self.on_order(&order);
                    if !matches!(self.journal.get(cid), Some(Entry::Done(_))) {
                        self.working = Some(cid);
                    }
                    self.budget = self.budget.saturating_sub(1);
                    self.placed_price = order.price;
                    return Ok(());
                }
                // "Not found" right after a cut is not final: the request may still be on its way.
                Err(e) if e.is_not_found() => {}
                Err(Error::RateLimited { .. } | Error::Transport(_)) => {}
                Err(other) => return Err(other),
            }
            if tokio::time::Instant::now() >= deadline {
                // Still unknown to the broker: it was not placed. A new order will have a new cid.
                self.journal.set(
                    cid,
                    Entry::Done("not placed (the broker never knew it)".into()),
                );
                return Ok(());
            }
            tokio::time::sleep(Duration::from_millis(100)).await;
        }
    }
    // ANCHOR_END: unknown

    // ANCHOR: recover
    /// After `Overflow` or `Degraded`: read what is waiting in the channel to the end, then reconcile.
    async fn reconcile_now(&mut self) -> Result<(), Error> {
        let report = self.ud.reconcile(&self.journal.live()).await?;
        for order in &report.confirmed {
            self.on_order(order);
        }
        for cid in &report.closed_offline {
            let how = match self.ud.order_state(*cid).await {
                Ok(order) => {
                    self.on_order(&order);
                    continue;
                }
                Err(_) => "the broker does not know it".to_string(),
            };
            self.journal.set(*cid, Entry::Done(how));
            if self.working == Some(*cid) {
                self.working = None;
            }
        }
        self.need_reconcile = false;
        Ok(())
    }

    /// The loop calls this after every event.
    pub async fn recover_if_needed(
        &mut self,
        events: &mut mpsc::UnboundedReceiver<Envelope>,
    ) -> Result<(), Error> {
        if self.need_reconcile {
            // First the events that did arrive: they are the history up to the hole.
            while let Ok(env) = events.try_recv() {
                self.on_event(env).await?;
            }
            self.reconcile_now().await?;
        }
        Ok(())
    }
    // ANCHOR_END: recover

    // ANCHOR: stop
    /// A clean stop. No new orders. The bot takes its own working order off (a choice of THIS bot: the
    /// library never cancels anything on shutdown), waits for the final status, and writes it down.
    pub async fn stop(
        &mut self,
        events: &mut mpsc::UnboundedReceiver<Envelope>,
    ) -> Result<(), Error> {
        self.stopping = true;
        if let Some(cid) = self.working {
            for _ in 0..5 {
                match self.ud.cancel(cid).await {
                    Ok(()) => break,
                    // The order was filled before the cancel arrived: read the result instead.
                    Err(Error::Rejected { .. }) => break,
                    // Nothing was sent: wait, or reconcile, and try again. Leaving the order is not an option.
                    Err(Error::RateLimited { retry_after }) => {
                        tokio::time::sleep(retry_after).await
                    }
                    Err(Error::NotReconciled | Error::Degraded) => {
                        // Drain first: what did arrive is the history up to the hole.
                        while let Ok(env) = events.try_recv() {
                            self.on_event(env).await?;
                        }
                        self.reconcile_now().await?
                    }
                    // Maybe cancelled, maybe not: ask, and cancel again only if it still works.
                    Err(Error::Unknown | Error::Transport(_)) => {
                        if let Ok(order) = self.ud.order_state(cid).await {
                            self.on_order(&order);
                            if self.working != Some(cid) {
                                break;
                            }
                        }
                    }
                    Err(other) => return Err(other),
                }
            }
            // The final status comes on the stream; the read below is the proof.
            let _ = tokio::time::timeout(Duration::from_secs(5), async {
                while self.working.is_some() {
                    match events.recv().await {
                        Some(env) => self.on_event(env).await?,
                        None => break,
                    }
                }
                Ok::<(), Error>(())
            })
            .await;
            if self.working.is_some() {
                let order = self.ud.order_state(cid).await?;
                self.on_order(&order);
            }
            // Still working after all this: the order stays on the exchange. Say so, do not hide it.
            self.left_working = self.working;
        }
        Ok(())
    }
    // ANCHOR_END: stop
}

/// What the example's "exchange" does with the bot's order.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Ending {
    /// The exchange executes the order.
    Filled,
    /// The bot is told to stop while the order works, and cancels it.
    StoppedByBot,
}

/// The result the tests look at.
#[derive(Debug)]
pub struct Outcome {
    pub journal: Vec<(ClientOrderId, Entry)>,
    pub filled: Qty,
    pub price: Option<Price>,
}

/// Plays the bot on the BCS imitation. `ending` says how the order ends.
pub async fn run_bcs(ending: Ending) -> Result<Outcome, Box<dyn std::error::Error>> {
    // ANCHOR: wiring
    use brokapi::bcs::limits::default_limits;
    use brokapi::bcs::protocol::config::BcsConfig;
    use brokapi::bcs::{MarketDataConfig, MarketDataConnector, UserDataConfig, UserDataConnector};
    use brokapi::runtime::BrokerLimiter;

    let server = brokapi_mocks::bcs::MockServer::start(Default::default()).await;
    let cfg = BcsConfig::for_mock("mock-refresh-token", &server.http_base).with_write(true);

    // One limiter for the token (BCS counts limits per token), one channel for all events.
    let limiter = BrokerLimiter::new(&default_limits());
    let (tx, events) = mpsc::channel::<Envelope>(1024);
    let mut queue = forward(events);
    let md = MarketDataConnector::start(
        MarketDataConfig::new(cfg.clone(), "bcs-md"),
        limiter.clone(),
        tx.clone(),
    )
    .await?;
    let ud = UserDataConnector::start(UserDataConfig::new(cfg, "bcs-ud"), limiter, tx).await?;
    let grid = ud.price_grid().clone();

    let mut bot =
        TradingBot::start(&md, &ud, sber_bcs(), Journal::default(), &grid, "bcs-md").await?;
    // ANCHOR_END: wiring

    // ANCHOR: loop
    // The loop: events in, the bot decides. A deadline keeps the example from hanging if something is wrong.
    let deadline = tokio::time::Instant::now() + Duration::from_secs(20);
    let mut placed = None;
    let mut tick = tokio::time::interval(Duration::from_millis(250));
    loop {
        tokio::select! {
            env = tokio::time::timeout_at(deadline, queue.recv()) => {
                bot.on_event(env?.ok_or("the channel closed")?).await?;
            }
            _ = tick.tick() => bot.on_tick().await?,
        }
        bot.recover_if_needed(&mut queue).await?;

        // The example plays the exchange: once the order works, fill it, or ask the bot to stop.
        if ending == Ending::Filled
            && placed.is_some()
            && bot.working.is_none()
            && bot.filled().is_positive()
        {
            break; // the order is final and its fill is booked (the two events can come in either order)
        }
        if let Some(cid) = bot.working
            && placed != Some(cid)
        {
            placed = Some(cid);
            match ending {
                Ending::Filled => {
                    let price = Price::new(Decimal::new(24200, 2));
                    server.fill(&cid.hyphenated().to_string(), Qty::from(1), price);
                }
                Ending::StoppedByBot => break,
            }
        }
    }
    bot.stop(&mut queue).await?;
    // ANCHOR_END: loop

    let outcome = Outcome {
        journal: bot.journal.entries.clone(),
        filled: bot.filled(),
        price: bot.placed_price,
    };
    // ANCHOR: shutdown
    // The bot borrows the connectors and `shutdown` takes them by value: let the bot go first.
    drop(bot);
    // Stop the account connector first (no more commands), then the market data.
    let stop = ShutdownMode::Graceful {
        deadline: Duration::from_secs(5),
    };
    let report = ud.shutdown(stop).await;
    md.shutdown(stop).await;
    println!(
        "stopped: {} command(s) were left without an answer",
        report.inflight_abandoned.len()
    );
    // ANCHOR_END: shutdown
    Ok(outcome)
}

/// Plays the bot on the T-Bank imitation, where the answer to the first `place` is lost.
pub async fn run_tbank_unknown() -> Result<Outcome, Box<dyn std::error::Error>> {
    use std::sync::Arc;
    use std::sync::atomic::Ordering;

    use brokapi::runtime::BrokerLimiter;
    use brokapi::tbank::limits::default_limits;
    use brokapi::tbank::protocol::TbankConfig;
    use brokapi::tbank::{
        MarketDataConfig, MarketDataConnector, UserDataConfig, UserDataConnector,
    };
    use brokapi_mocks::tbank::{ACCOUNT_A, MockOptions, MockServer, TOKEN};

    // The mock answers a place 1.5 s late, the connector gives up after 200 ms: the answer is lost, the
    // order is not. That is a real `Unknown`.
    let opts = Arc::new(MockOptions::default());
    opts.post_delay_ms.store(1500, Ordering::SeqCst);
    let server = MockServer::start(opts).await;
    let cfg = TbankConfig::for_mock(TOKEN, &server.endpoint)
        .with_account(ACCOUNT_A)
        .with_request_timeout(Duration::from_millis(200));

    let limiter = BrokerLimiter::new(&default_limits());
    let (tx, events) = mpsc::channel::<Envelope>(1024);
    let mut queue = forward(events);
    let md = MarketDataConnector::start(
        MarketDataConfig::new(cfg.clone(), "tbank-md"),
        limiter.clone(),
        tx.clone(),
    )
    .await?;
    let ud = UserDataConnector::start(UserDataConfig::new(cfg, "tbank-ud"), limiter, tx).await?;
    let grid = ud.price_grid().clone();

    // T-Bank names an instrument by uid: ask the directory.
    let sber = md
        .find(InstrumentQuery::ByTicker {
            ticker: "SBER".into(),
            exchange: Some("TQBR".into()),
        })
        .await?
        .into_iter()
        .next()
        .ok_or("SBER is not in the directory")?
        .id;

    let mut bot = TradingBot::start(&md, &ud, sber, Journal::default(), &grid, "tbank-md").await?;
    let deadline = tokio::time::Instant::now() + Duration::from_secs(30);
    while bot.working.is_none() {
        let env = tokio::time::timeout_at(deadline, queue.recv())
            .await?
            .ok_or("the channel closed")?;
        bot.on_event(env).await?;
    }
    bot.stop(&mut queue).await?;

    let outcome = Outcome {
        journal: bot.journal.entries.clone(),
        filled: bot.filled(),
        price: bot.placed_price,
    };
    drop(bot);
    let stop = ShutdownMode::Graceful {
        deadline: Duration::from_secs(5),
    };
    ud.shutdown(stop).await;
    md.shutdown(stop).await;
    Ok(outcome)
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let outcome = run_bcs(Ending::Filled).await?;
    println!("journal: {:?}", outcome.journal);
    Ok(())
}

Как проверить результат

Что проверяют тесты. Цена заявки равна 99% лучшей цены покупки, округленной вниз до шага (241.85 при 244.30 и шаге 0.01). В журнале ровно одна запись. После исполнения запись filled, после остановки cancelled. В сценарии с потерянным ответом заявка одна.

Что менять под себя

• Стратегию: функция try_buy, место, где вычисляется цена и количество. Все вокруг нее оставьте.
• Брокера: замените подключение (wiring). Для Т-Банка идентификатор инструмента берется из справочника (find, пример run_tbank_unknown), для Финама собирается из SBER@MISX (Быстрый старт).
• Журнал: замените на файл или базу, запись до place с принудительной записью на диск.
• Несколько заявок и инструментов: состояние working станет таблицей по cid, очередь по бумаге библиотека держит сама (Круг команд).
• Боевой счет: сначала Перед запуском на настоящем счете.

Как собрать инфраструктуру на несколько брокеров и счетов (Rust)

Инструкция. Цель: один процесс держит несколько брокеров и счетов (БКС один, Т-Банк два на одном токене, Финам один, АЛОР один), все события идут в один канал, заявки пишутся в журнал в файле, а после рестарта каждый счет сверяется с журналом. Правила: Контракт для агентов, устройство: Несколько счетов и брокеров. Код ниже - куски программы examples/infrastructure.rs. Она запускается тестом против имитаций всех брокеров, и тест проходит две жизни процесса.

Что получится

На схеме: коннекторы, общий канал, счетчики лимитов (у каждого брокера свой), журнал. Т-Банк делит один счетчик между рынком и обоими счетами, потому что считает лимит на пользователя.

flowchart TB
  subgraph B[БКС: счетчик 1]
    direction LR
    BM[MD bcs-md] ~~~ BU[UD bcs]
  end
  subgraph T[Т-Банк: счетчик 2 на всех]
    direction LR
    TM[MD tbank-md] ~~~ TA[UD tbank-a] ~~~ TB2[UD tbank-b]
  end
  subgraph F[Финам: счетчик 3]
    direction LR
    FM[MD finam-md] ~~~ FU[UD finam]
  end
  subgraph A[АЛОР: счетчик 4]
    direction LR
    AM[MD alor-md] ~~~ AU[UD alor]
  end
  B ~~~ T ~~~ F ~~~ A
  A -- события всех коннекторов --> Q[(Один канал событий)]
  Q --> R[route: по env.source<br>в нужный счет]
  R --> J[(Журнал в файле)]
  J --> S[start: reconcile каждого счета<br>со своей частью журнала]

Из схемы следует: UD на счет, MD на брокера, счетчик на область квоты. Метка source у коннектора, которую вы задаете в настройке, - единственное, по чему в общем канале видно, чье событие. Поэтому метки UD равны именам счетов.

Подключение

[package]
name = "my-bot"
edition = "2024"   # нужен Rust 1.88 или новее: в коде книги цепочки let

[dependencies]
brokapi = { version = "0.1.0-alpha.5", features = ["bcs", "tbank", "finam", "alor"] }
tokio   = { version = "1", features = ["full"] }
dotenvy = "0.15"

use brokapi::core::{
    ClientOrderId, Envelope, Error, Event, ExecutionSource, InstrumentId, InstrumentQuery,
    InstrumentSource, NativeId, OrderExecutor, OrderState, OrderType, PlaceOrderRequest,
    PortfolioSource, Price, Qty, ReconcileReport, ShutdownMode, Side,
};
use brokapi::runtime::BrokerLimiter;
use tokio::sync::mpsc;

Настройки

Все, что нужно для подключения, в одной структуре. В боевом запуске она строится из окружения (BCS_REFRESH_TOKEN, TBANK_TOKEN, TBANK_ACCOUNT_ID, TBANK_ACCOUNT_ID_2, FINAM_SECRET, FINAM_ACCOUNT_ID), в примере - из имитаций.

/// What the process needs to connect. In production it comes from the environment (`from_env`), in the example from
/// the imitations.
pub struct Settings {
    pub bcs: brokapi::bcs::protocol::config::BcsConfig,
    pub tbank: brokapi::tbank::protocol::TbankConfig,
    /// Two accounts behind one T-Bank token.
    pub tbank_accounts: [String; 2],
    pub finam: brokapi::finam::FinamApiConfig,
    pub finam_account: String,
    pub alor: brokapi::alor::protocol::config::AlorConfig,
}

impl Settings {
    /// BCS_REFRESH_TOKEN, BCS_IS_WRITE, TBANK_TOKEN, TBANK_SANDBOX, TBANK_ACCOUNT_ID, TBANK_ACCOUNT_ID_2, FINAM_SECRET,
    /// FINAM_ACCOUNT_ID, ALOR_REFRESH_TOKEN, ALOR_PORTFOLIO.
    pub fn from_env() -> Result<Self, Box<dyn std::error::Error>> {
        dotenvy::dotenv().ok();
        let (finam, account) = brokapi::finam::api_config_from_env()?;
        Ok(Self {
            bcs: brokapi::bcs::protocol::config::BcsConfig::from_env()?,
            tbank: brokapi::tbank::protocol::TbankConfig::from_env()?,
            tbank_accounts: [
                std::env::var("TBANK_ACCOUNT_ID")?,
                std::env::var("TBANK_ACCOUNT_ID_2")?,
            ],
            finam,
            finam_account: account.ok_or("FINAM_ACCOUNT_ID is not set")?,
            alor: brokapi::alor::protocol::config::AlorConfig::from_env()?,
        })
    }
}

Для пробного запуска без брокеров те же настройки собираются из имитаций (запуск имитаций и их константы: Тесты против имитаций):

// The imitations live through both lives of the process, like the brokers do.
let bcs_server = mbcs::MockServer::start(Default::default()).await;
let tbank_server = mtbank::MockServer::start(Default::default()).await;
let finam_server = mfinam::MockServer::start().await;
let alor_server = malor::MockServer::start(Default::default()).await;
let settings = Settings {
    bcs: brokapi::bcs::protocol::config::BcsConfig::for_mock(
        "mock-refresh-token",
        &bcs_server.http_base,
    )
    .with_write(true),
    tbank: brokapi::tbank::protocol::TbankConfig::for_mock(
        mtbank::TOKEN,
        &tbank_server.endpoint,
    ),
    tbank_accounts: [mtbank::ACCOUNT_A.into(), mtbank::ACCOUNT_B.into()],
    finam: brokapi::finam::FinamApiConfig::new(mfinam::SECRET)
        .with_endpoint(finam_server.url.clone()),
    finam_account: "ACC1".into(),
    alor: brokapi::alor::protocol::config::AlorConfig::for_mock(
        "mock-refresh-token",
        &alor_server.http_base,
    ),
};

MD Т-Банка не привязан к счету: его конфиг без account_id. Счета выбирают конфиги UD.

Журнал заявок в файле

Текстовый файл, одна строка на изменение: счет, cid, состояние, пояснение. Для каждой записи вызывается sync_data: журнал должен быть на диске до вызова, который его требует. Побеждает последняя строка cid. Строка, оборванная падением, пропускается при чтении.

/// What the journal knows about an order.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum State {
    /// Written BEFORE `place`. After a crash the order may or may not exist at the broker.
    Sending,
    /// The broker has it and it works.
    Working,
    /// Final, with the text of how it ended.
    Done(String),
}

/// The order journal: a text file, one line per change, `account TAB cid TAB state TAB detail`. The last line of a cid
/// wins. Every line is flushed to disk before the call that needs it: a journal that is written after `place` loses
/// the order that a crash cuts in between.
pub struct Journal {
    path: PathBuf,
    file: File,
    orders: HashMap<ClientOrderId, (String, State)>,
}

impl Journal {
    /// Opens the file (creates it if there is none) and reads what an earlier life wrote.
    pub fn open(path: &Path) -> io::Result<Self> {
        let mut orders = HashMap::new();
        if path.exists() {
            for line in BufReader::new(File::open(path)?).lines() {
                let line = line?;
                let mut parts = line.splitn(4, '\t');
                let (Some(account), Some(cid), Some(state)) =
                    (parts.next(), parts.next(), parts.next())
                else {
                    continue; // a line cut by a crash: it carries no complete change
                };
                let Ok(cid) = cid.parse::<ClientOrderId>() else {
                    continue;
                };
                let state = match state {
                    "sending" => State::Sending,
                    "working" => State::Working,
                    _ => State::Done(parts.next().unwrap_or("").to_string()),
                };
                orders.insert(cid, (account.to_string(), state));
            }
        }
        let file = OpenOptions::new().create(true).append(true).open(path)?;
        Ok(Self {
            path: path.to_path_buf(),
            file,
            orders,
        })
    }

    /// Writes a change and waits until the disk has it.
    pub fn set(&mut self, account: &str, cid: ClientOrderId, state: State) -> io::Result<()> {
        let (word, detail) = match &state {
            State::Sending => ("sending", String::new()),
            State::Working => ("working", String::new()),
            State::Done(text) => ("done", text.replace(['\t', '\n', '\r'], " ")),
        };
        writeln!(self.file, "{account}\t{cid}\t{word}\t{detail}")?;
        self.file.sync_data()?;
        self.orders.insert(cid, (account.to_string(), state));
        Ok(())
    }

    pub fn state(&self, cid: ClientOrderId) -> Option<&State> {
        self.orders.get(&cid).map(|(_, s)| s)
    }

    /// The ledger of one account for `reconcile`: orders it believes are alive.
    pub fn live(&self, account: &str) -> Vec<ClientOrderId> {
        self.orders
            .iter()
            .filter(|(_, (a, s))| a == account && !matches!(s, State::Done(_)))
            .map(|(cid, _)| *cid)
            .collect()
    }
}

Что нужно процессу от счета

Три брокера - три разных типа коннекторов. Общий трейт Account (его реализуют все автоматически) дает единый вид, и остальной код не знает, какой это брокер. Исход place сведен к четырем вариантам. Чтобы убрать счет, например оставить один счет Т-Банка вместо двух, уберите его UD из Infra, из accounts() и из ACCOUNTS.

/// What the process needs from an account, whatever the broker is. A blanket impl makes every connector one.
pub trait Account: OrderExecutor + ExecutionSource + PortfolioSource {}
impl<T: OrderExecutor + ExecutionSource + PortfolioSource> Account for T {}

/// How a `place` ended, for the caller.
#[derive(Debug, PartialEq, Eq)]
pub enum Placed {
    /// The broker accepted it.
    Working,
    /// The broker refused it. No order exists.
    Refused(String),
    /// The command did not leave the process (gate closed, quota). No order exists, the cid is not spent.
    NotSent(String),
    /// The outcome is unknown. The journal says `Sending`; the next reconcile or `order_state` settles it.
    Unknown,
}

Запуск всех коннекторов

Порядок запуска: счетчики, канал, коннекторы, подписки на статусы и сделки каждого счета, и только потом reconcile каждого счета со своей частью журнала. У Финама один JWT на MD и UD (shared_tokens).

/// All the connectors of the process and the journal.
pub struct Infra {
    pub bcs_md: brokapi::bcs::MarketDataConnector,
    pub tbank_md: brokapi::tbank::MarketDataConnector,
    pub finam_md: brokapi::finam::MarketDataConnector,
    pub alor_md: brokapi::alor::MarketDataConnector,
    pub bcs: brokapi::bcs::UserDataConnector,
    pub tbank_a: brokapi::tbank::UserDataConnector,
    pub tbank_b: brokapi::tbank::UserDataConnector,
    pub finam: brokapi::finam::UserDataConnector,
    pub alor: brokapi::alor::UserDataConnector,
    pub journal: Journal,
    /// Accounts that lost events (`Overflow`): reconcile them before trading.
    pub degraded: Vec<&'static str>,
}

/// The names of the accounts: the journal key and the `source` label of the envelopes.
pub const ACCOUNTS: [&str; 5] = ["bcs", "tbank-a", "tbank-b", "finam", "alor"];

impl Infra {
    /// Connects everything, subscribes, reconciles every account with the journal, and only then returns.
    pub async fn start(
        settings: &Settings,
        journal_path: &Path,
    ) -> Result<(Self, mpsc::UnboundedReceiver<Envelope>), Box<dyn std::error::Error>> {
        use brokapi::{alor, bcs, finam, tbank};

        // One limiter per area where the broker counts a limit. T-Bank counts per user: both accounts and the market
        // data connector share one. BCS counts per token, Finam per user, ALOR per login. The brokers never share.
        let bcs_limits = BrokerLimiter::new(&bcs::limits::default_limits());
        let tbank_limits = BrokerLimiter::new(&tbank::limits::default_limits());
        let finam_limits = BrokerLimiter::new(&finam::limits::default_limits());
        let alor_limits = BrokerLimiter::new(&alor::limits::default_limits());

        // One channel for everything: the `source` label of an envelope says whose it is. A small task moves the
        // envelopes into the process's own queue at once, so the library's channel is always empty and the process
        // may wait for the brokers as long as it needs (rule 5 of the contract).
        let (tx, channel) = mpsc::channel::<Envelope>(8192);
        let events = forward(channel);

        // Finam: one secret, one JWT for the market data and the account.
        let finam_api = settings
            .finam
            .clone()
            .with_tokens(settings.finam.shared_tokens().await?);

        let infra = Self {
            bcs_md: bcs::MarketDataConnector::start(
                bcs::MarketDataConfig::new(settings.bcs.clone(), "bcs-md"),
                bcs_limits.clone(),
                tx.clone(),
            )
            .await?,
            tbank_md: tbank::MarketDataConnector::start(
                tbank::MarketDataConfig::new(settings.tbank.clone(), "tbank-md"),
                tbank_limits.clone(),
                tx.clone(),
            )
            .await?,
            finam_md: finam::MarketDataConnector::start(
                finam::MarketDataConfig::new(finam_api.clone(), "finam-md"),
                finam_limits.clone(),
                tx.clone(),
            )
            .await?,
            alor_md: alor::MarketDataConnector::start(
                alor::MarketDataConfig::new(settings.alor.clone(), "alor-md"),
                alor_limits.clone(),
                tx.clone(),
            )
            .await?,
            // The `source` of an account connector is the account name.
            bcs: bcs::UserDataConnector::start(
                bcs::UserDataConfig::new(settings.bcs.clone(), "bcs"),
                bcs_limits,
                tx.clone(),
            )
            .await?,
            tbank_a: tbank::UserDataConnector::start(
                tbank::UserDataConfig::new(
                    settings
                        .tbank
                        .clone()
                        .with_account(&settings.tbank_accounts[0]),
                    "tbank-a",
                ),
                tbank_limits.clone(),
                tx.clone(),
            )
            .await?,
            tbank_b: tbank::UserDataConnector::start(
                tbank::UserDataConfig::new(
                    settings
                        .tbank
                        .clone()
                        .with_account(&settings.tbank_accounts[1]),
                    "tbank-b",
                ),
                tbank_limits,
                tx.clone(),
            )
            .await?,
            finam: finam::UserDataConnector::start(
                finam::UserDataConfig::new(finam_api, &settings.finam_account, "finam"),
                finam_limits,
                tx.clone(),
            )
            .await?,
            alor: alor::UserDataConnector::start(
                alor::UserDataConfig::new(settings.alor.clone(), "alor"),
                alor_limits,
                tx,
            )
            .await?,
            journal: Journal::open(journal_path)?,
            degraded: Vec::new(),
        };

        // Subscribe to the statuses and fills of every account FIRST, then reconcile it with ITS part of the journal.
        for (_, account) in infra.accounts() {
            account.subscribe_order_state().await?;
            account.subscribe_executions().await?;
        }
        let mut infra = infra;
        for name in ACCOUNTS {
            infra.reconcile_retry(name).await?;
        }
        Ok((infra, events))
    }

    /// The accounts by name, as the trait the process needs.
    pub fn accounts(&self) -> [(&'static str, &dyn Account); 5] {
        [
            ("bcs", &self.bcs),
            ("tbank-a", &self.tbank_a),
            ("tbank-b", &self.tbank_b),
            ("finam", &self.finam),
            ("alor", &self.alor),
        ]
    }

    pub fn account(&self, name: &str) -> &dyn Account {
        self.accounts()
            .into_iter()
            .find(|(n, _)| *n == name)
            .map(|(_, a)| a)
            .unwrap_or_else(|| panic!("no account {name}"))
    }

Вспомогательные функции

Читатель канала (forward), слова состояний для журнала и распознавание «брокер не знает заявку». Последнее у брокеров разное: Все брокеры отвечают Error::Rejected с кодом not_found (проверка Error::is_not_found()). Терпение NOT_FOUND_PATIENCE в примере полсекунды для имитаций. Для настоящего брокера берите секунды.

/// How long a restarted process asks about an order the broker does not know, before it closes the journal line.
const NOT_FOUND_PATIENCE: Duration = Duration::from_millis(500);

/// The connectors write into a bounded channel and never wait for it: this task moves every envelope into the
/// process's own queue. The queue is unbounded, so watch its length.
fn forward(mut events: mpsc::Receiver<Envelope>) -> mpsc::UnboundedReceiver<Envelope> {
    let (queue_tx, queue) = mpsc::unbounded_channel();
    tokio::spawn(async move {
        while let Some(env) = events.recv().await {
            if queue_tx.send(env).is_err() {
                break;
            }
        }
    });
    queue
}

fn state_word(state: &OrderState) -> &'static str {
    match state {
        OrderState::InFlight { .. } => "in flight",
        OrderState::Unknown { .. } => "unknown",
        OrderState::Acked { .. } => "working",
        OrderState::PartiallyFilled { .. } => "partly filled",
        OrderState::Filled { .. } => "filled",
        OrderState::Cancelled { .. } => "cancelled",
        OrderState::Rejected { .. } => "rejected",
        _ => "unknown",
    }
}

/// "The broker does not know this order". All brokers say it as `Rejected` with the code `not_found`.
fn is_not_found(e: &Error) -> bool {
    e.is_not_found()
}

Сверка при старте и после сбоя

Каждый счет сверяется со своей частью журнала. Из отчета: confirmed - заявка стоит, closed_offline - ее нет среди живых, значит исполнилась, снялась, отклонилась или так и не была отправлена. Узнать итог можно запросом order_state. Если брокер заявку не знает даже после ожидания, значит, процесс упал между записью в журнал и вызовом place: запись закрывается как «не дошла». foreign показывается, но не трогается.

/// Reconciles one account with the journal and writes down what it found. The gate of the account opens only if
/// this succeeds; if it fails, repeat it later and do not trade on that account meanwhile.
pub async fn reconcile(&mut self, name: &'static str) -> Result<ReconcileReport, Error> {
    let ledger = self.journal.live(name);
    let report = self.account(name).reconcile(&ledger).await?;
    for order in &report.confirmed {
        self.write(name, order.cid, State::Working);
    }
    for cid in &report.closed_offline {
        // Not alive at the broker. Ask how it ended. "Not found" can also mean "never sent": a crash between the
        // journal line and the call. Both are final for the journal; a new order gets a new cid.
        let how = self.settle(name, *cid).await?;
        self.write(name, *cid, State::Done(how));
    }
    // report.foreign: orders nobody here placed. Shown, never touched.
    self.degraded.retain(|n| *n != name);
    Ok(report)
}

/// The final state of an order that is not alive any more, as text for the journal.
async fn settle(&self, name: &str, cid: ClientOrderId) -> Result<String, Error> {
    // How long "not found" may still change after a restart is not measured on a real broker: here half a second
    // is enough for the imitations, take seconds for a real one.
    let deadline = tokio::time::Instant::now() + NOT_FOUND_PATIENCE;
    loop {
        match self.account(name).order_state(cid).await {
            Ok(order) => return Ok(state_word(&order.state).to_string()),
            // The broker does not know it. Right after a cut that is not final, so wait a little.
            Err(e) if is_not_found(&e) => {}
            Err(Error::RateLimited { .. } | Error::Transport(_)) => {}
            Err(other) => return Err(other),
        }
        if tokio::time::Instant::now() >= deadline {
            return Ok("never reached the broker".to_string());
        }
        tokio::time::sleep(Duration::from_millis(100)).await;
    }
}

/// The journal must not lose a line. If the disk fails, trading must stop: there is nothing to say here.
fn write(&mut self, name: &str, cid: ClientOrderId, state: State) {
    self.journal
        .set(name, cid, state)
        .expect("the journal must be writable");
}

Сверка при старте идет через reconcile_retry: лимит или сбой сети не убивают процесс, а повторяются с паузой, остальные ошибки возвращаются. После Overflow счета из degraded сверяются методом recover: сначала очередь читается до конца, потом сверка.

/// A reconcile that does not give up on the first hiccup: a limit or a network error means "no sealed answer
/// yet", so wait and ask again, a few times. Any other error is returned: a retry would fail the same way.
pub async fn reconcile_retry(&mut self, name: &'static str) -> Result<ReconcileReport, Error> {
    let mut pause = Duration::from_millis(200);
    for attempt in 1..=5 {
        match self.reconcile(name).await {
            Ok(report) => return Ok(report),
            Err(Error::RateLimited { retry_after }) if attempt < 5 => {
                tokio::time::sleep(retry_after).await
            }
            Err(Error::Transport(_)) if attempt < 5 => {
                tokio::time::sleep(pause).await;
                pause *= 2;
            }
            Err(other) => return Err(other),
        }
    }
    unreachable!("the last attempt returns")
}

/// After `Overflow` (the accounts in `degraded`): read the queue to the end, THEN reconcile each such account.
/// The events that did arrive are the history up to the hole. The states after the hole come from the reconcile
/// and `order_state`; fills since the hole from `executions(range)` if the process keeps its own totals.
pub async fn recover(
    &mut self,
    events: &mut mpsc::UnboundedReceiver<Envelope>,
) -> Result<(), Error> {
    while let Ok(env) = events.try_recv() {
        self.route(env);
    }
    for name in std::mem::take(&mut self.degraded) {
        self.reconcile_retry(name).await?;
    }
    Ok(())
}

Заявка: журнал, вызов, журнал

/// Places an order on an account: journal first, then the command, then the journal again.
pub async fn place(&mut self, name: &'static str, req: PlaceOrderRequest) -> Placed {
    if self.degraded.contains(&name) {
        return Placed::NotSent("the account lost events, reconcile first".into());
    }
    let cid = req.cid;
    self.write(name, cid, State::Sending);
    match self.account(name).place(req).await {
        Ok(_) => {
            self.write(name, cid, State::Working);
            Placed::Working
        }
        Err(Error::Rejected { code, message }) => {
            self.write(name, cid, State::Done(format!("rejected {code}")));
            Placed::Refused(message)
        }
        // Nothing left the process: a closed gate, a local limit, a wrong setup, a missing capability, a stop.
        Err(
            e @ (Error::NotReconciled
            | Error::Degraded
            | Error::ShuttingDown
            | Error::RateLimited { .. }
            | Error::Config(_)
            | Error::Unsupported { .. }),
        ) => {
            self.write(name, cid, State::Done("not sent".into()));
            Placed::NotSent(e.to_string())
        }
        // Unknown or Transport: the order may exist. Leave `Sending`: it is in the ledger of the next reconcile.
        // An error a later version adds is treated the same way: the safe reading is "may exist".
        Err(_) => Placed::Unknown,
    }
}

Вариант NotSent покрывает все ошибки, при которых ничего не ушло: закрытый шлюз, остановка, локальный лимит, неверная настройка, неподдерживаемая возможность. Unknown и Transport оставляют заявку возможно существующей.

Unknown оставляет в журнале Sending. Эта запись попадет в список следующей сверки, и order_state скажет, чем кончилось. Повторять place нельзя.

Разбор общего канала

/// One envelope of the shared channel: the label says whose it is, the payload what to do with it.
pub fn route(&mut self, env: Envelope) {
    let Some(name) = ACCOUNTS.iter().copied().find(|n| **n == *env.source) else {
        return; // a market data connector: the strategy reads those, not the infrastructure
    };
    match env.payload {
        Event::Order(order) => {
            let state = match &order.state {
                OrderState::Acked { .. } | OrderState::PartiallyFilled { .. } => State::Working,
                OrderState::InFlight { .. } | OrderState::Unknown { .. } => return,
                final_state => State::Done(state_word(final_state).to_string()),
            };
            self.write(name, order.cid, state);
        }
        Event::Overflow { .. } => self.degraded.push(name),
        _ => {}
    }
}

Журнал не зависит от событий для правильности: place записывает Working по ответу, а сверка при старте исправит все остальное. События лишь ускоряют запись итогов. Поэтому для примера не важно, что статусы БКС приходят после подключения сокета в фоне (ловушка в тестах): потеряно только раннее событие, итог узнает сверка.

События маркетдаты (bcs-md, tbank-md, finam-md, alor-md) инфраструктура пропускает: их читает стратегия. Overflow счета помечает его как «сверить до торговли».

Остановка

/// Stops everything. Accounts first, so no command is taken while the market data is still closing. Orders at the
/// brokers are not touched.
pub async fn stop(self, mode: ShutdownMode) {
    self.bcs.shutdown(mode).await;
    self.tbank_a.shutdown(mode).await;
    self.tbank_b.shutdown(mode).await;
    self.finam.shutdown(mode).await;
    self.alor.shutdown(mode).await;
    self.bcs_md.shutdown(mode).await;
    self.tbank_md.shutdown(mode).await;
    self.finam_md.shutdown(mode).await;
    self.alor_md.shutdown(mode).await;
}

В отчете shutdown у БКС unsubscribed всегда 0: сессии WebSocket отписываются не отдельными сообщениями. У Т-Банка и Финама счет подписок считается.

Вся программа целиком

//! One process, several brokers and accounts: a shared event channel, one order journal in a file, and a restart
//! that reconciles every account against that journal.
//!
//! The code of the page "Как собрать инфраструктуру на несколько брокеров и счетов" of the book
//! (docs/src/rust/howto-infrastructure.md). The accounts are BCS (one), T-Bank (two, one token), Finam (one) and ALOR (one). `run` plays
//! two lives of the process against the in-process imitations: the first places an order on every account and goes away
//! without cancelling (and leaves a journal line for an order that was never sent), while the process is down one order
//! is filled, the second life reconciles every account with the journal and finds out what became of everything.
//! Nothing here touches the network or money.
//!
//! ```text
//! cargo run --example infrastructure
//! ```
#![allow(dead_code)]

use std::collections::HashMap;
use std::fs::{File, OpenOptions};
use std::io::{self, BufRead, BufReader, Write};
use std::path::{Path, PathBuf};
use std::time::Duration;

// ANCHOR: imports
use brokapi::core::{
    ClientOrderId, Envelope, Error, Event, ExecutionSource, InstrumentId, InstrumentQuery,
    InstrumentSource, NativeId, OrderExecutor, OrderState, OrderType, PlaceOrderRequest,
    PortfolioSource, Price, Qty, ReconcileReport, ShutdownMode, Side,
};
use brokapi::runtime::BrokerLimiter;
use tokio::sync::mpsc;
// ANCHOR_END: imports

// ANCHOR: journal
/// What the journal knows about an order.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum State {
    /// Written BEFORE `place`. After a crash the order may or may not exist at the broker.
    Sending,
    /// The broker has it and it works.
    Working,
    /// Final, with the text of how it ended.
    Done(String),
}

/// The order journal: a text file, one line per change, `account TAB cid TAB state TAB detail`. The last line of a cid
/// wins. Every line is flushed to disk before the call that needs it: a journal that is written after `place` loses
/// the order that a crash cuts in between.
pub struct Journal {
    path: PathBuf,
    file: File,
    orders: HashMap<ClientOrderId, (String, State)>,
}

impl Journal {
    /// Opens the file (creates it if there is none) and reads what an earlier life wrote.
    pub fn open(path: &Path) -> io::Result<Self> {
        let mut orders = HashMap::new();
        if path.exists() {
            for line in BufReader::new(File::open(path)?).lines() {
                let line = line?;
                let mut parts = line.splitn(4, '\t');
                let (Some(account), Some(cid), Some(state)) =
                    (parts.next(), parts.next(), parts.next())
                else {
                    continue; // a line cut by a crash: it carries no complete change
                };
                let Ok(cid) = cid.parse::<ClientOrderId>() else {
                    continue;
                };
                let state = match state {
                    "sending" => State::Sending,
                    "working" => State::Working,
                    _ => State::Done(parts.next().unwrap_or("").to_string()),
                };
                orders.insert(cid, (account.to_string(), state));
            }
        }
        let file = OpenOptions::new().create(true).append(true).open(path)?;
        Ok(Self {
            path: path.to_path_buf(),
            file,
            orders,
        })
    }

    /// Writes a change and waits until the disk has it.
    pub fn set(&mut self, account: &str, cid: ClientOrderId, state: State) -> io::Result<()> {
        let (word, detail) = match &state {
            State::Sending => ("sending", String::new()),
            State::Working => ("working", String::new()),
            State::Done(text) => ("done", text.replace(['\t', '\n', '\r'], " ")),
        };
        writeln!(self.file, "{account}\t{cid}\t{word}\t{detail}")?;
        self.file.sync_data()?;
        self.orders.insert(cid, (account.to_string(), state));
        Ok(())
    }

    pub fn state(&self, cid: ClientOrderId) -> Option<&State> {
        self.orders.get(&cid).map(|(_, s)| s)
    }

    /// The ledger of one account for `reconcile`: orders it believes are alive.
    pub fn live(&self, account: &str) -> Vec<ClientOrderId> {
        self.orders
            .iter()
            .filter(|(_, (a, s))| a == account && !matches!(s, State::Done(_)))
            .map(|(cid, _)| *cid)
            .collect()
    }
}
// ANCHOR_END: journal

// ANCHOR: settings
/// What the process needs to connect. In production it comes from the environment (`from_env`), in the example from
/// the imitations.
pub struct Settings {
    pub bcs: brokapi::bcs::protocol::config::BcsConfig,
    pub tbank: brokapi::tbank::protocol::TbankConfig,
    /// Two accounts behind one T-Bank token.
    pub tbank_accounts: [String; 2],
    pub finam: brokapi::finam::FinamApiConfig,
    pub finam_account: String,
    pub alor: brokapi::alor::protocol::config::AlorConfig,
}

impl Settings {
    /// BCS_REFRESH_TOKEN, BCS_IS_WRITE, TBANK_TOKEN, TBANK_SANDBOX, TBANK_ACCOUNT_ID, TBANK_ACCOUNT_ID_2, FINAM_SECRET,
    /// FINAM_ACCOUNT_ID, ALOR_REFRESH_TOKEN, ALOR_PORTFOLIO.
    pub fn from_env() -> Result<Self, Box<dyn std::error::Error>> {
        dotenvy::dotenv().ok();
        let (finam, account) = brokapi::finam::api_config_from_env()?;
        Ok(Self {
            bcs: brokapi::bcs::protocol::config::BcsConfig::from_env()?,
            tbank: brokapi::tbank::protocol::TbankConfig::from_env()?,
            tbank_accounts: [
                std::env::var("TBANK_ACCOUNT_ID")?,
                std::env::var("TBANK_ACCOUNT_ID_2")?,
            ],
            finam,
            finam_account: account.ok_or("FINAM_ACCOUNT_ID is not set")?,
            alor: brokapi::alor::protocol::config::AlorConfig::from_env()?,
        })
    }
}
// ANCHOR_END: settings

// ANCHOR: account
/// What the process needs from an account, whatever the broker is. A blanket impl makes every connector one.
pub trait Account: OrderExecutor + ExecutionSource + PortfolioSource {}
impl<T: OrderExecutor + ExecutionSource + PortfolioSource> Account for T {}

/// How a `place` ended, for the caller.
#[derive(Debug, PartialEq, Eq)]
pub enum Placed {
    /// The broker accepted it.
    Working,
    /// The broker refused it. No order exists.
    Refused(String),
    /// The command did not leave the process (gate closed, quota). No order exists, the cid is not spent.
    NotSent(String),
    /// The outcome is unknown. The journal says `Sending`; the next reconcile or `order_state` settles it.
    Unknown,
}
// ANCHOR_END: account

// ANCHOR: infra
/// All the connectors of the process and the journal.
pub struct Infra {
    pub bcs_md: brokapi::bcs::MarketDataConnector,
    pub tbank_md: brokapi::tbank::MarketDataConnector,
    pub finam_md: brokapi::finam::MarketDataConnector,
    pub alor_md: brokapi::alor::MarketDataConnector,
    pub bcs: brokapi::bcs::UserDataConnector,
    pub tbank_a: brokapi::tbank::UserDataConnector,
    pub tbank_b: brokapi::tbank::UserDataConnector,
    pub finam: brokapi::finam::UserDataConnector,
    pub alor: brokapi::alor::UserDataConnector,
    pub journal: Journal,
    /// Accounts that lost events (`Overflow`): reconcile them before trading.
    pub degraded: Vec<&'static str>,
}

/// The names of the accounts: the journal key and the `source` label of the envelopes.
pub const ACCOUNTS: [&str; 5] = ["bcs", "tbank-a", "tbank-b", "finam", "alor"];

impl Infra {
    /// Connects everything, subscribes, reconciles every account with the journal, and only then returns.
    pub async fn start(
        settings: &Settings,
        journal_path: &Path,
    ) -> Result<(Self, mpsc::UnboundedReceiver<Envelope>), Box<dyn std::error::Error>> {
        use brokapi::{alor, bcs, finam, tbank};

        // One limiter per area where the broker counts a limit. T-Bank counts per user: both accounts and the market
        // data connector share one. BCS counts per token, Finam per user, ALOR per login. The brokers never share.
        let bcs_limits = BrokerLimiter::new(&bcs::limits::default_limits());
        let tbank_limits = BrokerLimiter::new(&tbank::limits::default_limits());
        let finam_limits = BrokerLimiter::new(&finam::limits::default_limits());
        let alor_limits = BrokerLimiter::new(&alor::limits::default_limits());

        // One channel for everything: the `source` label of an envelope says whose it is. A small task moves the
        // envelopes into the process's own queue at once, so the library's channel is always empty and the process
        // may wait for the brokers as long as it needs (rule 5 of the contract).
        let (tx, channel) = mpsc::channel::<Envelope>(8192);
        let events = forward(channel);

        // Finam: one secret, one JWT for the market data and the account.
        let finam_api = settings
            .finam
            .clone()
            .with_tokens(settings.finam.shared_tokens().await?);

        let infra = Self {
            bcs_md: bcs::MarketDataConnector::start(
                bcs::MarketDataConfig::new(settings.bcs.clone(), "bcs-md"),
                bcs_limits.clone(),
                tx.clone(),
            )
            .await?,
            tbank_md: tbank::MarketDataConnector::start(
                tbank::MarketDataConfig::new(settings.tbank.clone(), "tbank-md"),
                tbank_limits.clone(),
                tx.clone(),
            )
            .await?,
            finam_md: finam::MarketDataConnector::start(
                finam::MarketDataConfig::new(finam_api.clone(), "finam-md"),
                finam_limits.clone(),
                tx.clone(),
            )
            .await?,
            alor_md: alor::MarketDataConnector::start(
                alor::MarketDataConfig::new(settings.alor.clone(), "alor-md"),
                alor_limits.clone(),
                tx.clone(),
            )
            .await?,
            // The `source` of an account connector is the account name.
            bcs: bcs::UserDataConnector::start(
                bcs::UserDataConfig::new(settings.bcs.clone(), "bcs"),
                bcs_limits,
                tx.clone(),
            )
            .await?,
            tbank_a: tbank::UserDataConnector::start(
                tbank::UserDataConfig::new(
                    settings
                        .tbank
                        .clone()
                        .with_account(&settings.tbank_accounts[0]),
                    "tbank-a",
                ),
                tbank_limits.clone(),
                tx.clone(),
            )
            .await?,
            tbank_b: tbank::UserDataConnector::start(
                tbank::UserDataConfig::new(
                    settings
                        .tbank
                        .clone()
                        .with_account(&settings.tbank_accounts[1]),
                    "tbank-b",
                ),
                tbank_limits,
                tx.clone(),
            )
            .await?,
            finam: finam::UserDataConnector::start(
                finam::UserDataConfig::new(finam_api, &settings.finam_account, "finam"),
                finam_limits,
                tx.clone(),
            )
            .await?,
            alor: alor::UserDataConnector::start(
                alor::UserDataConfig::new(settings.alor.clone(), "alor"),
                alor_limits,
                tx,
            )
            .await?,
            journal: Journal::open(journal_path)?,
            degraded: Vec::new(),
        };

        // Subscribe to the statuses and fills of every account FIRST, then reconcile it with ITS part of the journal.
        for (_, account) in infra.accounts() {
            account.subscribe_order_state().await?;
            account.subscribe_executions().await?;
        }
        let mut infra = infra;
        for name in ACCOUNTS {
            infra.reconcile_retry(name).await?;
        }
        Ok((infra, events))
    }

    /// The accounts by name, as the trait the process needs.
    pub fn accounts(&self) -> [(&'static str, &dyn Account); 5] {
        [
            ("bcs", &self.bcs),
            ("tbank-a", &self.tbank_a),
            ("tbank-b", &self.tbank_b),
            ("finam", &self.finam),
            ("alor", &self.alor),
        ]
    }

    pub fn account(&self, name: &str) -> &dyn Account {
        self.accounts()
            .into_iter()
            .find(|(n, _)| *n == name)
            .map(|(_, a)| a)
            .unwrap_or_else(|| panic!("no account {name}"))
    }
    // ANCHOR_END: infra

    // ANCHOR: recover
    /// A reconcile that does not give up on the first hiccup: a limit or a network error means "no sealed answer
    /// yet", so wait and ask again, a few times. Any other error is returned: a retry would fail the same way.
    pub async fn reconcile_retry(&mut self, name: &'static str) -> Result<ReconcileReport, Error> {
        let mut pause = Duration::from_millis(200);
        for attempt in 1..=5 {
            match self.reconcile(name).await {
                Ok(report) => return Ok(report),
                Err(Error::RateLimited { retry_after }) if attempt < 5 => {
                    tokio::time::sleep(retry_after).await
                }
                Err(Error::Transport(_)) if attempt < 5 => {
                    tokio::time::sleep(pause).await;
                    pause *= 2;
                }
                Err(other) => return Err(other),
            }
        }
        unreachable!("the last attempt returns")
    }

    /// After `Overflow` (the accounts in `degraded`): read the queue to the end, THEN reconcile each such account.
    /// The events that did arrive are the history up to the hole. The states after the hole come from the reconcile
    /// and `order_state`; fills since the hole from `executions(range)` if the process keeps its own totals.
    pub async fn recover(
        &mut self,
        events: &mut mpsc::UnboundedReceiver<Envelope>,
    ) -> Result<(), Error> {
        while let Ok(env) = events.try_recv() {
            self.route(env);
        }
        for name in std::mem::take(&mut self.degraded) {
            self.reconcile_retry(name).await?;
        }
        Ok(())
    }
    // ANCHOR_END: recover

    // ANCHOR: reconcile
    /// Reconciles one account with the journal and writes down what it found. The gate of the account opens only if
    /// this succeeds; if it fails, repeat it later and do not trade on that account meanwhile.
    pub async fn reconcile(&mut self, name: &'static str) -> Result<ReconcileReport, Error> {
        let ledger = self.journal.live(name);
        let report = self.account(name).reconcile(&ledger).await?;
        for order in &report.confirmed {
            self.write(name, order.cid, State::Working);
        }
        for cid in &report.closed_offline {
            // Not alive at the broker. Ask how it ended. "Not found" can also mean "never sent": a crash between the
            // journal line and the call. Both are final for the journal; a new order gets a new cid.
            let how = self.settle(name, *cid).await?;
            self.write(name, *cid, State::Done(how));
        }
        // report.foreign: orders nobody here placed. Shown, never touched.
        self.degraded.retain(|n| *n != name);
        Ok(report)
    }

    /// The final state of an order that is not alive any more, as text for the journal.
    async fn settle(&self, name: &str, cid: ClientOrderId) -> Result<String, Error> {
        // How long "not found" may still change after a restart is not measured on a real broker: here half a second
        // is enough for the imitations, take seconds for a real one.
        let deadline = tokio::time::Instant::now() + NOT_FOUND_PATIENCE;
        loop {
            match self.account(name).order_state(cid).await {
                Ok(order) => return Ok(state_word(&order.state).to_string()),
                // The broker does not know it. Right after a cut that is not final, so wait a little.
                Err(e) if is_not_found(&e) => {}
                Err(Error::RateLimited { .. } | Error::Transport(_)) => {}
                Err(other) => return Err(other),
            }
            if tokio::time::Instant::now() >= deadline {
                return Ok("never reached the broker".to_string());
            }
            tokio::time::sleep(Duration::from_millis(100)).await;
        }
    }

    /// The journal must not lose a line. If the disk fails, trading must stop: there is nothing to say here.
    fn write(&mut self, name: &str, cid: ClientOrderId, state: State) {
        self.journal
            .set(name, cid, state)
            .expect("the journal must be writable");
    }
    // ANCHOR_END: reconcile

    // ANCHOR: place
    /// Places an order on an account: journal first, then the command, then the journal again.
    pub async fn place(&mut self, name: &'static str, req: PlaceOrderRequest) -> Placed {
        if self.degraded.contains(&name) {
            return Placed::NotSent("the account lost events, reconcile first".into());
        }
        let cid = req.cid;
        self.write(name, cid, State::Sending);
        match self.account(name).place(req).await {
            Ok(_) => {
                self.write(name, cid, State::Working);
                Placed::Working
            }
            Err(Error::Rejected { code, message }) => {
                self.write(name, cid, State::Done(format!("rejected {code}")));
                Placed::Refused(message)
            }
            // Nothing left the process: a closed gate, a local limit, a wrong setup, a missing capability, a stop.
            Err(
                e @ (Error::NotReconciled
                | Error::Degraded
                | Error::ShuttingDown
                | Error::RateLimited { .. }
                | Error::Config(_)
                | Error::Unsupported { .. }),
            ) => {
                self.write(name, cid, State::Done("not sent".into()));
                Placed::NotSent(e.to_string())
            }
            // Unknown or Transport: the order may exist. Leave `Sending`: it is in the ledger of the next reconcile.
            // An error a later version adds is treated the same way: the safe reading is "may exist".
            Err(_) => Placed::Unknown,
        }
    }
    // ANCHOR_END: place

    // ANCHOR: route
    /// One envelope of the shared channel: the label says whose it is, the payload what to do with it.
    pub fn route(&mut self, env: Envelope) {
        let Some(name) = ACCOUNTS.iter().copied().find(|n| **n == *env.source) else {
            return; // a market data connector: the strategy reads those, not the infrastructure
        };
        match env.payload {
            Event::Order(order) => {
                let state = match &order.state {
                    OrderState::Acked { .. } | OrderState::PartiallyFilled { .. } => State::Working,
                    OrderState::InFlight { .. } | OrderState::Unknown { .. } => return,
                    final_state => State::Done(state_word(final_state).to_string()),
                };
                self.write(name, order.cid, state);
            }
            Event::Overflow { .. } => self.degraded.push(name),
            _ => {}
        }
    }
    // ANCHOR_END: route

    // ANCHOR: stop
    /// Stops everything. Accounts first, so no command is taken while the market data is still closing. Orders at the
    /// brokers are not touched.
    pub async fn stop(self, mode: ShutdownMode) {
        self.bcs.shutdown(mode).await;
        self.tbank_a.shutdown(mode).await;
        self.tbank_b.shutdown(mode).await;
        self.finam.shutdown(mode).await;
        self.alor.shutdown(mode).await;
        self.bcs_md.shutdown(mode).await;
        self.tbank_md.shutdown(mode).await;
        self.finam_md.shutdown(mode).await;
        self.alor_md.shutdown(mode).await;
    }
    // ANCHOR_END: stop
}

// ANCHOR: helpers
/// How long a restarted process asks about an order the broker does not know, before it closes the journal line.
const NOT_FOUND_PATIENCE: Duration = Duration::from_millis(500);

/// The connectors write into a bounded channel and never wait for it: this task moves every envelope into the
/// process's own queue. The queue is unbounded, so watch its length.
fn forward(mut events: mpsc::Receiver<Envelope>) -> mpsc::UnboundedReceiver<Envelope> {
    let (queue_tx, queue) = mpsc::unbounded_channel();
    tokio::spawn(async move {
        while let Some(env) = events.recv().await {
            if queue_tx.send(env).is_err() {
                break;
            }
        }
    });
    queue
}

fn state_word(state: &OrderState) -> &'static str {
    match state {
        OrderState::InFlight { .. } => "in flight",
        OrderState::Unknown { .. } => "unknown",
        OrderState::Acked { .. } => "working",
        OrderState::PartiallyFilled { .. } => "partly filled",
        OrderState::Filled { .. } => "filled",
        OrderState::Cancelled { .. } => "cancelled",
        OrderState::Rejected { .. } => "rejected",
        _ => "unknown",
    }
}

/// "The broker does not know this order". All brokers say it as `Rejected` with the code `not_found`.
fn is_not_found(e: &Error) -> bool {
    e.is_not_found()
}
// ANCHOR_END: helpers

/// The instrument of each account in the form its broker wants. In real code every one comes from `find`.
pub async fn sber_for(
    infra: &Infra,
    name: &str,
) -> Result<InstrumentId, Box<dyn std::error::Error>> {
    use brokapi::core::InstrumentKey;
    Ok(match name {
        "bcs" => InstrumentId::new(
            InstrumentKey::new("SBER", "TQBR"),
            NativeId::TickerClass {
                ticker: "SBER".into(),
                class_code: "TQBR".into(),
            },
        ),
        "tbank-a" | "tbank-b" => {
            infra
                .tbank_md
                .find(InstrumentQuery::ByTicker {
                    ticker: "SBER".into(),
                    exchange: Some("TQBR".into()),
                })
                .await?
                .into_iter()
                .next()
                .ok_or("SBER is not in the T-Bank directory")?
                .id
        }
        "alor" => brokapi::alor::util::instrument_id("SBER", "TQBR"),
        _ => brokapi::finam::util::instrument_from_symbol("SBER@MISX"),
    })
}

fn buy(instrument: InstrumentId, cid: ClientOrderId) -> PlaceOrderRequest {
    PlaceOrderRequest {
        cid,
        instrument,
        side: Side::Buy,
        order_type: OrderType::Limit,
        qty: Qty::from(10),
        price: Some(Price::from(200)),
    }
}

/// What the test looks at after the two lives.
#[derive(Debug)]
pub struct Result2 {
    pub cids: HashMap<&'static str, ClientOrderId>,
    pub orphan: ClientOrderId,
    pub journal: HashMap<ClientOrderId, State>,
    pub reports: HashMap<&'static str, (usize, usize, usize)>,
}

/// Reads the channel into the journal until `done` holds or `how_long` passes.
async fn pump(
    infra: &mut Infra,
    events: &mut mpsc::UnboundedReceiver<Envelope>,
    how_long: Duration,
    done: impl Fn(&Infra) -> bool,
) {
    let _ = tokio::time::timeout(how_long, async {
        while !done(infra) {
            match events.recv().await {
                Some(env) => infra.route(env),
                None => break,
            }
        }
    })
    .await;
}

/// The two lives of the process. `dir` holds the journal.
pub async fn run(dir: &Path) -> Result<Result2, Box<dyn std::error::Error>> {
    use brokapi_mocks::{alor as malor, bcs as mbcs, finam as mfinam, tbank as mtbank};

    // ANCHOR: mock_settings
    // The imitations live through both lives of the process, like the brokers do.
    let bcs_server = mbcs::MockServer::start(Default::default()).await;
    let tbank_server = mtbank::MockServer::start(Default::default()).await;
    let finam_server = mfinam::MockServer::start().await;
    let alor_server = malor::MockServer::start(Default::default()).await;
    let settings = Settings {
        bcs: brokapi::bcs::protocol::config::BcsConfig::for_mock(
            "mock-refresh-token",
            &bcs_server.http_base,
        )
        .with_write(true),
        tbank: brokapi::tbank::protocol::TbankConfig::for_mock(
            mtbank::TOKEN,
            &tbank_server.endpoint,
        ),
        tbank_accounts: [mtbank::ACCOUNT_A.into(), mtbank::ACCOUNT_B.into()],
        finam: brokapi::finam::FinamApiConfig::new(mfinam::SECRET)
            .with_endpoint(finam_server.url.clone()),
        finam_account: "ACC1".into(),
        alor: brokapi::alor::protocol::config::AlorConfig::for_mock(
            "mock-refresh-token",
            &alor_server.http_base,
        ),
    };
    // ANCHOR_END: mock_settings
    let journal_path = dir.join("orders.journal");
    let _ = std::fs::remove_file(&journal_path);

    // ---- first life: an order on every account, then the process goes away without cancelling anything.
    let (mut infra, mut events) = Infra::start(&settings, &journal_path).await?;
    let mut cids = HashMap::new();
    for name in ACCOUNTS {
        let cid = ClientOrderId::new_v4();
        let instrument = sber_for(&infra, name).await?;
        let placed = infra.place(name, buy(instrument, cid)).await;
        assert_eq!(placed, Placed::Working, "{name}");
        cids.insert(name, cid);
    }
    // The journal line of an order that a crash cut off before `place` was called.
    let orphan = ClientOrderId::new_v4();
    infra.journal.set("tbank-b", orphan, State::Sending)?;
    pump(&mut infra, &mut events, Duration::from_secs(5), |i| {
        ACCOUNTS
            .iter()
            .all(|n| i.journal.state(cids[n]) == Some(&State::Working))
    })
    .await;
    infra.stop(ShutdownMode::Immediate).await;
    println!("first life over: the orders stay on the exchanges");

    // ---- while the process is down, the order of T-Bank account A is executed.
    tbank_server.fill(mtbank::ACCOUNT_A, &cids["tbank-a"].hyphenated().to_string());

    // ---- second life: the journal is read, every account is reconciled with its part of it.
    let (mut infra, mut events) = Infra::start(&settings, &journal_path).await?;
    let mut reports = HashMap::new();
    for name in ACCOUNTS {
        // `start` reconciled already; a second reconcile is cheap, safe, and shows the report.
        let r = infra.reconcile(name).await?;
        reports.insert(
            name,
            (r.confirmed.len(), r.closed_offline.len(), r.foreign.len()),
        );
    }
    // Take the remaining orders off before leaving (a choice of this process; the library never does it).
    for name in ["bcs", "tbank-b", "finam", "alor"] {
        infra.account(name).cancel(cids[name]).await?;
    }
    pump(&mut infra, &mut events, Duration::from_secs(5), |i| {
        ["bcs", "tbank-b", "finam", "alor"]
            .iter()
            .all(|n| matches!(i.journal.state(cids[n]), Some(State::Done(_))))
    })
    .await;
    let journal = ACCOUNTS
        .iter()
        .map(|n| cids[n])
        .chain([orphan])
        .filter_map(|c| infra.journal.state(c).cloned().map(|s| (c, s)))
        .collect();
    // An account that lost events is reconciled after the queue is read to the end.
    infra.degraded.push("bcs");
    infra.recover(&mut events).await?;
    assert!(infra.degraded.is_empty());
    infra
        .stop(ShutdownMode::Graceful {
            deadline: Duration::from_secs(5),
        })
        .await;
    Ok(Result2 {
        cids,
        orphan,
        journal,
        reports,
    })
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let dir = std::env::temp_dir();
    let r = run(&dir).await?;
    for (account, cid) in &r.cids {
        println!("{account}: {cid} -> {:?}", r.journal[cid]);
    }
    Ok(())
}

Как проверить

cargo test --test examples infrastructure     # в клоне репозитория
cargo run --example infrastructure            # то же с выводом

Вне клона скопируйте файл программы выше в свой проект (зависимости как в начале страницы плюс brokapi-mocks) и вызовите run(&каталог) из main.

Тест проходит две жизни процесса. Первая: заявка на каждом из четырех счетов, плюс строка журнала для заявки, которая так и не была отправлена (падение между журналом и вызовом), процесс уходит, заявки остаются на бирже. Пока процесса нет, заявка Т-Банка (счет A) исполняется. Вторая жизнь читает журнал и сверяет каждый счет. Проверяется: исполненная заявка закрыта как filled, три живые найдены в confirmed и сняты процессом, неотправленная закрыта как «не дошла», чужих заявок нет.

Что менять под себя

• Состав счетов: добавьте UD и имя в ACCOUNTS и accounts(). Правило прежнее: UD на счет, MD на брокера, счетчик на область.
• Журнал: вместо файла любая база. Условие одно: запись дошла до диска до вызова.
• Стратегию подключите к route: рыночные события не обрабатываются инфраструктурой, их можно отдавать стратегии по env.source и env.sub.
• Автосверку после Overflow: degraded содержит счета, которые надо сверить. Вызовите reconcile для каждого, предварительно дочитав канал (Если что-то пошло не так).

Как собрать исследовательский движок

Инструкция. Цель: выгрузить длинную историю свечей и сделок по нескольким бумагам у нескольких брокеров, не нарушая лимитов, записать поток событий в файл и проиграть его из файла столько раз, сколько нужно для разбора. Правила: Контракт для агентов. Код ниже - куски программы examples/research.rs. Она запускается тестом против имитаций брокеров: имитации, как настоящие брокеры, отклоняют запрос длиннее предела и отдают ряд под заданный период.

Что получится

flowchart TB
  subgraph BR[Брокеры, у каждого свой счетчик лимитов]
    B[БКС: 1440 баров на запрос]
    T[Т-Банк: от суток до 10 лет<br>по таймфрейму]
    F[Финам: осторожные 500 баров]
    A[АЛОР: предел не назван,<br>окно задает бот]
  end
  BR --> W[CandlePages: окна по пределу,<br>ожидание RateLimited, склейка без дублей]
  W --> D[(Файлы баров по бумагам<br>файл сам себе контрольная точка)]
  BR --> L[Живой поток событий]
  L --> R[record: файл events.log]
  R --> P[replay: те же события из файла]
  L --> A1[analyze: живой разбор]
  P --> A2[analyze: разбор из файла]

Из схемы следует: история и живой поток независимы. Историю читают окнами по запросу, живой поток записывают как есть, и тот же разбор (analyze) читает и живой канал, и проигрыш из файла, получая одно и то же.

Подключение

[package]
name = "my-bot"
edition = "2024"   # нужен Rust 1.88 или новее: в коде книги цепочки let

[dependencies]
brokapi = { version = "0.1.0-alpha.5", features = ["bcs", "tbank", "finam", "alor"] }
tokio   = { version = "1", features = ["full"] }

use brokapi::core::{
    Candle, Envelope, Error, ErrorClass, Event, InstrumentId, InstrumentQuery, InstrumentSource,
    MarketDataSource, NativeId, OrderBook, OrderBookSource, SubscribeOpts, TimeRange, Timeframe,
    UnixNanos,
};
use brokapi::runtime::history::{CandlePages, HistoryError, HistoryOpts};
use brokapi::runtime::record::{EnvelopeReader, EnvelopeWriter, ReplaySpeed, replay};
use brokapi::runtime::{BrokerLimiter, BrokerLimits};
use tokio::sync::mpsc;

Как библиотека читает длинную историю

Один запрос свечей брокер принимает лишь в пределах: БКС не больше 1440 баров, Т-Банк по таблице (минутные бары за сутки, пятиминутные за неделю, часовые за 3 месяца, дневные за 6 лет, недельные за 5, месячные за 10 лет), Финам и АЛОР предел не называют (у АЛОРа candles_max_span пуст, и без окна вся история уходит одним запросом: задайте HistoryOpts::window, если нужно резать). Эти значения взяты из документации брокеров, их отдает метод candles_max_span(таймфрейм) коннектора. CandlePages из brokapi::runtime::history пользуется им:

• режет период на окна не длиннее предела и читает их по порядку, по одному за вызов next_page,
• на RateLimited ждет retry_after (не дольше max_rate_wait, не больше max_rate_waits раз на окно),
• на сетевой сбой (Transport) читает окно еще раз с растущей паузой: чтение безопасно повторять, команды - нет,
• на любой другой отказ останавливается и возвращает HistoryError с местом, откуда продолжить (resume_from);
• склеивает окна без дублей: бар, который вернули оба соседних окна (брокеры по-разному считают конец периода), остается один раз.

Если коннектор не знает предел (None), период идет одним запросом. Размер окна можно задать самому: HistoryOpts::window.

requests() считает вызовы candles, в том числе те, что локальный счетчик отказал (до брокера они не дошли). Сколько запросов реально ушло, считайте на стороне брокера (в тестах - счетчики имитаций). rate_waits() считает только ожидания внутри CandlePages.

Для данных на несколько тысяч баров есть load_candles: читает все в память одним вызовом.

Файлы с барами

Один файл на бумагу: текст, строка на бар (время, открытие, максимум, минимум, закрытие, объем). Текст нарочно: его читает любая программа, а начало файла остается правильным файлом. Контрольной точкой служит сам файл: где он кончается, там продолжается выгрузка. Состояние не может разойтись с данными, потому что отдельного состояния нет.

/// `<dir>/<venue>/<ticker>_H1.csv`: one line per bar, `open_ts_ns,open,high,low,close,volume`. Text on purpose: any tool
/// reads it, and a prefix of the file is still a valid file.
fn bars_path(dir: &Path, venue: &str, ticker: &str, tf: Timeframe) -> PathBuf {
    dir.join(venue).join(format!("{ticker}_{tf:?}.csv"))
}

/// After a crash the last line may be cut. Drop it, so the file ends with a whole line.
fn repair(path: &Path) -> std::io::Result<()> {
    if let Ok(bytes) = fs::read(path)
        && !bytes.is_empty()
        && bytes.last() != Some(&b'\n')
    {
        let keep = bytes.iter().rposition(|b| *b == b'\n').map_or(0, |i| i + 1);
        OpenOptions::new()
            .write(true)
            .open(path)?
            .set_len(keep as u64)?;
    }
    Ok(())
}

/// Where to continue: after the last bar on disk, or at `from` if there is none. Nothing else is stored: the file is
/// its own checkpoint, so it cannot disagree with itself.
fn resume_point(path: &Path, tf: Timeframe, from: UnixNanos) -> UnixNanos {
    let last = fs::read_to_string(path).ok().and_then(|text| {
        text.lines()
            .last()
            .and_then(|l| l.split(',').next())
            .and_then(|t| t.parse::<i64>().ok())
    });
    match last {
        Some(open) => UnixNanos::from_nanos(open + tf.seconds() as i64 * 1_000_000_000),
        None => from,
    }
}

fn rows(bars: &[Candle]) -> String {
    bars.iter()
        .map(|c| {
            format!(
                "{},{},{},{},{},{}\n",
                c.open_ts.as_nanos(),
                c.open,
                c.high,
                c.low,
                c.close,
                c.volume
            )
        })
        .collect()
}

Выгрузка

Сначала вспомогательная waiting: любое чтение тратит квоту, и find, и last_trades, и подписка, а не только свечи, и любое может вернуть RateLimited. CandlePages ждет сама, остальные чтения нет, их оборачивает waiting. Пример без нее ломается, как только бумаг больше, чем запас ведра (burst).

По брокерам выгрузка идет одновременно, по бумагам внутри брокера по очереди: у брокера один счетчик лимитов на все. Каждая страница пишется одним write_all и сразу sync_data, и только потом просится следующая.

/// Waits out `RateLimited` for any read. EVERY read spends quota, `find` and `last_trades` included, not only candles.
async fn waiting<T, F, Fut>(mut call: F) -> Result<T, Error>
where
    F: FnMut() -> Fut,
    Fut: std::future::Future<Output = Result<T, Error>>,
{
    for _ in 0..20 {
        match call().await {
            Err(Error::RateLimited { retry_after }) => tokio::time::sleep(retry_after).await,
            other => return other,
        }
    }
    call().await
}

/// Downloads `tf` bars of every instrument of the venue over `range` into files. Restart-safe: run it again after a
/// stop and it continues where each file ends. The library cuts the range into windows the broker accepts, waits out
/// the rate limit and joins the windows without duplicates; this function decides what happens to each page and to
/// each failure: a failure that may pass (`Retryable`) is waited out and the instrument is continued from its file, a
/// failure that will repeat (`Fatal`) is written to the report and the next instrument goes on.
pub async fn download(
    venue: &Venue<'_>,
    tf: Timeframe,
    range: TimeRange,
    dir: &Path,
) -> Result<VenueReport, Box<dyn std::error::Error + Send + Sync>> {
    let mut report = VenueReport::default();
    for (ticker, id) in &venue.instruments {
        let path = bars_path(dir, venue.name, ticker, tf);
        fs::create_dir_all(path.parent().expect("a file has a folder"))?;
        let mut attempts = 0;
        loop {
            repair(&path)?;
            let from = resume_point(&path, tf, range.from);
            let mut file = OpenOptions::new().create(true).append(true).open(&path)?;
            let mut pages = CandlePages::new(
                venue.md,
                id,
                tf,
                TimeRange::new(from, range.to),
                // The library repeats a window after a network error by itself: 2 times, the pause doubles.
                // A short first pause (the default is a second) keeps the demonstration quick.
                HistoryOpts {
                    transport_backoff: Duration::from_millis(20),
                    ..HistoryOpts::default()
                },
            );
            let outcome = loop {
                match pages.next_page().await {
                    Ok(Some(bars)) => {
                        // One write per page, then to disk. The page is on disk before the next one is asked for.
                        file.write_all(rows(&bars).as_bytes())?;
                        file.sync_data()?;
                        report.bars += bars.len();
                    }
                    Ok(None) => break Ok(()),
                    Err(e) => break Err(e),
                }
            };
            report.requests += pages.requests();
            report.rate_waits += pages.rate_waits();
            let HistoryError { error, .. } = match outcome {
                Ok(()) => break,
                Err(e) => e,
            };
            // Progress resets the patience: only an instrument that does not move at all gives up.
            if resume_point(&path, tf, range.from) > from {
                attempts = 0;
            }
            match error.class() {
                ErrorClass::Retryable if attempts < 5 => {
                    attempts += 1;
                    let pause = match error {
                        Error::RateLimited { retry_after } => retry_after,
                        _ => Duration::from_millis(500),
                    };
                    tokio::time::sleep(pause).await;
                }
                // Fatal (the same read fails again) or the patience is spent: write it down, go to the next one.
                _ => {
                    report.failed.push((ticker.clone(), error.to_string()));
                    break;
                }
            }
        }
    }
    Ok(report)
}

Что делает download с ошибками, по классу ошибки (error.class()):

Что делает тест. Год часовых баров по двум бумагам у всех брокеров, ровно 8760 баров на бумагу без пропусков и дублей. Число запросов к имитациям равно числу окон (БКС 7 на бумагу, Т-Банк 5, Финам 18, АЛОР 1: предел не назван). Счетчик лимитов в примере нарочно мал, поэтому движок несколько раз ждет и не падает. Повторный запуск ничего не просит у брокеров.

Сделки ленты

last_trades(инструмент, число) дает последние сделки ленты: сколько глубины, зависит от брокера (БКС: текущая сессия, Т-Банк: последний час). Глубокой истории сделок в общем интерфейсе нет. Живую ленту записывайте потоком subscribe_market_trades (режим DropNewest или Lossless, если терять сделки нельзя) в тот же журнал событий, что описан ниже.

Запись потока событий в файл

EnvelopeWriter из brokapi::runtime::record пишет конверты в любой Write: строка JSON на конверт, перед ними строка-заголовок с версией формата. Цены и количества записываются строками, поэтому возвращаются точно (244.30 остается 244.30).

/// Reads the live channel, writes every envelope to the log, and passes a copy on to the analysis. Stops after `max`
/// envelopes or when nothing comes for `quiet`.
pub async fn record(
    mut live: mpsc::Receiver<Envelope>,
    log: &Path,
    max: u64,
    quiet: Duration,
    to_analysis: mpsc::Sender<Envelope>,
) -> Result<u64, Box<dyn std::error::Error + Send + Sync>> {
    let mut writer = EnvelopeWriter::new(std::io::BufWriter::new(fs::File::create(log)?))?;
    while writer.written() < max {
        let Ok(Some(env)) = tokio::time::timeout(quiet, live.recv()).await else {
            break;
        };
        writer.write(&env)?;
        let _ = to_analysis.send(env).await;
    }
    let written = writer.written();
    writer.finish()?; // flushes: the tail of the file must not stay in a buffer
    Ok(written)
}

/// Plays the log into a channel as fast as the consumer reads. Nothing is lost: a replay waits for the consumer.
pub async fn play(
    log: &Path,
    to_analysis: mpsc::Sender<Envelope>,
) -> Result<u64, Box<dyn std::error::Error + Send + Sync>> {
    let reader = EnvelopeReader::new(BufReader::new(fs::File::open(log)?))?;
    let report = replay(reader, &to_analysis, ReplaySpeed::Instant).await?;
    Ok(report.sent)
}

Чего файл не хранит: монотонные часы rx_mono. После чтения в нем время чтения. Для порядка и замеров в проигрыше используйте rx_ts и broker_ts.

Проигрыш из файла

replay отправляет конверты в канал по порядку, как коннектор. Скорость: ReplaySpeed::Instant (насколько быстро читает потребитель) или Paced { factor, max_gap } (темп записи, деленный на factor, пауза не длиннее max_gap).

Отличие от живого потока. Проигрыш ждет потребителя (send().await), поэтому медленный потребитель замедляет проигрыш и ничего не теряется. Живой коннектор ждать не может и применяет режим подписки. Значит, проигрыш никогда не даст Overflow: код разбора Overflow нужно проверять отдельно.

Файл в формате с более новой версией читать нельзя: LogError::Schema. Поврежденная строка останавливает чтение с номером строки, пропустить ее молча нельзя.

Разбор, один для живого потока и для файла

/// A tiny analysis over an event stream: how many books came from which connector, and the last mid price of each.
/// The same function reads a live channel and a replay.
#[derive(Debug, Default, PartialEq, Eq)]
pub struct Stats {
    pub books: BTreeMap<String, usize>,
    pub last_mid: BTreeMap<String, String>,
}

pub async fn analyze(mut events: mpsc::Receiver<Envelope>) -> Stats {
    let mut stats = Stats::default();
    while let Some(env) = events.recv().await {
        if let Event::OrderBook(OrderBook::Snapshot { bids, asks, .. }) = env.payload
            && let (Some(bid), Some(ask)) = (bids.first(), asks.first())
        {
            *stats.books.entry(env.source.to_string()).or_default() += 1;
            // Exact arithmetic, no floats.
            let mid = (bid.price.decimal() + ask.price.decimal()) / brokapi::core::Decimal::from(2);
            stats
                .last_mid
                .insert(env.source.to_string(), mid.to_string());
        }
    }
    stats
}

Тест записывает 30 событий живого потока, проигрывает файл и проверяет, что число записанных равно числу проигранных и что разбор вернул одно и то же.

Вся программа целиком

//! A research engine: a year of candles from several brokers within their limits, written to disk and resumable, a live
//! event stream recorded to a file, and the same stream played back from that file.
//!
//! The code of the page "Как собрать исследовательский движок" of the book (docs/src/rust/howto-research.md). `run` works on
//! the in-process imitations of the brokers, which, like the real ones, refuse a candle request over their span
//! and answer a series for the range asked. Nothing here touches the network or money.
//!
//! ```text
//! cargo run --example research
//! ```
#![allow(dead_code)]

use std::collections::BTreeMap;
use std::fs::{self, OpenOptions};
use std::io::{BufReader, Write};
use std::path::{Path, PathBuf};
use std::time::Duration;

// ANCHOR: imports
use brokapi::core::{
    Candle, Envelope, Error, ErrorClass, Event, InstrumentId, InstrumentQuery, InstrumentSource,
    MarketDataSource, NativeId, OrderBook, OrderBookSource, SubscribeOpts, TimeRange, Timeframe,
    UnixNanos,
};
use brokapi::runtime::history::{CandlePages, HistoryError, HistoryOpts};
use brokapi::runtime::record::{EnvelopeReader, EnvelopeWriter, ReplaySpeed, replay};
use brokapi::runtime::{BrokerLimiter, BrokerLimits};
use tokio::sync::mpsc;
// ANCHOR_END: imports

/// What the engine needs from a market data connector, whatever the broker is.
pub trait Market: OrderBookSource + MarketDataSource + InstrumentSource {}
impl<T: OrderBookSource + MarketDataSource + InstrumentSource> Market for T {}

/// One broker as the engine sees it: a name, a connector, and the instruments to download.
pub struct Venue<'a> {
    pub name: &'static str,
    pub md: &'a dyn Market,
    pub instruments: Vec<(String, InstrumentId)>,
}

// ANCHOR: files
/// `<dir>/<venue>/<ticker>_H1.csv`: one line per bar, `open_ts_ns,open,high,low,close,volume`. Text on purpose: any tool
/// reads it, and a prefix of the file is still a valid file.
fn bars_path(dir: &Path, venue: &str, ticker: &str, tf: Timeframe) -> PathBuf {
    dir.join(venue).join(format!("{ticker}_{tf:?}.csv"))
}

/// After a crash the last line may be cut. Drop it, so the file ends with a whole line.
fn repair(path: &Path) -> std::io::Result<()> {
    if let Ok(bytes) = fs::read(path)
        && !bytes.is_empty()
        && bytes.last() != Some(&b'\n')
    {
        let keep = bytes.iter().rposition(|b| *b == b'\n').map_or(0, |i| i + 1);
        OpenOptions::new()
            .write(true)
            .open(path)?
            .set_len(keep as u64)?;
    }
    Ok(())
}

/// Where to continue: after the last bar on disk, or at `from` if there is none. Nothing else is stored: the file is
/// its own checkpoint, so it cannot disagree with itself.
fn resume_point(path: &Path, tf: Timeframe, from: UnixNanos) -> UnixNanos {
    let last = fs::read_to_string(path).ok().and_then(|text| {
        text.lines()
            .last()
            .and_then(|l| l.split(',').next())
            .and_then(|t| t.parse::<i64>().ok())
    });
    match last {
        Some(open) => UnixNanos::from_nanos(open + tf.seconds() as i64 * 1_000_000_000),
        None => from,
    }
}

fn rows(bars: &[Candle]) -> String {
    bars.iter()
        .map(|c| {
            format!(
                "{},{},{},{},{},{}\n",
                c.open_ts.as_nanos(),
                c.open,
                c.high,
                c.low,
                c.close,
                c.volume
            )
        })
        .collect()
}
// ANCHOR_END: files

/// What one venue's download did.
#[derive(Debug, Default, Clone)]
pub struct VenueReport {
    pub requests: u32,
    pub rate_waits: u32,
    pub bars: usize,
    /// Instruments that could not be finished: ticker and the reason.
    pub failed: Vec<(String, String)>,
}

// ANCHOR: download
/// Waits out `RateLimited` for any read. EVERY read spends quota, `find` and `last_trades` included, not only candles.
async fn waiting<T, F, Fut>(mut call: F) -> Result<T, Error>
where
    F: FnMut() -> Fut,
    Fut: std::future::Future<Output = Result<T, Error>>,
{
    for _ in 0..20 {
        match call().await {
            Err(Error::RateLimited { retry_after }) => tokio::time::sleep(retry_after).await,
            other => return other,
        }
    }
    call().await
}

/// Downloads `tf` bars of every instrument of the venue over `range` into files. Restart-safe: run it again after a
/// stop and it continues where each file ends. The library cuts the range into windows the broker accepts, waits out
/// the rate limit and joins the windows without duplicates; this function decides what happens to each page and to
/// each failure: a failure that may pass (`Retryable`) is waited out and the instrument is continued from its file, a
/// failure that will repeat (`Fatal`) is written to the report and the next instrument goes on.
pub async fn download(
    venue: &Venue<'_>,
    tf: Timeframe,
    range: TimeRange,
    dir: &Path,
) -> Result<VenueReport, Box<dyn std::error::Error + Send + Sync>> {
    let mut report = VenueReport::default();
    for (ticker, id) in &venue.instruments {
        let path = bars_path(dir, venue.name, ticker, tf);
        fs::create_dir_all(path.parent().expect("a file has a folder"))?;
        let mut attempts = 0;
        loop {
            repair(&path)?;
            let from = resume_point(&path, tf, range.from);
            let mut file = OpenOptions::new().create(true).append(true).open(&path)?;
            let mut pages = CandlePages::new(
                venue.md,
                id,
                tf,
                TimeRange::new(from, range.to),
                // The library repeats a window after a network error by itself: 2 times, the pause doubles.
                // A short first pause (the default is a second) keeps the demonstration quick.
                HistoryOpts {
                    transport_backoff: Duration::from_millis(20),
                    ..HistoryOpts::default()
                },
            );
            let outcome = loop {
                match pages.next_page().await {
                    Ok(Some(bars)) => {
                        // One write per page, then to disk. The page is on disk before the next one is asked for.
                        file.write_all(rows(&bars).as_bytes())?;
                        file.sync_data()?;
                        report.bars += bars.len();
                    }
                    Ok(None) => break Ok(()),
                    Err(e) => break Err(e),
                }
            };
            report.requests += pages.requests();
            report.rate_waits += pages.rate_waits();
            let HistoryError { error, .. } = match outcome {
                Ok(()) => break,
                Err(e) => e,
            };
            // Progress resets the patience: only an instrument that does not move at all gives up.
            if resume_point(&path, tf, range.from) > from {
                attempts = 0;
            }
            match error.class() {
                ErrorClass::Retryable if attempts < 5 => {
                    attempts += 1;
                    let pause = match error {
                        Error::RateLimited { retry_after } => retry_after,
                        _ => Duration::from_millis(500),
                    };
                    tokio::time::sleep(pause).await;
                }
                // Fatal (the same read fails again) or the patience is spent: write it down, go to the next one.
                _ => {
                    report.failed.push((ticker.clone(), error.to_string()));
                    break;
                }
            }
        }
    }
    Ok(report)
}
// ANCHOR_END: download

// ANCHOR: stats
/// A tiny analysis over an event stream: how many books came from which connector, and the last mid price of each.
/// The same function reads a live channel and a replay.
#[derive(Debug, Default, PartialEq, Eq)]
pub struct Stats {
    pub books: BTreeMap<String, usize>,
    pub last_mid: BTreeMap<String, String>,
}

pub async fn analyze(mut events: mpsc::Receiver<Envelope>) -> Stats {
    let mut stats = Stats::default();
    while let Some(env) = events.recv().await {
        if let Event::OrderBook(OrderBook::Snapshot { bids, asks, .. }) = env.payload
            && let (Some(bid), Some(ask)) = (bids.first(), asks.first())
        {
            *stats.books.entry(env.source.to_string()).or_default() += 1;
            // Exact arithmetic, no floats.
            let mid = (bid.price.decimal() + ask.price.decimal()) / brokapi::core::Decimal::from(2);
            stats
                .last_mid
                .insert(env.source.to_string(), mid.to_string());
        }
    }
    stats
}
// ANCHOR_END: stats

// ANCHOR: record
/// Reads the live channel, writes every envelope to the log, and passes a copy on to the analysis. Stops after `max`
/// envelopes or when nothing comes for `quiet`.
pub async fn record(
    mut live: mpsc::Receiver<Envelope>,
    log: &Path,
    max: u64,
    quiet: Duration,
    to_analysis: mpsc::Sender<Envelope>,
) -> Result<u64, Box<dyn std::error::Error + Send + Sync>> {
    let mut writer = EnvelopeWriter::new(std::io::BufWriter::new(fs::File::create(log)?))?;
    while writer.written() < max {
        let Ok(Some(env)) = tokio::time::timeout(quiet, live.recv()).await else {
            break;
        };
        writer.write(&env)?;
        let _ = to_analysis.send(env).await;
    }
    let written = writer.written();
    writer.finish()?; // flushes: the tail of the file must not stay in a buffer
    Ok(written)
}

/// Plays the log into a channel as fast as the consumer reads. Nothing is lost: a replay waits for the consumer.
pub async fn play(
    log: &Path,
    to_analysis: mpsc::Sender<Envelope>,
) -> Result<u64, Box<dyn std::error::Error + Send + Sync>> {
    let reader = EnvelopeReader::new(BufReader::new(fs::File::open(log)?))?;
    let report = replay(reader, &to_analysis, ReplaySpeed::Instant).await?;
    Ok(report.sent)
}
// ANCHOR_END: record

/// A deliberately small budget, so the history download has to wait for the limiter: a burst of 2, then one request
/// per 5 ms. The real defaults of each broker are in `brokapi::<broker>::limits::default_limits()`.
fn small_budget() -> std::sync::Arc<BrokerLimiter> {
    let raw = r#"
[demo.buckets.market]
rate = 200
per = "1s"
burst = 2
[demo.route]
"*" = ["market"]
[demo.conns]
max_conns = 4
max_subs_per_conn = 50
supports_multiplex = false
"#;
    BrokerLimiter::new(&BrokerLimits::from_toml_str(raw).expect("valid limits"))
}

/// Spends the burst of a budget as of 20 ms from now. The reads that follow are refused until the real clock
/// is past that moment, so the download has to wait for the limiter whatever the speed of the machine. (A
/// budget that only refills fast would make the waits depend on how quick the imitation answers.)
fn hold(budget: &BrokerLimiter) {
    let later = brokapi::runtime::now() + Duration::from_millis(20);
    while budget.acquire("GetCandles", later).is_ok() {}
}

/// What the test looks at.
#[derive(Debug)]
pub struct Result3 {
    pub reports: BTreeMap<&'static str, VenueReport>,
    pub second_run_requests: u32,
    pub recorded: u64,
    pub replayed: u64,
    pub live_stats: Stats,
    pub replay_stats: Stats,
    pub tbank_requests: Vec<(i32, i64, i64)>,
    pub bcs_requests: usize,
    pub finam_requests: usize,
    pub alor_requests: usize,
    /// T-Bank reads that the imitation refused for good: the engine writes the instruments to the report.
    pub fatal: VenueReport,
    /// T-Bank reads that failed twice on the network and then passed: the engine waited and went on.
    pub transient: VenueReport,
}

/// The whole engine on the imitations. `dir` holds the data files and the log.
pub async fn run(dir: &Path) -> Result<Result3, Box<dyn std::error::Error + Send + Sync>> {
    use brokapi::{alor, bcs, finam, tbank};
    use brokapi_mocks::{alor as malor, bcs as mbcs, finam as mfinam, tbank as mtbank};
    use std::sync::Arc;
    use std::sync::atomic::Ordering;

    // Imitations that answer a series for the asked range and refuse a range over the broker's span.
    let bcs_opts = Arc::new(mbcs::MockOptions::default());
    bcs_opts.synthetic_candles.store(true, Ordering::SeqCst);
    let bcs_server = mbcs::MockServer::start(bcs_opts.clone()).await;
    let tbank_opts = Arc::new(mtbank::MockOptions::default());
    tbank_opts.synthetic_candles.store(true, Ordering::SeqCst);
    let tbank_server = mtbank::MockServer::start(tbank_opts.clone()).await;
    let finam_server = mfinam::MockServer::start().await;
    finam_server
        .state
        .options
        .synthetic_candles
        .store(true, Ordering::SeqCst);

    let alor_opts = Arc::new(malor::MockOptions::default());
    let alor_server = malor::MockServer::start(alor_opts.clone()).await;

    // The small budgets of the brokers, kept here so that the download can start with them spent.
    let budgets = [
        small_budget(),
        small_budget(),
        small_budget(),
        small_budget(),
    ];

    // One channel for the live events of all the market data connectors.
    let (tx, live) = mpsc::channel::<Envelope>(4096);
    let finam_api =
        finam::FinamApiConfig::new(mfinam::SECRET).with_endpoint(finam_server.url.clone());
    let bcs_md = bcs::MarketDataConnector::start(
        bcs::MarketDataConfig::new(
            bcs::protocol::config::BcsConfig::for_mock("mock-refresh-token", &bcs_server.http_base),
            "bcs-md",
        ),
        Arc::clone(&budgets[0]),
        tx.clone(),
    )
    .await?;
    let tbank_md = tbank::MarketDataConnector::start(
        tbank::MarketDataConfig::new(
            tbank::protocol::TbankConfig::for_mock(mtbank::TOKEN, &tbank_server.endpoint),
            "tbank-md",
        ),
        Arc::clone(&budgets[1]),
        tx.clone(),
    )
    .await?;
    let finam_md = finam::MarketDataConnector::start(
        finam::MarketDataConfig::new(finam_api, "finam-md"),
        Arc::clone(&budgets[2]),
        tx.clone(),
    )
    .await?;
    let alor_md = alor::MarketDataConnector::start(
        alor::MarketDataConfig::new(
            alor::protocol::config::AlorConfig::for_mock(
                "mock-refresh-token",
                &alor_server.http_base,
            ),
            "alor-md",
        ),
        Arc::clone(&budgets[3]),
        tx,
    )
    .await?;

    // The instruments of each venue in its own form. In real code all of them come from `find`.
    let bcs_id = |t: &str| {
        InstrumentId::new(
            brokapi::core::InstrumentKey::new(t, "TQBR"),
            NativeId::TickerClass {
                ticker: t.into(),
                class_code: "TQBR".into(),
            },
        )
    };
    let mut tbank_ids = Vec::new();
    for t in ["SBER", "GAZP"] {
        let found = waiting(|| {
            tbank_md.find(InstrumentQuery::ByTicker {
                ticker: t.into(),
                exchange: Some("TQBR".into()),
            })
        })
        .await?;
        tbank_ids.push((
            t.to_string(),
            found.into_iter().next().ok_or("not in the directory")?.id,
        ));
    }
    let venues = vec![
        Venue {
            name: "bcs",
            md: &bcs_md,
            instruments: ["SBER", "GAZP"]
                .map(|t| (t.to_string(), bcs_id(t)))
                .to_vec(),
        },
        Venue {
            name: "tbank",
            md: &tbank_md,
            instruments: tbank_ids,
        },
        Venue {
            name: "finam",
            md: &finam_md,
            instruments: ["SBER", "GAZP"]
                .map(|t| {
                    (
                        t.to_string(),
                        finam::util::instrument_from_symbol(&format!("{t}@MISX")),
                    )
                })
                .to_vec(),
        },
        Venue {
            name: "alor",
            md: &alor_md,
            instruments: ["SBER", "GAZP"]
                .map(|t| (t.to_string(), alor::util::instrument_id(t, "TQBR")))
                .to_vec(),
        },
    ];

    // ---- 1. A year of hourly bars. The brokers are independent (own limits), so they run side by side.
    let year = TimeRange::new(
        UnixNanos::from_nanos(1_767_225_600_000_000_000), // 2026-01-01
        UnixNanos::from_nanos(1_798_761_600_000_000_000), // 2027-01-01
    );
    budgets.iter().for_each(|b| hold(b));
    let (r_bcs, r_tbank, r_finam, r_alor) = tokio::try_join!(
        download(&venues[0], Timeframe::H1, year, dir),
        download(&venues[1], Timeframe::H1, year, dir),
        download(&venues[2], Timeframe::H1, year, dir),
        download(&venues[3], Timeframe::H1, year, dir),
    )?;
    let mut reports = BTreeMap::new();
    reports.insert("bcs", r_bcs);
    reports.insert("tbank", r_tbank);
    reports.insert("finam", r_finam);
    reports.insert("alor", r_alor);

    // A second run finds every file complete and asks the brokers for nothing.
    let again = download(&venues[0], Timeframe::H1, year, dir).await?;

    // What the brokers saw for the main download (the scenarios below add requests of their own).
    let tbank_requests = tbank_opts.candle_requests.lock().unwrap().clone();
    let bcs_requests = bcs_opts.candle_requests.lock().unwrap().len();
    let finam_requests = finam_server
        .state
        .options
        .bars_requests
        .lock()
        .unwrap()
        .len();

    let alor_requests = alor_opts.history_requests.lock().unwrap().len();

    // A read the broker refuses for good (`Rejected`) ends in the report, the engine goes on with the next instrument.
    tbank_opts.candle_fail.store(1, Ordering::SeqCst);
    let fatal = download(&venues[1], Timeframe::H1, year, &dir.join("fatal")).await?;
    // A read that fails on the network: the engine waits and continues from the file. The imitation fails the
    // next two calls and then heals.
    tbank_opts.candle_fail.store(0, Ordering::SeqCst);
    tbank_opts
        .candle_network_failures
        .store(2, Ordering::SeqCst);
    let transient = download(&venues[1], Timeframe::H1, year, &dir.join("transient")).await?;

    // ---- 2. The deals of the tape: the latest ones, to a file of their own.
    for v in &venues {
        let (ticker, id) = &v.instruments[0];
        let trades = waiting(|| v.md.last_trades(id, 50)).await?;
        let mut out = String::new();
        for t in &trades {
            out.push_str(&format!(
                "{},{},{},{:?}\n",
                t.ts.rx_ts.as_nanos(),
                t.price,
                t.qty,
                t.side
            ));
        }
        fs::write(dir.join(v.name).join(format!("{ticker}_trades.csv")), out)?;
    }

    // ---- 3. Record the live stream while an analysis reads the same events.
    for v in &venues {
        let (_, id) = &v.instruments[0];
        waiting(|| v.md.subscribe_order_book(id, SubscribeOpts::conflate())).await?;
    }
    let (tee_tx, tee_rx) = mpsc::channel::<Envelope>(4096);
    let analysis = tokio::spawn(analyze(tee_rx));
    let log = dir.join("events.log");
    let recorded = record(live, &log, 30, Duration::from_secs(3), tee_tx).await?;
    let live_stats = analysis.await?;

    // ---- 4. The same events again, from the file.
    let (play_tx, play_rx) = mpsc::channel::<Envelope>(16);
    let analysis = tokio::spawn(analyze(play_rx));
    let replayed = play(&log, play_tx).await?;
    let replay_stats = analysis.await?;

    // Stop the connectors (the borrows of `venues` end here).
    drop(venues);
    let stop = brokapi::core::ShutdownMode::Immediate;
    bcs_md.shutdown(stop).await;
    tbank_md.shutdown(stop).await;
    finam_md.shutdown(stop).await;
    alor_md.shutdown(stop).await;
    Ok(Result3 {
        reports,
        second_run_requests: again.requests,
        recorded,
        replayed,
        live_stats,
        replay_stats,
        tbank_requests,
        bcs_requests,
        finam_requests,
        alor_requests,
        fatal,
        transient,
    })
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let dir = std::env::temp_dir().join("brokapi-research");
    let r = run(&dir).await?;
    println!("{:#?}", r.reports);
    Ok(())
}

Как проверить

cargo test --test examples research
cargo run --example research        # то же с выводом отчета по брокерам

Сверка с NautilusTrader и пределы подхода

NautilusTrader хранит данные в каталоге Parquet с запросами по инструменту и времени и проигрывает их в бэктесте. В brokapi взят самый простой вариант без зависимостей: текстовые файлы баров и журнал событий в JSON-строках.

Для лет данных и частых запросов берите каталог: тот же поток конвертов можно складывать в Parquet своим кодом, формат Envelope стабилен (schema) и сериализуется через serde.

Что менять под себя

• Таймфрейм и период: параметры download. M10 у БКС не поддерживается (Unsupported).
• Бумаги: список в Venue. В боевом коде идентификаторы берутся из find.
• Куда писать: вместо файлов любая база. Условие то же: страница на диске до следующего запроса.
• Лимиты: HistoryOpts (max_rate_waits, max_rate_wait, transport_retries) и сами лимиты брокера (limits_from_toml_path, Лимиты запросов).

Запуск, рестарт и остановка бота

Инструкция: что делать боту при старте, после рестарта и при остановке, в каком порядке и что при этом должно быть видно. Почему порядок именно такой, объяснено на странице Круг жизни. Код ниже - куски программы examples/lifecycle.rs: она запускается тестом против имитации БКС, поэтому текст и проверенный код не расходятся. Программа играет два запуска бота: первый ставит заявку и уходит, не снимая ее, второй стартует, сверяется с журналом и находит эту заявку.

Старт и рестарт

Старт и рестарт - одна процедура. На первом запуске журнал бота пуст, на втором в нем лежат cid заявок, которые бот считал живыми.

1. Поднять коннекторы. start(конфиг, счетчик_лимитов, канал_событий). Шлюз команд после этого закрыт.
2. Подписаться на статусы заявок и исполнения. Подписки при закрытом шлюзе разрешены.

// Second run, after a restart. The gate is closed after `start`: commands return NotReconciled.
let (ud, mut events) = start_ud(cfg).await?;
// Subscribe BEFORE the reconcile: an event between the snapshot and the subscription would be lost.
ud.subscribe_order_state().await?;

Вы должны увидеть: start вернул коннектор без ошибки. Если вернулась ошибка, токен не подошел (у БКС и Финама start сразу авторизуется, у Т-Банка при заданном счете первая проверка будет при первом запросе). Любая торговая команда сейчас вернет NotReconciled, и это правильно.

3. Достать из журнала cid заявок, считавшихся живыми, и вызвать reconcile.
4. Разобрать три списка.

// The journal says which orders the bot thinks are alive.
let report = ud.reconcile(&journal).await?;
for order in &report.confirmed {
    println!(
        "confirmed {}: still at the broker, filled {}",
        order.cid,
        order.filled.decimal()
    );
}
for cid in &report.closed_offline {
    // Find out how it ended: order_state(cid) and executions(...), then write it to the journal.
    println!("closed offline {cid}: ask order_state and write the result");
}
for order in &report.foreign {
    // Not ours. Do not touch: a person decides.
    println!("foreign {}: shown to a person", order.cid);
}

Вы должны увидеть строку confirmed ... для каждой заявки, которая стоит у брокера. Если reconcile вернул ошибку, шлюз не открыт: подождите и вызовите еще раз. Ошибка ничего не говорит о заявках. Что делать с каждым списком:

• confirmed: сверить с журналом состояние и исполненный объем, поправить. Продолжать вести.
• closed_offline: для каждого запросить итог (order_state, executions) и записать в журнал.
• foreign: показать человеку или записать в журнал как чужие. Не снимать и не менять: бот не знает, зачем заявку поставили. Если такую заявку снять, можно сломать чужую стратегию.

5. Для стоп-заявок отдельно вызвать active_stop_orders(): обычная сверка их не показывает (Стоп-заявки).
6. Работать. Шлюз открыт.

// The gate is open now. The bot trades. Here it takes its own order off.
ud.cancel(cid).await?;
journal.clear();

Если пропустить шаги 2-3 и сразу ставить заявки, получите NotReconciled. Если подписаться после сверки, события, пришедшие между снимком и подпиской, потеряются.

Остановка

shutdown(режим) останавливает коннектор. Он забирает коннектор по значению, после вызова пользоваться им нельзя. Режимы:

• Graceful { deadline } - аккуратно: закрыть подписки штатным способом брокера и дождаться подтверждений не дольше deadline.
• Immediate - сразу, без отписок.

// Stop: new commands get ShuttingDown, subscriptions are closed, the report says what was left.
let report = ud
    .shutdown(ShutdownMode::Graceful {
        deadline: Duration::from_secs(5),
    })
    .await;
println!(
    "stopped: {} subscription(s) closed, {} failed, {} command(s) without an answer",
    report.unsubscribed,
    report.unsubscribe_failed,
    report.inflight_abandoned.len()
);

Что происходит по шагам:

1. Новые торговые команды получают ShuttingDown. Шлюз закрывается навсегда.
2. (Graceful) Подписки закрываются. У gRPC-брокеров закрытие вызова и есть отписка, у MD БКС отправляется сообщение отписки.
3. Заявки, у которых еще нет ответа, не ждутся и не повторяются: они локально переводятся в Unknown, а список возвращается в отчете (ShutdownReport.inflight_abandoned). У Т-Банка на каждую такую заявку еще уходит событие. Почему не ждутся: повторить их нельзя, а ждать вечно нельзя.
4. Задачи останавливаются.

Вы должны увидеть отчет: сколько подписок закрыто (unsubscribed), сколько закрыть не удалось (unsubscribe_failed), какие заявки остались без ответа (inflight_abandoned). Если список не пуст, при следующем запуске эти cid должны быть в журнале как «проверить»: reconcile вернет их как confirmed или closed_offline.

Заявки на бирже при остановке не затрагиваются. Если до остановки заявка была принята, она останется на бирже, а при следующем запуске ее подхватит сверка. Снять заявки перед выходом - решение бота: библиотека этого не делает, потому что «снять все» может быть неверным решением (например, защитный стоп должен пережить бота). Порядок остановки нескольких коннекторов тоже за ботом: обычно сначала UD (чтобы не принимать команды), потом MD.

Если что-то пошло не так

Инструкции на случаи, когда бот не знает, что со счетом: у заявки нет ответа, канал событий переполнился, пропала связь. Что означает каждая ошибка и состояние, - на странице Ошибки и что с ними делать, почему библиотека устроена так - в Круге команд и Круге жизни. Код - куски программы examples/recovery.rs, она запускается тестом против имитации: Unknown там настоящий, получен таймаутом на имитации Т-Банка.

place вернул Unknown

Заявка ушла к брокеру, ответа нет. Она могла встать, могла не дойти. Не повторяйте place: если первая встала, на счете окажутся две заявки. Вместо повтора спросите брокера по тому же cid.

flowchart TB
  U[place вернул Unknown] --> S[order_state по cid]
  S --> Q{Что ответил брокер}
  Q -- заявка есть --> A[Работать как с обычной:<br>Acked, Filled, Cancelled...]
  Q -- заявки нет --> W[Подождать несколько секунд<br>и спросить еще раз]
  W --> Q2{Появилась}
  Q2 -- да --> A
  Q2 -- нет --> N[Заявки нет. Поставить новую<br>с новым cid, если еще нужно]

На схеме: путь от Unknown до решения. Из нее следует: «заявки нет» сразу после обрыва не окончательно, запрос, ушедший в сеть, мог дойти позже, поэтому один отрицательный ответ ничего не доказывает.

/// `place` answered `Unknown`: ask the broker about the `cid` until it answers or `patience` runs out.
///
/// `Ok(Some(order))` - the order exists, continue with its state. `Ok(None)` - the broker still does not
/// know it after `patience`: it was not placed, and a new order needs a NEW `cid`.
pub async fn resolve_unknown<U: OrderExecutor>(
    ud: &U,
    cid: ClientOrderId,
    patience: Duration,
) -> Result<Option<OrderSnapshot>, Error> {
    let deadline = tokio::time::Instant::now() + patience;
    loop {
        match ud.order_state(cid).await {
            Ok(order) => return Ok(Some(order)),
            // "Not found" right after a cut is not final: the request may still be on its way.
            Err(e) if e.is_not_found() => {}
            // A limit or a network error says nothing about the order: wait and ask again.
            Err(Error::RateLimited { .. } | Error::Transport(_)) => {}
            Err(other) => return Err(other),
        }
        if tokio::time::Instant::now() >= deadline {
            return Ok(None);
        }
        tokio::time::sleep(Duration::from_millis(100)).await;
    }
}

Вы должны увидеть: функция вернула Some(заявка), если брокер ее знает, и None, если не знает и после ожидания. Как это читается:

• order_state(cid) возвращает состояние заявки по вашему cid. Если брокер такой заявки не знает, вернется Rejected (код not_found, одинаковый у всех).
• Брокер срок не называет, поэтому ожидание ограничивайте своим временем, а не ждите бесконечно.
• Если в игру вступает сомнение (например, заявка могла исполниться и исчезнуть из активных), смотрите executions и portfolio.
• При следующем запуске бота reconcile вернет такую заявку как confirmed или closed_offline.
• Вторую заявку ставьте только когда убедились, что первой нет. Номер нужен новый: старый библиотека не отправит (duplicate_place).
• Для cancel с Unknown отмену можно повторить вручную после проверки order_state: повторная отмена новых заявок не создает. Для replace спрашивайте состояние по обоим номерам, исходному и новому.

Пришел Overflow или ошибка Degraded

Буфер подписки без потерь переполнился: бот читал канал медленнее, чем шли события. Часть событий о своих заявках могла пропасть, поэтому торговля закрыта, пока вы не сверитесь со счетом. Что делать, по порядку:

1. Дочитать канал событий до пустого. То, что дошло, обработайте до сверки: это события до дыры.
2. Вызвать reconcile(&журнал). Успех снимает Degraded, подписки снова принимают события.
3. Восстановить пропущенное из снимков: состояние заявок из confirmed и order_state, сделки из executions(...) с момента lost_from из Overflow, портфель из portfolio().
4. Вернуться к работе.

/// `Event::Overflow` came, or a command returned `Degraded`: read the channel to the end, then reconcile.
///
/// `handle` gets every event that was waiting, so nothing that did arrive is lost. A successful
/// `reconcile` opens the gate again. After it, restore what was lost from the snapshots: the states in
/// `confirmed`, the fills from `executions(...)` since `lost_from`, the portfolio from `portfolio()`.
pub async fn after_overflow<U: OrderExecutor>(
    ud: &U,
    events: &mut mpsc::Receiver<Envelope>,
    ledger: &[ClientOrderId],
    mut handle: impl FnMut(Envelope),
) -> Result<ReconcileReport, Error> {
    while let Ok(env) = events.try_recv() {
        handle(env);
    }
    ud.reconcile(ledger).await
}

Вы должны увидеть: функция вернула отчет сверки, а следующий place перестал отвечать Degraded. Если reconcile вернул ошибку, шлюз остался закрытым, повторите позже. Для рыночных подписок сверки нет, поэтому после Overflow такую подписку снимают (unsubscribe) и оформляют заново. Чтобы переполнения не было: читайте канал отдельной задачей и не делайте в ней долгих операций, размер буфера подбирайте с запасом на всплеск (Круг событий).

Поток заявок оборвался

Соединения коннектор восстанавливает сам, а бот узнает об обрыве потока заявок или потока исполнений по событию Event::Reconnected { sub, gap_from }. Оно приходит, когда поток снова открыт, а за время обрыва могли пройти события, которых бот не видел: заявка исполнилась, снялась, была отклонена. Это то же состояние, что после Overflow: шлюз закрыт (Degraded), команды в сеть не уходят.

1. Дочитайте канал до конца. События до дыры нужны как обычно.
2. Прочитайте состояние у брокера: active_orders(), order_state(cid) по своим заявкам в пути, executions(range), где range начинается с запасом раньше gap_from.
3. Вызовите reconcile(&журнал). Успешная сверка открывает шлюз, следующий place проходит.

if let Event::Reconnected { sub, gap_from } = &env.payload {
    // 1. the events before the hole were handled as always
    // 2. read what the broker has: orders and fills since a little before `gap_from`
    let live = ud.active_orders().await?;
    let since = TimeRange::new(UnixNanos::from_nanos(gap_from.as_nanos() - 60_000_000_000), UnixNanos::from_nanos(i64::MAX / 2));
    let fills = ud.executions(since).await?;
    // 3. the gate opens
    ud.reconcile(&journal.live()).await?;
}

Если вы не слушаете события, а хотите узнать о закрытом шлюзе по ошибке, это Error::Degraded на команде, и действия те же. Потеря связи без Reconnected (например, поток молчит, но не оборван) бывает, если сам брокер перестал присылать события. Такое в коде не обнаруживается. Если связь была потеряна надолго или вы не уверены в журнале, зовите reconcile: он безопасен и ничего не меняет на счете.

Что приходит сверх события, по брокерам: у Т-Банка коннектор сам перечитывает активные заявки и присылает изменившиеся, у БКС и Финама нет. Поэтому после Reconnected читайте состояние сами, не ждите, что события наверстают.

Другие случаи, когда звать reconcile

• Не уверены в журнале. Вызов только читает, его можно делать в любой момент и сколько угодно раз.
• NotReconciled на команде. После запуска не было успешной сверки: вызовите reconcile, потом повторите команду, cid годен (Запуск, рестарт и остановка).
• Пришел Resync. Это про стакан, а не про заявки: выбросьте хранимый стакан и дождитесь следующего снимка (Круг событий).

Несколько счетов и брокеров

В одной программе можно держать любые сочетания: несколько брокеров, несколько счетов у одного брокера. Для этого есть три простых правила.

UD на счет. MD на брокера. Один счетчик лимитов на область, в которой брокер считает лимит.

• UD (заявки, портфель) - по одному на каждый счет. Один UD не умеет работать с двумя счетами.
• MD (рынок) - один на брокера. Рыночные данные от счета не зависят, второй MD ничего не добавит.
• Счетчик лимитов (BrokerLimiter) - один на ту область, где брокер считает лимит, и его получают все коннекторы, которые эту квоту тратят. Если дать им разные счетчики, вместе они превысят квоту и брокер начнет отказывать. Как устроен счетчик: Лимиты запросов. Если дать один счетчик там, где лимиты независимы, они будут мешать друг другу без нужды.

Библиотека не делает: общий портфель по всем счетам и выбор, с какого счета ставить заявку. Это слой над коннекторами, его пишет бот.

Таблица по брокерам

Почему так записано для Т-Банка: документация брокера говорит, что лимитная политика распространяется на все счета пользователя, а общее число запросов по всем счетам и токенам в секунду не должно превышать 50.

Где записана область, там и менять: в файле crates/<брокер>/limits.toml.

Метки source

У каждого UD своя метка, по ней в общем канале видно, с какого счета событие. Назовите метки так, чтобы по ним можно было понять счет: tbank-ud-main, tbank-ud-iis. Библиотека метку не разбирает, она нужна только вам.

Один брокер, несколько счетов

flowchart TB
  Bot[Бот] --> MD & U1 & U2
  subgraph L[Один счетчик лимитов на пользователя]
    MD[MD Т-Банка]
    U1[UD: брокерский счет]
    U2[UD: ИИС]
  end
  MD --> Q[(Канал событий)]
  U1 -- source=tbank-ud-main --> Q
  U2 -- source=tbank-ud-iis --> Q
  Q --> Bot

Пример на два счета Т-Банка. Один токен, два account_id, один счетчик, один MD, один канал:

use std::time::Duration;

use brokapi::core::{Envelope, Event, OrderExecutor};
use brokapi::runtime::BrokerLimiter;
use brokapi::tbank::limits::default_limits;
use brokapi::tbank::{MarketDataConfig, MarketDataConnector, UserDataConfig, UserDataConnector};
use brokapi::tbank::protocol::TbankConfig;
use tokio::sync::mpsc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cfg = TbankConfig::from_env()?; // один токен

    // Т-Банк считает лимит на пользователя: счетчик один на всех
    let limiter = BrokerLimiter::new(&default_limits());
    let (tx, mut events) = mpsc::channel::<Envelope>(4096);

    let md = MarketDataConnector::start(
        MarketDataConfig::new(cfg.clone(), "tbank-md"),
        limiter.clone(),
        tx.clone(),
    )
    .await?;

    // По одному UD на счет, у каждого своя метка
    let main_account = UserDataConnector::start(
        UserDataConfig::new(cfg.clone().with_account("ID_БРОКЕРСКОГО_СЧЕТА"), "tbank-ud-main"),
        limiter.clone(),
        tx.clone(),
    )
    .await?;
    let iis_account = UserDataConnector::start(
        UserDataConfig::new(cfg.with_account("ID_ИИС"), "tbank-ud-iis"),
        limiter,
        tx,
    )
    .await?;

    // Каждому счету своя сверка и свой журнал cid
    main_account.reconcile(&[]).await?;
    iis_account.reconcile(&[]).await?;
    main_account.subscribe_order_state().await?;
    iis_account.subscribe_order_state().await?;

    // Разбор общего канала: кто прислал, определяет source
    let _ = tokio::time::timeout(Duration::from_secs(30), async {
        while let Some(env) = events.recv().await {
            match (&*env.source, env.payload) {
                ("tbank-ud-main", Event::Order(o)) => println!("основной счет: {} {:?}", o.cid, o.state),
                ("tbank-ud-iis", Event::Order(o)) => println!("ИИС: {} {:?}", o.cid, o.state),
                ("tbank-md", Event::OrderBook(_)) => {} // рыночные данные - общие для обоих счетов
                _ => {}
            }
        }
    })
    .await;

    let stop = brokapi::core::ShutdownMode::Graceful { deadline: Duration::from_secs(5) };
    main_account.shutdown(stop).await;
    iis_account.shutdown(stop).await;
    md.shutdown(stop).await;
    Ok(())
}

Что видно в этом примере. Каждый UD видит только заявки своего счета: проверено на имитации, UD одного счета не может прочитать или снять заявку другого. Сверка идет отдельно по каждому счету со своим списком cid. Заявка одного счета в confirmed другого не окажется.

Финам

Один секрет и один JWT на несколько счетов: создайте менеджер токенов один раз и отдайте всем коннекторам.

let tokens = api.shared_tokens().await?;      // один вызов авторизации
let api = api.with_tokens(tokens);
let a = UserDataConnector::start(UserDataConfig::new(api.clone(), "СЧЕТ_A", "finam-ud-a"), limiter.clone(), tx.clone()).await?;
let b = UserDataConnector::start(UserDataConfig::new(api.clone(), "СЧЕТ_B", "finam-ud-b"), limiter.clone(), tx.clone()).await?;
let md = MarketDataConnector::start(MarketDataConfig::new(api, "finam-md"), limiter, tx).await?;

При запуске UD проверяет, что счет принадлежит секрету (список счетов берется из данных токена). Если счета нет в списке, start возвращает Config.

БКС

Счет определяет токен, поэтому два счета - два refresh-токена и два счетчика лимитов. MD держим с одним из токенов, и он делит счетчик с UD этого же токена.

let cfg_a = BcsConfig::new(token_a).with_write(true);
let cfg_b = BcsConfig::new(token_b).with_write(true);
let limiter_a = BrokerLimiter::new(&limits);
let limiter_b = BrokerLimiter::new(&limits);
let md   = MarketDataConnector::start(MarketDataConfig::new(cfg_a.clone(), "bcs-md"), limiter_a.clone(), tx.clone()).await?;
let ud_a = UserDataConnector::start(UserDataConfig::new(cfg_a, "bcs-ud-a"), limiter_a, tx.clone()).await?;
let ud_b = UserDataConnector::start(UserDataConfig::new(cfg_b, "bcs-ud-b"), limiter_b, tx).await?;

Два токена БКС с двумя независимыми счетчиками: у каждого свои заявки, стопы, события и сверка.

Несколько брокеров

Коннекторы разных брокеров ничего не знают друг о друге: у каждого свое соединение и свой счетчик. Канал событий можно дать общий (тогда брокеров различают по source), можно каждому свой.

flowchart TB
  Bot[Бот]
  Bot --> B[БКС<br>MD и UD]
  Bot --> T[Т-Банк<br>MD и UD]
  Bot --> F[Финам<br>MD и UD]
  B & T & F --> Q[(Общий канал,<br>различаем по source)]
  Q --> Bot

Для общего кода полезно, что все UD имеют один набор трейтов (OrderExecutor, PortfolioSource…). Функцию можно написать один раз и вызывать для любого брокера, как это сделано в Быстром старте.

Различия, которые общий код должен учитывать сам:

• Единицы количества. Во всех Qty это штуки (единицы инструмента), Т-Банк переводит лоты сам. Размер лота в TradingParams::lot_size.
• Замена заявки есть не у всех (caps().supports_replace).
• Идентификатор инструмента у каждого брокера свой вид (NativeId): Брокеры.

Стоп-заявки

Стоп-заявка лежит у брокера и ждет цены. Пока цена не дошла до заданной, на бирже ее нет. Когда дошла, брокер выставляет обычную заявку, рыночную или лимитную.

Для стоп-заявок есть отдельный трейт StopOrderExecutor. Обычных заявок он не касается, а reconcile и active_orders стоп-заявок не показывают. Он реализован у всех брокеров (caps().supports_stop_orders).

Виды

Параметры (PlaceStopOrderRequest): cid, инструмент, сторона, вид, количество, stop_price (цена срабатывания), limit_price (цена заявки после срабатывания: нет цены - рыночная), срок (StopExpiry: до отмены, до конца дня, до даты). Номер cid - тот же UUID, что у обычных заявок, и правила те же: свой на каждую заявку, повторно не отправляется, заранее записывается в журнал.

Методы

Шлюз команд (NotReconciled, Degraded, ShuttingDown) действует на place_stop и cancel_stop так же, как на place и cancel. Неясный ответ - Unknown, повтора нет. Подробности исходов: Круг команд.

Проверки без сети (нет цены у стоп-лимита, срок, которого нет у брокера, некратное лоту количество) библиотека делает сама до отправки, квота на них не тратится. Узнать о срабатывании стопа можно только опросом: нового события о нем нет. Когда стоп сработал, брокер ставит обычную заявку, и ее ведет обычный поток заявок. Связь между стопом и порожденной заявкой библиотека не строит.

Пример

use brokapi::core::{
    ClientOrderId, Error, InstrumentId, PlaceStopOrderRequest, Price, Qty, Side, StopExpiry,
    StopOrderExecutor, StopOrderKind, StopOrderRef,
};

/// Ставит стоп-лосс на продажу, смотрит список ждущих и снимает стоп по номеру брокера.
async fn protect<U: StopOrderExecutor>(
    ud: &U,
    instrument: InstrumentId,
    qty: Qty,
    stop_price: Price,
) -> Result<(), Error> {
    let cid = ClientOrderId::new_v4();
    let ack = ud
        .place_stop(PlaceStopOrderRequest {
            cid,
            instrument,
            side: Side::Sell,
            kind: StopOrderKind::StopLoss,
            qty,
            stop_price,
            limit_price: None, // рыночная заявка после срабатывания
            expiry: StopExpiry::GoodTillCancel,
        })
        .await?;
    // Номер брокера нужно сохранить: после рестарта у Т-Банка отмена по cid невозможна
    let broker_id = ack.broker_id;

    for stop in ud.active_stop_orders().await? {
        println!("стоп {:?} {:?} по {}, cid {:?}", stop.kind, stop.state, stop.stop_price, stop.cid);
    }

    ud.cancel_stop(StopOrderRef::Broker(broker_id)).await
}

Потерянный ответ

Unknown у place_stop значит, что стоп мог дойти до брокера. Тот же cid повторить нельзя, новый стоп наугад ставить тоже: выйдет два. Прочитайте active_stop_orders():

• Есть стоп с вашим cid. Он ваш. БКС, Финам, АЛОР и Bybit возвращают cid сами. Т-Банк нет: его коннектор связывает стоп с cid, если в списке ровно один стоп без cid, который подходит под запрос (бумага, сторона, вид, количество, цены) и создан, пока запрос был в пути.
• Есть стопы без cid на той же бумаге и в ту же сторону, ваш среди них неясен. Второй стоп не ставьте. У Т-Банка так бывает, когда рядом стоит такой же стоп другой программы или два одинаковых ответа потерялись: коннектор не гадает и cid не назначает.
• Ничего нет. Стопа у брокера нет. Подождите несколько секунд, посмотрите еще раз (медленный брокер принимает стоп с опозданием), потом ставьте заново с новым cid.

Рабочий код этих трех шагов на Python: Стоп-заявки, Python.

Что отличается у брокеров

Особенности:

• БКС: срок жизни. Документация срок условной заявки не называет. Поэтому БКС принимает только «до отмены» и никакого поля срока не шлет. Срок жизни условной заявки в документации БКС не назван. Направление срабатывания БКС выбирает сам из стороны и вида. Пару «стоп-лосс плюс тейк-профит» одной заявкой библиотека не создает. Чужую пару в списке показывает двумя заявками с одним номером.
• Т-Банк: отмена после рестарта. cancel_stop(StopOrderRef::Cid(cid)) для стопа, поставленного раньше этого запуска, вернет Rejected с кодом unknown_stop_order. Снимайте по StopOrderRef::Broker(номер): номер берите из журнала бота или из active_stop_orders().
• Bybit: списки. Ожидающие стоп-заявки не попадают в active_orders и reconcile как рабочие заявки, для них active_stop_orders (после срабатывания стоп становится обычной заявкой). Позицию стоп сам не закрывает: reduceOnly и closeOnTrigger коннектор не ставит, поэтому размер стопа равен позиции. Подробно: Bybit.
• Финам: списки. Стоп-заявки не попадают в active_orders и reconcile. Для них свой список.
• Финам: процент вместо штук. Если у чужой SL/TP-заявки единица объема - процент от позиции, в qty будет 0 («не в штуках»), а не процент. Свои заявки библиотека ставит в штуках.
• Т-Банк: длинный список. Когда стоп-заявок слишком много для одного ответа (ошибка 30261), active_stop_orders читает список по периодам и склеивает. Если и так не вышло, Rejected с кодом stop_orders_response_limit. Подробно: Т-Банк.
• Т-Банк: лимит по инструменту. Ответ 80007 (максимум стоп-заявок по инструменту) - это Rejected с кодом stop_orders_limit, а не RateLimited: повтор не поможет, снимите одну из заявок.
• Сверка и стопы. cid стоп-заявок в список для reconcile не кладите: обычной сверкой они не видны. После старта читайте active_stop_orders().

Стоп-заявки проверяйте на минимальном объеме с ценой далеко от рынка.

Любой метод брокера: raw

Общий интерфейс закрывает то, что умеют все брокеры. Но у каждого брокера есть много своего: купоны и дивиденды, отчеты, избранное, корпоративные действия, свежие методы. Чтобы они не оказались закрыты, у каждого коннектора (MD и UD, у всех брокеров) есть метод raw(). Он позволяет вызвать любой метод API брокера с теми же токеном, адресом и счетчиком лимитов, что у самого коннектора.

Сколько методов брокера есть и какие из них доступны только так: Покрытие API. Это не недоделка, а способ дать все остальное, не раздувая общий интерфейс.

Два вызова

• call(имя, замыкание) - для чтения. Сетевой сбой и таймаут - ошибка, которую можно повторить. У Финама при просроченном токене запрос один раз повторяется после обновления JWT. У БКС и АЛОРа клиент сам повторяет запрос один раз после ответа 401 (команды заявок этого не делают).
• call_command(имя, замыкание) - для всего, что меняет счет. Если ответа нет (таймаут, обрыв, ошибка сервера), результат Unknown: брокер мог выполнить команду. Библиотека такой вызов никогда не повторяет.

Если сомневаетесь, меняет ли метод счет, берите call_command.

Что происходит при вызове

1. Берется квота. Имя метода ("GetUserTariff") ищется в файле лимитов (limits.toml крейта брокера). Нет такого имени - тратится общее ведро брокера (маршрут "*"). Бесплатно не уходит ни один вызов. Квоты нет - вызов не отправляется, возвращается RateLimited.
2. Идет вызов с токеном коннектора. Время ожидания то же, что у самого коннектора.
3. Ошибка брокера переводится в те же ошибки библиотеки, что и везде (Круг команд).

Правила:

• Один вызов raw() - один метод API. Не вызывайте несколько методов в одном замыкании: квота берется за один.
• Имя метода - это имя метода из описания API (для Т-Банка и Финама имя метода .proto, для БКС имя операции из файла лимитов). Хотите точный учет - добавьте маршрут для метода в файл лимитов.
• Потоки. Если метод возвращает поток (server-streaming), квота покрывает только открытие. Дальше поток ваш: читайте его сами. Поток Финама хранит JWT, с которым он открыт, и после смены токена его надо открыть заново (коннектор делает это для своих потоков, для ваших - вы).
• WebSocket БКС. connect_ws(канал, отправитель) открывает один из каналов (лимиты, маржинальные показатели) с тем же токеном. Квота называется Connect<Канал>. Сессия сама переподключается и подписывается заново.

Чего raw() не делает

raw() не знает про заявки коннектора. Заявка, поставленная через raw(), не попадает ни в события, ни в reconcile, и коннектор не следит за ее состоянием. Заявки ставьте обычными методами. Через raw() вызывайте то, чего в общем интерфейсе нет.

Примеры

Т-Банк: тариф и последние цены нескольких инструментов сразу (нужен крейт brokapi-tbank-protocol).

use brokapi::tbank::MarketDataConnector;
use brokapi::tbank::protocol::v1 as pb;

async fn tbank_raw(md: &MarketDataConnector) -> Result<(), brokapi::core::Error> {
    let raw = md.raw();

    // Квота берется по имени метода, вызов идет с токеном коннектора
    let tariff = raw
        .call("GetUserTariff", |c| async move { c.users().get_user_tariff(pb::GetUserTariffRequest {}).await })
        .await?;
    println!("лимитов в тарифе: {}", tariff.unary_limits.len());

    let prices = raw
        .call("GetLastPrices", |c| async move {
            c.market_data()
                .get_last_prices(pb::GetLastPricesRequest {
                    instrument_id: vec!["SBER_TQBR".into(), "GAZP_TQBR".into()],
                    ..Default::default()
                })
                .await
        })
        .await?;
    for p in prices.last_prices {
        println!("{} {:?}", p.ticker, p.price);
    }
    Ok(())
}

БКС: котировки и история операций (нужен крейт brokapi-bcs-protocol).

use brokapi::bcs::protocol::http::models::{OperationHistoryRequest, QuoteInstrument, QuotesRequest};
use brokapi::bcs::MarketDataConnector;

async fn bcs_raw(md: &MarketDataConnector) -> Result<(), brokapi::core::Error> {
    let raw = md.raw();

    let quotes = raw
        .call("GetQuotes", |http| async move {
            http.get_quotes(&QuotesRequest { instruments: vec![QuoteInstrument::new("SBER", "TQBR")] }).await
        })
        .await?;
    for q in quotes.records {
        println!("{:?} покупка {:?} продажа {:?} последняя {:?}", q.ticker, q.bid, q.offer, q.last);
    }

    // Операции без сделок (пополнения, дивиденды, комиссии): в общем интерфейсе их нет
    let history = raw
        .call("GetOperationHistory", |http| async move {
            http.search_operations(&OperationHistoryRequest::default(), Some(10), None).await
        })
        .await?;
    println!("операций: {}", history.records.len());
    Ok(())
}

Финам: последняя котировка и время биржи (нужен крейт brokapi-finam-protocol). Замыкание у Финама может вызываться дважды (после обновления токена), поэтому оно типа Fn, а не FnOnce.

use brokapi::finam::MarketDataConnector;
use brokapi::finam::protocol::pb::grpc::tradeapi::v1::assets as ps;
use brokapi::finam::protocol::pb::grpc::tradeapi::v1::marketdata as pm;

async fn finam_raw(md: &MarketDataConnector) -> Result<(), brokapi::core::Error> {
    let raw = md.raw();

    let quote = raw
        .call("LastQuote", |api| async move {
            api.market_data().last_quote(pm::QuoteRequest { symbol: "SBER@MISX".into() }).await
        })
        .await?;
    println!("{} {:?}", quote.symbol, quote.quote);

    let clock = raw.call("Clock", |api| async move { api.assets().clock(ps::ClockRequest {}).await }).await?;
    println!("время биржи: {:?}", clock.timestamp);
    Ok(())
}

АЛОР: котировки нескольких бумаг сразу и сводка портфеля (оба метода в общем интерфейсе не нужны).

use brokapi::alor::MarketDataConnector;

async fn alor_raw(md: &MarketDataConnector, portfolio: &str) -> Result<(), brokapi::core::Error> {
    let raw = md.raw();

    let quotes = raw
        .call("GetQuotes", |http| async move { http.get_quotes(&[("MOEX", "SBER"), ("MOEX", "GAZP")]).await })
        .await?;
    for q in quotes {
        println!("{} покупка {:?} продажа {:?} последняя {:?}", q.symbol, q.bid, q.ask, q.last_price);
    }

    let portfolio = portfolio.to_string();
    let summary = raw
        .call("GetSummary", |http| async move { http.get_summary("MOEX", &portfolio).await })
        .await?;
    println!("оценка портфеля: {:?}", summary.portfolio_evaluation);
    Ok(())
}

Остальные методы описания API (группы заявок, оценка заявки, риски, остальные подписки WebSocket, канал /cws) устроены так же: метод клиента AlorHttpClient в замыкании, имя для квоты первым аргументом.

Все примеры только читают. Все, что меняет счет (отчет, SL/TP-заявка Финама, группа заявок АЛОРа и подобное), идет через call_command. Готовые полные примеры лежат в examples/*_raw_access.rs соответствующих крейтов.

Как проверено

На имитации у всех брокеров: вызов проходит авторизацию, тратит квоту по имени метода, отказ по квоте не доходит до брокера, счетчик общий с соседним коннектором, метод без маршрута идет по маршруту по умолчанию. У Финама еще проверено обновление токена при чтении и отсутствие повтора у команды. У Т-Банка и БКС неясный ответ команды дает Unknown. У БКС проверено открытие WebSocket-канала через raw().

Как тестировать код против имитаций брокеров (Rust)

Инструкция. Крейт brokapi-mocks запускает в вашем процессе имитации БКС, Т-Банка, Финама, АЛОРа и Bybit. Они говорят на настоящем протоколе брокера (HTTP и WebSocket у БКС, АЛОРа и Bybit, gRPC у Т-Банка и Финама), поэтому коннектор работает с ними так же, как с брокером: без сети, без токенов, без денег. Все примеры книги и все программы в examples/ запускаются против них.

Имитация проверяет, что ваш код правильно разбирает то, что брокер описал в документации. Она не доказывает, что настоящий брокер отвечает так же.

brokapi-mocks не входит в обещания библиотеки (publish = false): его интерфейс может меняться в любой версии. Он нужен тестам и примерам.

Подключение

# edition = "2024" в [package], Rust 1.88 или новее
[dev-dependencies]
brokapi       = { path = "../brokapi", features = ["bcs", "tbank", "finam", "alor"] }
brokapi-mocks = { path = "../brokapi/crates/mocks" }
tokio         = { version = "1", features = ["full", "test-util"] }

Путь указывает на клон репозитория. Тесты - обычные #[tokio::test] (среда в одном потоке). Как обращаться со временем в таких тестах, написано в разделе Время в тестах.

Запуск каждой имитации

Имитация живет, пока жива переменная MockServer, и слушает случайный порт на 127.0.0.1. Адрес и токен подставляются в настройку коннектора специальным конструктором for_mock.

use std::sync::Arc;
use brokapi::bcs::protocol::config::BcsConfig;
use brokapi::bcs::{MarketDataConfig, MarketDataConnector, UserDataConfig, UserDataConnector};
use brokapi::bcs::limits::default_limits;
use brokapi::runtime::BrokerLimiter;
use tokio::sync::mpsc;

let server = brokapi_mocks::bcs::MockServer::start(Default::default()).await;
let cfg = BcsConfig::for_mock("mock-refresh-token", &server.http_base).with_write(true);
let limiter = BrokerLimiter::new(&default_limits());
let (tx, mut events) = mpsc::channel(1024);
let ud = UserDataConnector::start(UserDataConfig::new(cfg, "bcs-ud"), limiter, tx).await?;
ud.reconcile(&[]).await?;   // обязательно, как и с настоящим брокером

Чтобы читать счетчики и менять рычаги работающей имитации (event_sockets(), synthetic_candles и другие), создайте настройки сами и передайте Arc в start. Тип надо назвать: Arc::new(Default::default()) компилятор не выведет.

use std::sync::Arc;
use brokapi_mocks::bcs::{MockOptions, MockServer};

let opts: Arc<MockOptions> = Arc::default();
let server = MockServer::start(opts.clone()).await;
// ... рычаги и счетчики лежат в `opts`, например `opts.event_sockets()` - сколько сокетов событий открыто.

BrokerLimiter::new возвращает Arc<BrokerLimiter>: передавайте его дальше через .clone().

Готовые рабочие программы с запуском имитаций: examples/trading_bot.rs (БКС и Т-Банк), examples/infrastructure.rs и examples/research.rs (все три). Тесты на них: tests/examples.rs.

Время в тестах

Тесты без настоящих пауз: ни sleep, ни ожидания «на всякий случай». Часы коннекторов - часы tokio: все они берут текущее время из brokapi::runtime::now(), поэтому лимит запросов, таймаут команды и пауза переподключения идут по тем же часам, что и тест.

Нельзя только одного: останавливать часы на весь тест (#[tokio::test(start_paused = true)]), когда имитация слушает настоящий порт. Пока запрос идет по сокету, у среды нет задач, и остановленные часы сами перескакивают к ближайшему таймеру. Таймаут запроса срабатывает раньше, чем прочитан ответ. Поэтому у тестов с имитациями часы настоящие, а вместо пауз - два помощника в brokapi_mocks::time:

Про «ничего не произошло» (чужой счет не получил событие, повтора не было) вместо «подождали и не увидели» проверяют так: после действия делают что-то, что приходит заведомо позже (событие по своему счету, круг запроса к брокеру), и смотрят, что между ними лишнего нет.

В готовых тестах книги так и сделано: crates/*/tests/.

Константы и пути

Какие данные отдают имитации

• Стакан. БКС (чтение по REST и поток): лучшая цена покупки 244.30, продажи 244.35. Подписка на стакан БКС дает один снимок и дальше тихо: бот, которому нужен повтор по таймеру, не дождется второго снимка. Т-Банк: покупка около 273.90, продажа около 274.00, при подписке приходит несколько снимков. Финам (чтение по REST): покупка 100.0, продажа 100.1, поток снимков с периодом tick_ms. Имитации принимают любую цену, кроме отклоняемой.
• Свечи и бары. По умолчанию фиксированный короткий ответ. Включите synthetic_candles (опция имитации), и имитация отдаст ряд под заданный период по одному бару на шаг таймфрейма и отклонит период длиннее предела брокера (БКС: больше 1440 баров, Т-Банк: INVALID_ARGUMENT 30014 по таблице пределов). Так проверяется выгрузка окнами.
• АЛОР. Стакан: покупка 244.30, продажа 244.31, подписка на стакан дает один снимок. Бумаги SBER, GAZP (режим TQBR, лот 10, шаг 0.01) и фьючерс SiZ6, тикер NOPE неизвестен. Портфель: рубли и 30 штук SBER. Свечи всегда рядом по сетке таймфрейма на весь запрошенный период. Повтор X-REQID получает копию первого ответа, как сказано в документации брокера.
• Заявки. Имитации помнят заявки: их можно поставить, прочитать, снять, заменить (где брокер умеет). Данные счета отдельные.

Имитация Bybit

Таблицы выше про четырех российских брокеров. Имитация Bybit устроена так же, отличия коротко.

use brokapi::bybit::protocol::config::BybitConfig;

let server = brokapi_mocks::bybit::MockServer::start(Default::default()).await;
let cfg = BybitConfig::for_mock("mock-key", "mock-secret", &server.http_base);
// MarketDataConfig::new(cfg.clone(), "bybit-md"), UserDataConfig::new(cfg, "bybit-ud"): дальше как у остальных.

• Подпись настоящая. Имитация проверяет подпись каждого приватного запроса и окно времени (recv_window), как биржа: клиент, который подписывает неверно, получает отказ. Ключ brokapi_mocks::bybit::DEFAULT_KEY ("mock-key"), секрет SECRET ("mock-secret"). Другой ключ - отдельный счет со своими заявками.
• Инструменты. MOCKUSDT (бессрочный, шаг количества и самое малое количество 10, шаг цены 0.01, LOT = 10), BTCUSDT (числа настоящего контракта: шаг 0.001, цена 0.10) и срочный фьючерс BTC-26DEC26. Тикер NOPEUSDT (UNKNOWN_SYMBOL) неизвестен: чтение дает код 10001.
• Заявки и рычаги. server.fill(&cid.hyphenated().to_string(), qty, price) исполняет заявку (статус, исполнение, события). server.cut_event_sockets() обрывает приватные сокеты (бот получает Event::Reconnected), server.push_event(текст) пишет сырое сообщение в приватные сокеты. Лимитная заявка по цене brokapi_conformance::REJECT_PRICE (13.37) отвергается кодом 110003.
• Настройки (MockOptions): rate_limit_order_book (чтение стакана отвечает HTTP 429), order_delay_ms (команда ждет столько по часам теста, для Unknown по таймауту), stop_answer_lost (стоп принят, ответ потерян: HTTP 503), clock_offset_ms (часы биржи уходят вперед), refuse_ws_login, fail_subscribe_text, stream_gate (биржа медленно открывает потоки), disconnect_after_data_frames.
• Свечи. Ряд под запрошенный период, по одной свече на шаг интервала (synthetic_candles не нужен).

Рычаги, которыми вызывают нужный исход

opts - это Arc<MockOptions>, который передается в start. Для Финама рычаги лежат в server.state.options. Все поля - атомарные числа и флаги, их можно менять, пока имитация работает.

Ловушки тестов

• subscribe_* возвращается, когда поток открыт. Ждать подключения сокета (event_sockets()) после subscribe_order_state и subscribe_executions не нужно: заявка, поставленная сразу после возврата, не пропадет. Событие, случившееся до подписки, теряется, его читают через order_state или active_orders. Подписка раньше заявки - правило и для имитации.
• Имитация сервера должна жить столько же, сколько коннекторы. Положите ее в переменную, которая не уходит из области раньше.
• Рестарт процесса проверяется двумя жизнями коннекторов при одной имитации: имитация помнит заявки между ними (инфраструктура).
• Таймауты ожидания в тестах задавайте с запасом на медленный CI, но не бесконечные: зависший тест хуже упавшего. Они срабатывают только когда тест упал, поэтому на скорость прогона не влияют.
• Имитации не знают реальных лимитов брокеров и реальной скорости. Лимиты запросов проверяйте своим малым бюджетом.

Чего имитации не покажут

Реальные форматы чисел и времени, реальные лимиты и ошибки, поведение брокера на повтор cid, единицы количества у БКС. Проверяйте эти места на минимальной заявке.

brokapi для Python

Тонкая обертка над ядром brokapi на Rust. Стадия: открытая альфа, интерфейс до беты может меняться. Перед боевым счетом: Перед боевым счетом.

Обертка не придумывает своих правил. Это те же БКС, Т-Банк, Финам, АЛОР и Bybit, те же сверка, cid, лимиты и ошибки, что у ядра, только вызываются они из Python. События приходят через async for, деньги, цены и количества - decimal.Decimal, никогда float. Устройство, правила и особенности брокеров общие для всех путей и лежат в общих частях книги. Здесь то, что зависит от языка: как подключить пакет и как решить задачу кодом.

Что нужно

• Python 3.10 или новее. Пакет один на все версии (abi3).
• pip install brokapi. Готовые пакеты есть для Linux (x86_64 и aarch64), macOS (Intel и Apple silicon) и Windows, на остальных системах расширение соберется при установке (нужен Rust 1.88 или новее). Подробности и частые ошибки: Установка. Пакет дает библиотеку. Программа brokapi (Gateway) ставится отдельно: Установка.

python -m venv .venv && . .venv/bin/activate
pip install "git+https://github.com/runinfra/brokapi#subdirectory=crates/python"   # из клона: pip install ./crates/python
python -c "import brokapi; print(brokapi.__version__)"

Должен напечататься номер версии.

Инструкции по задачам

Что умеет первая версия

Python повторяет Rust по возможностям. Отличие одно: raw не отдает потоки (метод, который открывает поток, и WebSocket-каналы БКС), их читает общий интерфейс. Подробности: Любой метод брокера, Python.

Правила, которые остаются

Обертка сохраняет обязательные правила ядра (Контракт для агентов):

• торговля открывается только после reconcile, до него place поднимает NotReconciled
• cid придумывает бот (brokapi.new_cid()) и записывает в свой журнал до вызова place
• Unknown никогда не повторяется: после него order_state(cid)
• один счетчик лимитов на область брокера: limiter= у connect
• деньги, цены и количества - Decimal, float в вызове отвергается с TypeError

Что бывает, если нарушить каждое правило, объяснено в общих частях: Круг команд, Круг жизни, Лимиты, Деньги, цены и количества.

Общее, что нужно прочитать

• Контракт для агентов: обязательные правила на одной странице, нужны и человеку.
• Карта и три круга: события, команды, жизнь коннектора.
• Ошибки и что с ними делать, события и возможности, Брокеры.
• Для ИИ-агентов, которые пишут на Python: llms.txt для Python (на сайте /docs/python/llms.txt).

Каждый пример в этом разделе - тест против имитаций брокеров, он запускается при каждой проверке репозитория.

Быстрый старт на Python

Цель страницы: за один заход дойти от пустого окружения до первой заявки и не рисковать деньгами по дороге. Ступеней три: сначала имитация брокера в вашем процессе (без токена и без денег), потом песочница Т-Банка, и только потом боевой счет.

Боевой токен выдает человек, и первую боевую заявку ставят только с его слова. ИИ-агент токен с правом торговли сам не создает и флаги записи (BCS_IS_WRITE и подобные) сам не включает: правило 0. На настоящем счете БКС, Т-Банка, Финама и АЛОРа библиотеку пока не запускали (Bybit проверен вживую), подробности: Перед боевым счетом.

Шаг 1. Получить библиотеку

Нужен Python 3.10 или новее. Пакет brokapi ставится в виртуальное окружение:

python -m venv .venv && . .venv/bin/activate
pip install brokapi

Самая свежая версия из репозитория - вместо второй строки (нужен Rust 1.88 или новее, расширение собирается при установке, это несколько минут. Подробности и частые ошибки - на странице Установка):

pip install "git+https://github.com/runinfra/brokapi#subdirectory=crates/python"

Проверка:

python -c "import brokapi; print(brokapi.__version__)"

Должна напечататься версия 0.1.0a5. Не напечатала: таблица «Если что-то пошло не так» на странице Установка.

Шаг 2. Первая программа: без токена и без денег

Обычный скрипт. Имитация (brokapi.testing.mock_tbank) - это настоящий сервер на 127.0.0.1, который говорит на протоколе Т-Банка, а клиент к нему тот же brokapi.Client, что вернул бы brokapi.connect("tbank", ...). Токен, счет и сеть не нужны.

Программа начинается с импортов:

import asyncio
import sys
from decimal import Decimal

import brokapi
from brokapi.testing import mock_tbank

Сама работа - функция first_order. Она берет клиента любого брокера, поэтому дальше, на песочнице и на боевом счете, она не меняется:

async def first_order(client: brokapi.Client) -> None:
    """Reads the market, puts one order far below it and takes it off at once."""
    # 1. What to trade and by what rules: the step of the price and the lot.
    sber = await client.instrument("SBER")
    params = await client.trading_params(sber)

    # 2. The quote: the best bid and the best ask are the top of the order book.
    book = await client.order_book(sber, depth=1)
    best_bid = book.bids[0].price
    print(f"SBER: bid {best_bid}, ask {book.asks[0].price}, lot {params.lot_size}, price step {params.price_step}")

    # 3. Subscribe to the states of your orders, and only then reconcile: no event is lost between the two.
    await client.subscribe_order_state()
    report = await client.reconcile([])  # a new bot has an empty ledger. Until now `place` is NotReconciled
    print(f"reconcile: {len(report.foreign)} foreign order(s) on the account")

    # 4. An order far from the market: 90% of the best bid, rounded down to the price step, one lot.
    price = brokapi.round_to_step(best_bid * Decimal("0.9"), params.price_step, brokapi.RoundMode.DOWN)
    cid = brokapi.new_cid()  # a real bot writes the cid to its journal here, before `place`
    ack = await client.place(cid=cid, instrument=sber, side=brokapi.Side.BUY, qty=params.lot_size, price=price)
    print(f"placed: broker order id {ack.broker_id}, price {price}")

    # 5. Take it off and ask the broker what became of it. The answer of `order_state` is the proof.
    await client.cancel(cid)
    state = await client.order_state(cid)
    print(f"after cancel: {state.state.kind.value}, orders alive: {len(await client.active_orders())}")

Запуск на имитации: блок async with поднимает сервер и останавливает его в конце, mock.connect() возвращает клиента.

async def on_the_imitation() -> None:
    # The block starts the imitation and stops it at the end. `mock.connect()` is `brokapi.connect(...)` to it.
    async with await mock_tbank() as mock:
        client = await mock.connect()
        await first_order(client)

        # The price of the imitation stands still: it has no market behind it.
        book = await client.order_book(await client.instrument("SBER"), depth=1)
        print(f"the price stands still: bid {book.bids[0].price}")

Готовая программа целиком - в разделе «Вся программа» ниже (к этим кускам добавлены импорты и запуск через asyncio.run). Сохраните ее как quickstart_tbank.py и запустите python quickstart_tbank.py. Должно напечататься:

SBER: bid 273.9, ask 274, lot 10, price step 0.01
reconcile: 0 foreign order(s) on the account
placed: broker order id EX1, price 246.51
after cancel: Cancelled, orders alive: 0
the price stands still: bid 273.9

Что здесь произошло:

1. Котировка - верх стакана. Отдельного метода «котировка» у клиента нет: order_book(sber, depth=1) дает лучшую цену покупки и продажи.
2. Подписка на статусы своих заявок идет до reconcile, иначе событие между снимком сверки и подпиской пропало бы. reconcile([]) открыл шлюз торговых команд: до него place вернул бы NotReconciled. Список пустой, потому что бот новый.
3. Цена заявки - 90% от лучшей покупки, округленная вниз до шага точной арифметикой (round_to_step). Количество - один лот, в штуках (лот SBER в имитации 10).
4. cid бот придумывает сам. В настоящем боте в этот момент строка уходит в журнал на диск: «отправляю».
5. place вернул OrderAck: «брокер принял». Что стало с заявкой, говорит order_state, и после cancel это Cancelled.

Цена в имитации стоит на месте. За стаканом нет рынка: сколько раз ни спроси, будет 273.9 и 274, а заявка сама не исполнится. Исполнить ее просят у имитации: mock.fill(cid) (Тесты против имитаций). Поэтому на имитации проверяют порядок вызовов и разбор исходов, а стратегию по движению цены на ней проверить нельзя. Имитация написана по документации брокера и не доказывает, что настоящий брокер ответит так же.

Такие же имитации есть у БКС, Финама и АЛОРа (mock_bcs(), mock_finam(), mock_alor()), first_order работает на каждой. У Bybit имитация mock_bybit() с контрактом MOCKUSDT и свой первый запуск, с демо-счетом вместо песочницы: Bybit.

Шаг 3. Песочница Т-Банка

Следующая ступень - настоящий сервер брокера, но с игровыми деньгами. Нужны токен песочницы и счет песочницы. Токен выдает человек в кабинете Т-Банка, как это сделать - в разделе «Вход» страницы Т-Банк. Счет песочницы сам не появляется: его открывает метод OpenSandboxAccount и пополняет SandboxPayIn (по документации Т-Банка). Без счета connect ответит Config: у токена нет открытого счета.

export TBANK_TOKEN=...        # токен песочницы
python quickstart_tbank.py sandbox

В коде меняется одна строка: клиента делает connect, а не имитация. sandbox=True выбирает адрес песочницы (без него адрес боевой, и токен песочницы не подойдет), то же делает переменная TBANK_SANDBOX=true. Токен берется из окружения или из файла .env рядом с программой.

async def on_the_sandbox() -> None:
    # TBANK_TOKEN is the token of the sandbox. sandbox=True is the address of the sandbox (the real one is the default).
    client = await brokapi.connect("tbank", sandbox=True)
    try:
        await first_order(client)
    finally:
        await client.close()

Печатается то же самое, но с живыми ценами песочницы. Заявка покупает, поэтому на счете песочницы должны быть деньги: пополните его на сумму больше цены лота. Если счетов у токена несколько, укажите нужный: TBANK_ACCOUNT_ID или account_id= в connect.

Шаг 4. Боевой счет

Сюда идут, когда имитация и песочница прошли, а человек, чей это счет, сам выдал токен и сказал «можно». Первая заявка та же: лимитная, минимальное количество, цена далеко от рынка, сразу отмена.

Где взять токен и номер счета у каждого брокера: раздел «Вход» на страницах БКС, Т-Банк, Финам, АЛОР, Bybit. Первый день на Финаме, где песочницы нет: Финам.

await client.instrument("SBER") у Т-Банка делает один запрос к справочнику и берет uid инструмента, у БКС, Финама, АЛОРа и Bybit идентификатор строится по тексту, второй аргумент задает площадку (TQBR, MISX, у Bybit категорию linear). Особенности брокеров: БКС, Т-Банк, Финам, АЛОР, Bybit.

Пример для БКС

У БКС нет песочницы, счет настоящий. Заявка ставится только по токену на запись, ее цена заведомо ниже рынка, количество минимальное, и она снимается сразу. Токен без записи (BCS_IS_WRITE не true) дойдет только до чтения.

Настройки лежат в переменных окружения. Удобно файлом .env рядом с программой, пакет читает его сам. Токены не печатайте в логи и не кладите в коммиты. Те же настройки можно передать аргументами: brokapi.connect("bcs", refresh_token="...", write=True). Что не передано, берется из окружения.

connect поднимает два коннектора, рыночных данных и счета, и возвращает клиента. Если токен не подошел, это Config или Transport прямо здесь, а не на первом запросе.

# BCS_REFRESH_TOKEN and BCS_IS_WRITE come from the environment (a .env file works)
client = await brokapi.connect("bcs")
print("connected: bcs-md and bcs-ud started")

Должно напечататься connected: bcs-md and bcs-ud started. Не напечатало: Config называет, какой настройки нет, Transport говорит, что БКС не отвечает или отверг токен.

Чтение: три запроса, которые ничего не меняют. Инструмент SBER на основной площадке БКС (TQBR) получает метод instrument, он собирает идентификатор по тикеру.

sber = await client.instrument("SBER")  # the ticker on the board TQBR

# 1. Portfolio: money and positions of the account.
portfolio = await client.portfolio()
print(f"portfolio: {len(portfolio.balances)} balance(s), {len(portfolio.positions)} position(s)")
for balance in portfolio.balances:
    print(f"  money {balance.currency}: {balance.available} free, {balance.blocked} blocked")

# 2. Order book: best bid and best ask.
book = await client.order_book(sber, depth=5)
best_bid = book.bids[0].price if book.bids else None
best_ask = book.asks[0].price if book.asks else None
print(f"order book SBER: best bid {best_bid}, best ask {best_ask}")

# 3. Candles: the last hour of five-minute bars.
now = datetime.now(timezone.utc)
bars = await client.candles(sber, brokapi.Timeframe.M5, now - timedelta(hours=1), now)
print(f"candles M5: {len(bars)} bar(s), last close {bars[-1].close if bars else None}")

Должно напечататься число балансов и позиций, лучшая цена покупки и продажи и число свечей. Цены и суммы здесь Decimal: цена печатается точной десятичной записью, как ее отдал брокер, без хвостов вроде 0.30000000000000004.

Дальше программа пишет в счет. Если токен не на запись, она остановится здесь.

print("WARNING: BCS has no sandbox. The account is real, the order below goes to the exchange.")

Заявка далеко от рынка и отмена. Порядок важен, причины каждого шага разобраны в Круге жизни и Круге команд:

1. Правила инструмента: шаг цены и минимальное количество (trading_params). Метод заодно сообщает шаг цены коннектору, и цена не на шаге будет отвергнута сразу, до отправки.
2. Цена: 90% от лучшей покупки, округленная вниз до шага точной арифметикой (round_to_step).
3. Подписка на статусы своих заявок, и только потом reconcile: событие между снимком сверки и подпиской иначе потерялось бы.
4. cid придумывает бот. В настоящем боте здесь строка в журнал: «отправляю».
5. place, события статусов, cancel и проверка order_state.

# The price: far below the best bid, a multiple of the price step. The quantity: the minimum.
params = await client.trading_params(sber)
reference = best_bid or (bars[-1].close if bars else None)
if reference is None:
    raise SystemExit("no price to start from: the book and the candles are empty")
# The rounding is exact: the price is a whole number of steps, no 0.9999999 noise.
price = brokapi.round_to_step(reference * FAR_FROM_MARKET, params.price_step, brokapi.RoundMode.DOWN)
print(f"order: buy {params.min_qty} at {price} (best bid {reference}, price step {params.price_step})")

# The gate is closed until the first reconcile. The ledger of this new bot is empty. Subscribe first, so no
# event between the snapshot of the reconcile and the subscription is lost.
await client.subscribe_order_state()
report = await client.reconcile([])
print(f"reconcile: {len(report.foreign)} foreign order(s) on the account")

# The cid is made by the bot and belongs in its journal before the order is sent.
cid = brokapi.new_cid()
# Here the bot writes `cid` to its journal as "sending".
print(f"cid {cid}")
ack = await client.place(
    cid=cid,
    instrument=sber,
    side=brokapi.Side.BUY,
    qty=params.min_qty,
    price=price,
)
print(f"accepted: broker order id {ack.broker_id}")
await wait_for_order(client, cid, brokapi.OrderStateKind.ACKED)

# Cancel at once and look at the final state.
await client.cancel(cid)
await wait_for_order(client, cid, brokapi.OrderStateKind.CANCELLED)
last = await client.order_state(cid)
print(f"order_state: {last.state.kind.value}")

Должно напечататься: accepted: broker order id ..., события Acked, затем Cancelled, в конце order_state: Cancelled. Событие это уведомление, а доказательство - ответ order_state, поэтому программа не падает, если события не пришли.

Если place вернул Rejected, у ошибки есть code: price_off_step (цена не на шаге), missing_price (у лимитной заявки нет цены), отказ брокера с его текстом. Если Unknown, заявка могла встать: не повторяйте, спросите order_state(cid) (Если что-то пошло не так, общая логика одна для всех языков).

Остановка:

await client.close()
print("stopped")

Заявки на бирже при остановке не снимаются. Если cancel не прошел, заявка останется. Как остановить бота так, чтобы на счете не осталось лишнего: Аварийная остановка бота.

Вся программа

"""Quick start: the first run without a token and without money, then the sandbox of T-Bank.

This program is the code of the page "Быстрый старт" of the Python section of the book. The book includes the marked
parts below, so the text and the code that is tested cannot drift apart.

Without a token (the imitation of T-Bank in your own process; no account, no network)::

    python quickstart_tbank.py

On the sandbox of T-Bank (a token of the sandbox and an account of the sandbox are needed)::

    TBANK_TOKEN=... python quickstart_tbank.py sandbox

The imitation (`brokapi.testing.mock_tbank`) is a server on 127.0.0.1 that speaks the protocol of T-Bank. The client is
the same `brokapi.Client` that `brokapi.connect("tbank", ...)` returns, so `first_order` below is the code of a real
run: it works with a client of any broker.
"""

import asyncio
import sys
from decimal import Decimal

import brokapi
from brokapi.testing import mock_tbank


# ANCHOR: first_order
async def first_order(client: brokapi.Client) -> None:
    """Reads the market, puts one order far below it and takes it off at once."""
    # 1. What to trade and by what rules: the step of the price and the lot.
    sber = await client.instrument("SBER")
    params = await client.trading_params(sber)

    # 2. The quote: the best bid and the best ask are the top of the order book.
    book = await client.order_book(sber, depth=1)
    best_bid = book.bids[0].price
    print(f"SBER: bid {best_bid}, ask {book.asks[0].price}, lot {params.lot_size}, price step {params.price_step}")

    # 3. Subscribe to the states of your orders, and only then reconcile: no event is lost between the two.
    await client.subscribe_order_state()
    report = await client.reconcile([])  # a new bot has an empty ledger. Until now `place` is NotReconciled
    print(f"reconcile: {len(report.foreign)} foreign order(s) on the account")

    # 4. An order far from the market: 90% of the best bid, rounded down to the price step, one lot.
    price = brokapi.round_to_step(best_bid * Decimal("0.9"), params.price_step, brokapi.RoundMode.DOWN)
    cid = brokapi.new_cid()  # a real bot writes the cid to its journal here, before `place`
    ack = await client.place(cid=cid, instrument=sber, side=brokapi.Side.BUY, qty=params.lot_size, price=price)
    print(f"placed: broker order id {ack.broker_id}, price {price}")

    # 5. Take it off and ask the broker what became of it. The answer of `order_state` is the proof.
    await client.cancel(cid)
    state = await client.order_state(cid)
    print(f"after cancel: {state.state.kind.value}, orders alive: {len(await client.active_orders())}")
    # ANCHOR_END: first_order


# ANCHOR: mock
async def on_the_imitation() -> None:
    # The block starts the imitation and stops it at the end. `mock.connect()` is `brokapi.connect(...)` to it.
    async with await mock_tbank() as mock:
        client = await mock.connect()
        await first_order(client)

        # The price of the imitation stands still: it has no market behind it.
        book = await client.order_book(await client.instrument("SBER"), depth=1)
        print(f"the price stands still: bid {book.bids[0].price}")
        # ANCHOR_END: mock


# ANCHOR: sandbox
async def on_the_sandbox() -> None:
    # TBANK_TOKEN is the token of the sandbox. sandbox=True is the address of the sandbox (the real one is the default).
    client = await brokapi.connect("tbank", sandbox=True)
    try:
        await first_order(client)
    finally:
        await client.close()
        # ANCHOR_END: sandbox


if __name__ == "__main__":
    asyncio.run(on_the_sandbox() if sys.argv[1:] == ["sandbox"] else on_the_imitation())

"""Quick start on BCS: read first, then one order far from the market, cancelled at once.

This program is the code of the page "Быстрый старт" of the Python section of the book. The book includes the marked
parts below, so the text and the code that is tested cannot drift apart.

Run it with a real account (BCS has no sandbox, the account is real)::

    BCS_REFRESH_TOKEN=... BCS_IS_WRITE=true python quickstart_bcs.py

The tests run `run()` against the imitation of BCS (`brokapi.testing`): no network, no account, no money.
"""

import asyncio
import os
from datetime import datetime, timedelta, timezone
from decimal import Decimal

import brokapi

# The price of the test order is this share of the best bid. Far enough that it does not fill in a normal session,
# near enough that the exchange does not refuse it as being outside the allowed corridor.
FAR_FROM_MARKET = Decimal("0.9")


async def wait_for_order(client: brokapi.Client, cid, kind: brokapi.OrderStateKind) -> None:
    """Reads the events until the order `cid` reaches `kind`, and prints every state it goes through.

    An event is a notice. The answer of `order_state` is the proof, so a missing event is not an error here."""

    async def read() -> None:
        async for envelope in client.events:
            order = envelope.payload
            if isinstance(order, brokapi.OrderSnapshot) and order.cid == cid:
                print(f"event: order {cid} is {order.state.kind.value}")
                if order.state.kind is kind:
                    return

    try:
        await asyncio.wait_for(read(), 5)
    except asyncio.TimeoutError:
        print(f"no event {kind.value} within 5 s, the state is checked with order_state below")


async def run(client: brokapi.Client, *, can_trade: bool) -> None:
    """The whole quick start on a connected client."""
    # ANCHOR: read
    sber = await client.instrument("SBER")  # the ticker on the board TQBR

    # 1. Portfolio: money and positions of the account.
    portfolio = await client.portfolio()
    print(f"portfolio: {len(portfolio.balances)} balance(s), {len(portfolio.positions)} position(s)")
    for balance in portfolio.balances:
        print(f"  money {balance.currency}: {balance.available} free, {balance.blocked} blocked")

    # 2. Order book: best bid and best ask.
    book = await client.order_book(sber, depth=5)
    best_bid = book.bids[0].price if book.bids else None
    best_ask = book.asks[0].price if book.asks else None
    print(f"order book SBER: best bid {best_bid}, best ask {best_ask}")

    # 3. Candles: the last hour of five-minute bars.
    now = datetime.now(timezone.utc)
    bars = await client.candles(sber, brokapi.Timeframe.M5, now - timedelta(hours=1), now)
    print(f"candles M5: {len(bars)} bar(s), last close {bars[-1].close if bars else None}")
    # ANCHOR_END: read

    if not can_trade:
        print("the token is read-only (BCS_IS_WRITE is not true): the order step is skipped")
        return

    # ANCHOR: warning
    print("WARNING: BCS has no sandbox. The account is real, the order below goes to the exchange.")
    # ANCHOR_END: warning

    # ANCHOR: order
    # The price: far below the best bid, a multiple of the price step. The quantity: the minimum.
    params = await client.trading_params(sber)
    reference = best_bid or (bars[-1].close if bars else None)
    if reference is None:
        raise SystemExit("no price to start from: the book and the candles are empty")
    # The rounding is exact: the price is a whole number of steps, no 0.9999999 noise.
    price = brokapi.round_to_step(reference * FAR_FROM_MARKET, params.price_step, brokapi.RoundMode.DOWN)
    print(f"order: buy {params.min_qty} at {price} (best bid {reference}, price step {params.price_step})")

    # The gate is closed until the first reconcile. The ledger of this new bot is empty. Subscribe first, so no
    # event between the snapshot of the reconcile and the subscription is lost.
    await client.subscribe_order_state()
    report = await client.reconcile([])
    print(f"reconcile: {len(report.foreign)} foreign order(s) on the account")

    # The cid is made by the bot and belongs in its journal before the order is sent.
    cid = brokapi.new_cid()
    # Here the bot writes `cid` to its journal as "sending".
    print(f"cid {cid}")
    ack = await client.place(
        cid=cid,
        instrument=sber,
        side=brokapi.Side.BUY,
        qty=params.min_qty,
        price=price,
    )
    print(f"accepted: broker order id {ack.broker_id}")
    await wait_for_order(client, cid, brokapi.OrderStateKind.ACKED)

    # Cancel at once and look at the final state.
    await client.cancel(cid)
    await wait_for_order(client, cid, brokapi.OrderStateKind.CANCELLED)
    last = await client.order_state(cid)
    print(f"order_state: {last.state.kind.value}")
    # ANCHOR_END: order


async def main() -> None:
    # ANCHOR: connect
    # BCS_REFRESH_TOKEN and BCS_IS_WRITE come from the environment (a .env file works)
    client = await brokapi.connect("bcs")
    print("connected: bcs-md and bcs-ud started")
    # ANCHOR_END: connect
    try:
        await run(client, can_trade=os.environ.get("BCS_IS_WRITE") == "true")
    finally:
        # ANCHOR: stop
        await client.close()
        print("stopped")
        # ANCHOR_END: stop


if __name__ == "__main__":
    asyncio.run(main())

Что произошло по шагам на БКС

1. connect поднял оба коннектора. У БКС, Финама, АЛОРа и Bybit он сразу проходит авторизацию, поэтому неверный токен виден на этом шаге.
2. Чтение ничего не меняет и не требует сверки.
3. subscribe_order_state дал подписку на события своих заявок и вернулся, когда поток открыт. Она сделана до сверки нарочно.
4. reconcile([]) открыл шлюз команд. До него place вернул бы NotReconciled.
5. place вернул OrderAck: «брокер принял». Статусы приходят событиями в client.events, порядок между ответом и событием не гарантирован.
6. cancel снял заявку, close остановил коннекторы.

Дальше: торговый бот на событиях, стоп-заявки, аварийная остановка. Если вы пришли с tinkoff-investments: таблица соответствий.

Если вы пришли с tinkoff-investments

Справка для тех, у кого бот уже написан на SDK tinkoff-investments (gRPC API Т-Банка, T-Invest API) и кто переносит его на brokapi. Цель: показать, что в каком месте меняется, чтобы перенос не превратился в двойную заявку. Левая колонка описывает API Т-Банка, на котором стоит SDK, названия методов сверяйте с версией своего SDK.

Идея одна: brokapi берет на себя то, что в SDK делал ваш код (сверка, лимиты, перевод единиц), и взамен требует порядка, который в SDK был по желанию. Поэтому перенос - это не замена вызовов один к одному.

Таблица соответствий

Что и как переносить

Два преобразования, без которых не обходится ни один перенос. Лоты в штуки: старый код ставил quantity=lots, новому нужны единицы инструмента. Quotation в Decimal: пригодится для данных, которые вы хранили в файлах (в самом brokapi цены уже Decimal).

async def place_lots(
    client: brokapi.Client, ticker: str, lots: int, price: Decimal, side: brokapi.Side = brokapi.Side.BUY
) -> uuid.UUID:
    """The order of the old code was `quantity=lots`. Here the quantity is in units of the instrument: lots times the lot size."""
    instrument = await client.instrument(ticker)  # an InstrumentId (the uid inside), not a figi string
    params = await client.trading_params(instrument)
    cid = brokapi.new_cid()  # the old `order_id`: made by the bot, in its journal before the call
    await client.place(cid=cid, instrument=instrument, side=side, qty=params.lot_size * lots, price=price)
    return cid

def quotation_to_decimal(units: int, nano: int) -> Decimal:
    """`Quotation(units, nano)` and the `units` and `nano` of `MoneyValue` of the old code, for the data you keep in files.

    Exact: no float on the way. Negative prices have both parts negative, as in the API of the broker."""
    return Decimal(units) + Decimal(nano) / Decimal(1_000_000_000)

Порядок переноса, который не оставляет дыр:

1. Подключите клиента к песочнице и прогоните старую логику через connect("tbank", sandbox=True). Первая ступень вообще без токена: Быстрый старт.
2. Замените номер заявки: order_id -> cid из журнала, записанного до вызова. Это главное отличие, на нем держится безопасность повторов.
3. Добавьте подписку на статусы и reconcile в начале работы. Бот, у которого в журнале есть живые cid, передает их в reconcile.
4. Разберите исходы place по таблице из торгового бота: Unknown и Transport на команде не повторяются.
5. Если у бота есть стопы, добавьте проверку на старте: Бот со стопом: старт и рестарт.
6. Перед боевым счетом - Перед боевым счетом и Аварийная остановка бота.

Если вы пришли с QUIK

brokapi не подключается к QUIK и не заменяет терминал: он говорит с API брокера напрямую (БКС, Т-Банк, Финам, АЛОР, Bybit), и ни терминал, ни запущенный на машине QUIK не нужны. Скрипты QUIK (Lua, QUIK# и им подобные) живут внутри терминала и реагируют на его события (OnOrder, OnTrade, OnTransReply) и таблицы, заявка там - транзакция с номером TRANS_ID. В brokapi то же самое делают поток client.events (статусы заявок и сделки), portfolio() с позициями и cid, который бот придумывает сам и пишет в журнал до place. Переносится логика стратегии, а слой связи с терминалом заменяется целиком. Что изменится по порядку работы, описано в таблице выше: сверка до торговли, единицы в штуках, Decimal вместо float.

Как написать торгового бота на событиях (Python)

Инструкция. Цель: бот, который читает стакан, по сигналу ставит заявку, следит за ее статусами, выходит из неясного исхода (Unknown) и аккуратно останавливается. Правила, на которых он стоит, собраны в Контракте для агентов, причины - в Круге команд и Круге жизни. Код ниже - куски программы trading_bot.py, весь ее текст в конце страницы. Она запускается тестом против имитации БКС, поэтому текст и проверенный код не расходятся.

Стратегия в примере заглушка: когда пришел стакан и своей заявки нет, купить минимальное количество на 1% ниже лучшей цены покупки. Все остальное (журнал, сверка, исходы каждой команды, Resync, Overflow, Reconnected, остановка) нужно любому настоящему боту.

Что получится

Один клиент, один поток событий и один цикл. Бот решает по событию, а исходы place разбирает на месте.

flowchart TB
  BR[Брокер] --> C[Client: рыночные данные и счет]
  C --> Q[client.events: один поток]
  Q --> BOT[TradingBot.on_event]
  BOT -- стакан, заявки нет --> P[place, cid в журнал до вызова]
  P -- ответ OrderAck --> W[working: ждем событий заявки]
  P -- Rejected --> D[done: отказ]
  P -- RateLimited или шлюз закрыт --> N[не отправлено: позже, новый cid]
  P -- Unknown --> U[order_state по тому же cid]
  U -- заявка есть --> W
  U -- брокер не знает --> D2[done: не ставилась]

Из схемы следует: ответ на place и статусы приходят разными путями (результат вызова и события), Unknown разбирается запросом, а не повтором, и каждая развилка заканчивается записью в журнал.

Журнал

Журнал - память бота. Библиотека не пишет на диск ничего. Каждое изменение записывается в файл и сбрасывается на диск до вызова, которому оно нужно: журнал, записанный после place, теряет заявку, которую оборвал сбой между отправкой и записью. Последняя строка по cid главная. Битая последняя строка (сбой посреди записи) пропускается.

class Journal:
    """The memory of the bot. The library writes nothing to disk, so the bot does.

    One JSON line per change, flushed to disk BEFORE the call that needs it: a journal written after `place` loses
    the order that a crash cuts in between. The last line of a cid wins.
    """

    def __init__(self, path: Optional[Path] = None) -> None:
        self.path = path
        self.orders: dict[uuid.UUID, tuple[str, str]] = {}
        if path is not None and path.exists():
            for line in path.read_text().splitlines():
                try:
                    row = json.loads(line)
                except json.JSONDecodeError:
                    continue  # a line cut by a crash carries no complete change
                self.orders[uuid.UUID(row["cid"])] = (row["state"], row.get("detail", ""))

    def set(self, cid: uuid.UUID, state: str, detail: str = "") -> None:
        """`state`: sending, working, unknown or done."""
        self.orders[cid] = (state, detail)
        if self.path is not None:
            with self.path.open("a") as file:
                file.write(json.dumps({"cid": str(cid), "state": state, "detail": detail}) + "\n")
                file.flush()
                os.fsync(file.fileno())

    def alive(self) -> list[uuid.UUID]:
        """The ledger for `reconcile`: the orders the bot believes are alive."""
        return [cid for cid, (state, _) in self.orders.items() if state != "done"]

Старт бота и события

start делает все по порядку: подписка на статусы и исполнения, reconcile со списком из журнала, правила инструмента, подписка на стакан. Пока start не вернулся, бот не торгует. Подписки идут до сверки: иначе событие между снимком сверки и подпиской пропало бы.

class TradingBot:
    def __init__(self, client: brokapi.Client, ticker: str, journal: Journal, budget: Decimal) -> None:
        self.client = client
        self.ticker = ticker
        self.journal = journal
        self.budget = budget  # how much to buy in all
        self.filled = Decimal(0)
        self.working: Optional[uuid.UUID] = None
        self.top_bid: Optional[Decimal] = None
        self.book_sub: Optional[int] = None
        self.need_reconcile = False
        self.placed = asyncio.Event()  # set when the first order stands: a hook for the tests

    @property
    def done(self) -> bool:
        return self.filled >= self.budget and self.working is None

    async def start(self) -> None:
        """In this order: subscriptions, reconcile with the journal, the rules of the instrument, the book.
        Until `start` returns, the bot does not trade."""
        self.instrument = await self.client.instrument(self.ticker)
        await self.client.subscribe_order_state()
        await self.client.subscribe_executions()
        await self.reconcile()
        self.params = await self.client.trading_params(self.instrument)
        self.book_sub = await self.client.subscribe_order_book(self.instrument, depth=1)

    async def reconcile(self) -> None:
        report = await self.client.reconcile(self.journal.alive())
        for snapshot in report.confirmed:
            self.on_order(snapshot)
        for cid in report.closed_offline:
            # The broker has no such order and it is not alive: it ended while the bot was away, or was never sent.
            self.journal.set(cid, "done", "closed while the bot was away")
        self.need_reconcile = False

    async def on_event(self, envelope: brokapi.Envelope) -> None:
        event = envelope.payload
        if isinstance(event, brokapi.OrderBookSnapshot) and envelope.sub == self.book_sub:
            self.top_bid = event.bids[0].price if event.bids else None
            await self.try_buy()
        elif isinstance(event, brokapi.Resync):
            self.top_bid = None  # the next snapshot replaces the book
        elif isinstance(event, brokapi.OrderSnapshot):
            self.on_order(event)
        elif isinstance(event, brokapi.Overflow):
            if event.sub == self.book_sub:
                self.top_bid = None  # a lost book is not a hole in the orders: take a new subscription
                self.book_sub = await self.client.subscribe_order_book(self.instrument, depth=1)
            else:
                self.need_reconcile = True  # the orders may have a hole: read the stream to the end, then reconcile
        elif isinstance(event, brokapi.Reconnected):
            # The stream of the orders or of the fills was cut and opened again: what happened in the gap never
            # reached the bot. The gate is closed until the reconcile, so read the stream to the end, then reconcile.
            self.need_reconcile = True
        elif isinstance(event, brokapi.UnknownEvent):
            # A kind this package does not know. It may be about lost data, like the two above: reconcile.
            self.need_reconcile = True

    def on_order(self, snapshot: brokapi.OrderSnapshot) -> None:
        """The state of an order comes from the events, not from the answer of `place` (it only means "accepted")."""
        if snapshot.cid not in self.journal.orders:
            return  # an order placed by hand: the bot does not enter it into its journal
        if snapshot.state.is_final:
            self.journal.set(snapshot.cid, "done", snapshot.state.kind.value)
            # The filled quantity is taken from the snapshot, not summed from `Execution` events: after an
            # overflow the reconcile returns the right number by itself.
            self.filled += snapshot.filled
            if self.working == snapshot.cid:
                self.working = None
        else:
            self.journal.set(snapshot.cid, "working")
            self.working = snapshot.cid

Что видно в коде:

• Resync обнуляет сохраненный стакан, следующий снимок его заменит.
• Overflow бывает двух видов. Переполнилась подписка на стакан (ее sub известен боту): стакан объявляется недействительным и подписка оформляется заново. Переполнился поток своих заявок: нужна сверка, а торговля до нее закрыта (Degraded).
• Reconnected значит, что поток своих заявок или исполнений оборвался и открыт снова: за обрыв могли пройти события, а торговля закрыта (Degraded) до сверки. Бот дочитывает поток и сверяется (читает active_orders, order_state, executions с запасом раньше gap_from, зовет reconcile).
• Событие неизвестного типа (UnknownEvent) не ломает цикл. Оно может быть про потерю данных, как два предыдущих, поэтому бот на всякий случай сверяется.
• Состояние заявки берется из событий (on_order), а не из ответа на place: ответ значит «брокер принял».
• В поток статусов попадают все заявки счета, в том числе поставленные руками. Заявок, которых нет в журнале, бот не трогает (Контракт, правило 11).
• Сколько исполнено, бот берет из поля filled снимков, а не складывает события Execution: после Overflow сверка сама вернет правильное число.

Сигнал и заявка со всеми исходами

async def try_buy(self) -> None:
    """The signal, and the order with every outcome handled."""
    if self.need_reconcile:
        await self.reconcile()
    if self.working is not None or self.top_bid is None or self.filled >= self.budget:
        return
    # Exact arithmetic. Round DOWN for a buy so the price never exceeds the plan, and to the step.
    price = brokapi.round_to_step(self.top_bid * BUY_AT, self.params.price_step, brokapi.RoundMode.DOWN)
    cid = brokapi.new_cid()
    self.journal.set(cid, "sending")  # BEFORE the call
    try:
        await self.client.place(
            cid=cid,
            instrument=self.instrument,
            side=brokapi.Side.BUY,
            qty=self.params.min_qty,
            price=price,
        )
    except brokapi.Rejected as error:
        self.journal.set(cid, "done", f"rejected: {error.code}")  # the broker said no: no order exists
    except (brokapi.NotReconciled, brokapi.Degraded):
        self.journal.set(cid, "done", "not sent: gate closed")
        self.need_reconcile = True
    except brokapi.RateLimited as error:
        self.journal.set(cid, "done", "not sent: rate limit")
        await asyncio.sleep(error.retry_after.total_seconds())  # then the next book tries again with a new cid
    except brokapi.Unknown:
        # Nobody knows whether the order exists. NEVER send it again: ask the broker.
        self.journal.set(cid, "unknown")
        await self.resolve_unknown(cid)
    else:
        self.working = cid
        self.journal.set(cid, "working")
        self.placed.set()

async def resolve_unknown(self, cid: uuid.UUID) -> None:
    """The way out of `Unknown`: `order_state` by the same cid."""
    try:
        snapshot = await self.client.order_state(cid)
    except brokapi.Rejected as error:
        if error.code != "not_found":
            raise
        # The broker has no such order. A broker can be late: a real bot asks again after a pause, and only then
        # writes "not placed". Here it is written at once and the next signal uses a new cid.
        self.journal.set(cid, "done", "unknown, not found at the broker")
        return
    self.on_order(snapshot)
    self.placed.set()

Цена считается Decimal и округляется вниз до шага (round_to_step): покупка не должна выйти за план, а цена должна лежать на сетке брокера. Деньги и цены в боте нигде не проходят через float.

Цикл и остановка

Поток событий читает одно место. Если бот делает долгую работу, он выносит ее в отдельную задачу и передает события своей очередью: пока поток не читается, подписки без потерь копят события и при переполнении закрывают торговлю.

async def run(bot: TradingBot) -> None:
    """Starts the bot and reads events until the budget is bought. The one place that reads the stream."""
    await bot.start()
    try:
        async for envelope in bot.client.events:
            await bot.on_event(envelope)
            if bot.done:
                break
    finally:
        # Orders at the exchange are not cancelled by a stop. This bot leaves none: it stops when its order is done.
        if bot.working is not None:
            await bot.client.cancel(bot.working)

Остановка клиента не снимает заявок на бирже. Бот из примера не оставляет ни одной: он останавливается, когда его заявка исполнена, а если вышел раньше, снимает ее сам.

Вся программа

"""A trading bot on events: it reads the book, buys once, follows the order and leaves cleanly.

The code of the page "Как написать торгового бота на событиях" of the Python section of the book. The strategy is a
stub: when a book arrives and the bot has no order, buy the minimal quantity 1% below the best bid. Everything else
(the journal, the reconcile, the outcome of every command, `Resync`, `Overflow`, `Reconnected`, the stop) any real bot needs.

The tests run it against the imitation of BCS.
"""

import asyncio
import json
import os
import uuid
from decimal import Decimal
from pathlib import Path
from typing import Optional

import brokapi

BUY_AT = Decimal("0.99")


# ANCHOR: journal
class Journal:
    """The memory of the bot. The library writes nothing to disk, so the bot does.

    One JSON line per change, flushed to disk BEFORE the call that needs it: a journal written after `place` loses
    the order that a crash cuts in between. The last line of a cid wins.
    """

    def __init__(self, path: Optional[Path] = None) -> None:
        self.path = path
        self.orders: dict[uuid.UUID, tuple[str, str]] = {}
        if path is not None and path.exists():
            for line in path.read_text().splitlines():
                try:
                    row = json.loads(line)
                except json.JSONDecodeError:
                    continue  # a line cut by a crash carries no complete change
                self.orders[uuid.UUID(row["cid"])] = (row["state"], row.get("detail", ""))

    def set(self, cid: uuid.UUID, state: str, detail: str = "") -> None:
        """`state`: sending, working, unknown or done."""
        self.orders[cid] = (state, detail)
        if self.path is not None:
            with self.path.open("a") as file:
                file.write(json.dumps({"cid": str(cid), "state": state, "detail": detail}) + "\n")
                file.flush()
                os.fsync(file.fileno())

    def alive(self) -> list[uuid.UUID]:
        """The ledger for `reconcile`: the orders the bot believes are alive."""
        return [cid for cid, (state, _) in self.orders.items() if state != "done"]
# ANCHOR_END: journal


# ANCHOR: bot
class TradingBot:
    def __init__(self, client: brokapi.Client, ticker: str, journal: Journal, budget: Decimal) -> None:
        self.client = client
        self.ticker = ticker
        self.journal = journal
        self.budget = budget  # how much to buy in all
        self.filled = Decimal(0)
        self.working: Optional[uuid.UUID] = None
        self.top_bid: Optional[Decimal] = None
        self.book_sub: Optional[int] = None
        self.need_reconcile = False
        self.placed = asyncio.Event()  # set when the first order stands: a hook for the tests

    @property
    def done(self) -> bool:
        return self.filled >= self.budget and self.working is None

    async def start(self) -> None:
        """In this order: subscriptions, reconcile with the journal, the rules of the instrument, the book.
        Until `start` returns, the bot does not trade."""
        self.instrument = await self.client.instrument(self.ticker)
        await self.client.subscribe_order_state()
        await self.client.subscribe_executions()
        await self.reconcile()
        self.params = await self.client.trading_params(self.instrument)
        self.book_sub = await self.client.subscribe_order_book(self.instrument, depth=1)

    async def reconcile(self) -> None:
        report = await self.client.reconcile(self.journal.alive())
        for snapshot in report.confirmed:
            self.on_order(snapshot)
        for cid in report.closed_offline:
            # The broker has no such order and it is not alive: it ended while the bot was away, or was never sent.
            self.journal.set(cid, "done", "closed while the bot was away")
        self.need_reconcile = False

    async def on_event(self, envelope: brokapi.Envelope) -> None:
        event = envelope.payload
        if isinstance(event, brokapi.OrderBookSnapshot) and envelope.sub == self.book_sub:
            self.top_bid = event.bids[0].price if event.bids else None
            await self.try_buy()
        elif isinstance(event, brokapi.Resync):
            self.top_bid = None  # the next snapshot replaces the book
        elif isinstance(event, brokapi.OrderSnapshot):
            self.on_order(event)
        elif isinstance(event, brokapi.Overflow):
            if event.sub == self.book_sub:
                self.top_bid = None  # a lost book is not a hole in the orders: take a new subscription
                self.book_sub = await self.client.subscribe_order_book(self.instrument, depth=1)
            else:
                self.need_reconcile = True  # the orders may have a hole: read the stream to the end, then reconcile
        elif isinstance(event, brokapi.Reconnected):
            # The stream of the orders or of the fills was cut and opened again: what happened in the gap never
            # reached the bot. The gate is closed until the reconcile, so read the stream to the end, then reconcile.
            self.need_reconcile = True
        elif isinstance(event, brokapi.UnknownEvent):
            # A kind this package does not know. It may be about lost data, like the two above: reconcile.
            self.need_reconcile = True

    def on_order(self, snapshot: brokapi.OrderSnapshot) -> None:
        """The state of an order comes from the events, not from the answer of `place` (it only means "accepted")."""
        if snapshot.cid not in self.journal.orders:
            return  # an order placed by hand: the bot does not enter it into its journal
        if snapshot.state.is_final:
            self.journal.set(snapshot.cid, "done", snapshot.state.kind.value)
            # The filled quantity is taken from the snapshot, not summed from `Execution` events: after an
            # overflow the reconcile returns the right number by itself.
            self.filled += snapshot.filled
            if self.working == snapshot.cid:
                self.working = None
        else:
            self.journal.set(snapshot.cid, "working")
            self.working = snapshot.cid
# ANCHOR_END: bot

    # ANCHOR: place
    async def try_buy(self) -> None:
        """The signal, and the order with every outcome handled."""
        if self.need_reconcile:
            await self.reconcile()
        if self.working is not None or self.top_bid is None or self.filled >= self.budget:
            return
        # Exact arithmetic. Round DOWN for a buy so the price never exceeds the plan, and to the step.
        price = brokapi.round_to_step(self.top_bid * BUY_AT, self.params.price_step, brokapi.RoundMode.DOWN)
        cid = brokapi.new_cid()
        self.journal.set(cid, "sending")  # BEFORE the call
        try:
            await self.client.place(
                cid=cid,
                instrument=self.instrument,
                side=brokapi.Side.BUY,
                qty=self.params.min_qty,
                price=price,
            )
        except brokapi.Rejected as error:
            self.journal.set(cid, "done", f"rejected: {error.code}")  # the broker said no: no order exists
        except (brokapi.NotReconciled, brokapi.Degraded):
            self.journal.set(cid, "done", "not sent: gate closed")
            self.need_reconcile = True
        except brokapi.RateLimited as error:
            self.journal.set(cid, "done", "not sent: rate limit")
            await asyncio.sleep(error.retry_after.total_seconds())  # then the next book tries again with a new cid
        except brokapi.Unknown:
            # Nobody knows whether the order exists. NEVER send it again: ask the broker.
            self.journal.set(cid, "unknown")
            await self.resolve_unknown(cid)
        else:
            self.working = cid
            self.journal.set(cid, "working")
            self.placed.set()

    async def resolve_unknown(self, cid: uuid.UUID) -> None:
        """The way out of `Unknown`: `order_state` by the same cid."""
        try:
            snapshot = await self.client.order_state(cid)
        except brokapi.Rejected as error:
            if error.code != "not_found":
                raise
            # The broker has no such order. A broker can be late: a real bot asks again after a pause, and only then
            # writes "not placed". Here it is written at once and the next signal uses a new cid.
            self.journal.set(cid, "done", "unknown, not found at the broker")
            return
        self.on_order(snapshot)
        self.placed.set()
    # ANCHOR_END: place


# ANCHOR: loop
async def run(bot: TradingBot) -> None:
    """Starts the bot and reads events until the budget is bought. The one place that reads the stream."""
    await bot.start()
    try:
        async for envelope in bot.client.events:
            await bot.on_event(envelope)
            if bot.done:
                break
    finally:
        # Orders at the exchange are not cancelled by a stop. This bot leaves none: it stops when its order is done.
        if bot.working is not None:
            await bot.client.cancel(bot.working)
# ANCHOR_END: loop


async def main() -> None:
    client = await brokapi.connect("bcs")
    try:
        bot = TradingBot(client, "SBER", Journal(Path("journal.jsonl")), budget=Decimal(1))
        await run(bot)
    finally:
        await client.close()


if __name__ == "__main__":
    asyncio.run(main())

Как проверить

Для этой команды нужен клон репозитория: тесты и примеры в пакет pip install brokapi не входят. Версия пакета должна быть той же, что у клона.

git clone https://github.com/runinfra/brokapi && cd brokapi
pip install brokapi pytest pytest-asyncio
cd crates/python
pytest tests/test_examples.py -k trading_bot

Тесты проверяют: бот покупает один раз и останавливается, когда имитация исполнила заявку. Бот, у которого ответ на place потерялся (Unknown), спрашивает order_state и не шлет заявку второй раз. Отказ и закрытый шлюз разбираются по таблице выше. Неизвестное событие включает сверку.

Как собрать инфраструктуру на несколько брокеров и счетов (Python)

Инструкция. Цель: один процесс держит несколько брокеров и несколько счетов, читает события всех одним циклом, ведет один журнал заявок в файле и после рестарта сверяет каждый счет с этим журналом. Правила: Контракт для агентов, логика счетов и лимитов: Несколько счетов и брокеров. Код ниже - куски программы infrastructure.py. Она запускается тестом против имитаций брокеров: две жизни процесса, между ними одна заявка исполняется.

В примере несколько счетов: БКС (один), Т-Банк (два, один токен), Финам (один) и АЛОР (один).

Что получится

Один клиент на счет. Клиенты одного брокера делят счетчик лимитов, клиенты разных брокеров нет.

flowchart TB
  subgraph B[БКС: счетчик лимитов токена]
    A1[клиент bcs]
  end
  subgraph T[Т-Банк: один счетчик на двоих]
    A2[клиент tbank-a]
    A3[клиент tbank-b]
  end
  subgraph F[Финам: счетчик пользователя]
    A4[клиент finam]
  end
  subgraph L[АЛОР: счетчик логина]
    A5[клиент alor]
  end
  B --> M[brokapi.merge: один цикл событий]
  T --> M
  F --> M
  L --> M
  M --> J[(журнал заявок в файле)]

Из схемы следует: брокер считает лимит на токен или пользователя, поэтому два клиента одного токена обязаны делить счетчик (limiter=), а чужого брокера счетчик не касается. События всех клиентов идут в один цикл, и поле source говорит, чье это событие.

Журнал заявок в файле

Текстовый файл, строка на изменение: счет, cid, состояние, подробность. Последняя строка по cid главная. Каждая строка сбрасывается на диск до вызова, которому нужна: строка «отправляю» пишется до place, иначе сбой между отправкой и записью теряет заявку.

class Journal:
    """The order journal: a text file, one line per change, `account TAB cid TAB state TAB detail`. The last line of
    a cid wins. Every line is flushed to disk before the call that needs it."""

    def __init__(self, path: Path) -> None:
        self.path = path
        self.orders: dict[uuid.UUID, tuple[str, str]] = {}  # cid -> (account, state)
        if path.exists():
            for line in path.read_text().splitlines():
                parts = line.split("\t", 3)
                if len(parts) < 3:
                    continue  # a line cut by a crash carries no complete change
                try:
                    self.orders[uuid.UUID(parts[1])] = (parts[0], parts[2])
                except ValueError:
                    continue

    def set(self, account: str, cid: uuid.UUID, state: str, detail: str = "") -> None:
        """`state`: sending (written BEFORE place), working, or done."""
        self.orders[cid] = (account, state)
        with self.path.open("a") as file:
            file.write(f"{account}\t{cid}\t{state}\t{detail}\n")
            file.flush()
            os.fsync(file.fileno())

    def live(self, account: str) -> list[uuid.UUID]:
        """The ledger of one account for `reconcile`: the orders it believes are alive."""
        return [c for c, (a, s) in self.orders.items() if a == account and s != "done"]

Подключение, подписки, сверка

Подключение идет по порядку: клиенты, подписки на статусы и исполнения каждого счета, и только потом сверка каждого счета со своей частью журнала. Второй счет Т-Банка берет счетчик первого: limiter=clients["tbank-a"].limiter. Передать счетчик другого брокера нельзя: connect вернет Config. У каждого клиента свое имя (name=), оно попадает в source событий.

Сверка не сдается на первой же заминке: RateLimited и Transport значат «ответа пока нет», поэтому сверка ждет и спрашивает снова, несколько раз. Любая другая ошибка поднимается, повтор дал бы то же самое.

class Infra:
    """All the clients of the process and the journal."""

    def __init__(self, clients: dict[str, brokapi.Client], journal: Journal) -> None:
        self.clients = clients
        self.journal = journal
        self.degraded: set[str] = set()  # accounts that lost events (Overflow, Reconnected): reconcile them before trading

    @classmethod
    async def start(cls, settings: dict[str, dict], journal_path: Path) -> "Infra":
        """Connects everything, subscribes, reconciles every account with the journal, and only then returns."""
        clients: dict[str, brokapi.Client] = {}
        # One limiter per area where the broker counts a limit. T-Bank counts per user: both accounts share one.
        # BCS counts per token, Finam per user, ALOR per login. The brokers never share.
        clients["bcs"] = await brokapi.connect("bcs", name="bcs", **settings.get("bcs", {}))
        clients["tbank-a"] = await brokapi.connect("tbank", name="tbank-a", **settings.get("tbank-a", {}))
        clients["tbank-b"] = await brokapi.connect(
            "tbank", name="tbank-b", limiter=clients["tbank-a"].limiter, **settings.get("tbank-b", {})
        )
        clients["finam"] = await brokapi.connect("finam", name="finam", **settings.get("finam", {}))
        clients["alor"] = await brokapi.connect("alor", name="alor", **settings.get("alor", {}))
        infra = cls(clients, Journal(journal_path))
        # Subscribe to the statuses and fills of every account FIRST, then reconcile it with ITS part of the journal.
        for client in clients.values():
            await client.subscribe_order_state()
            await client.subscribe_executions()
        for name in ACCOUNTS:
            await infra.reconcile(name)
        return infra

    async def reconcile(self, name: str) -> brokapi.ReconcileReport:
        """A reconcile that does not give up on the first hiccup: a limit or a network error means "no sealed
        answer yet", so wait and ask again, a few times. Any other error is raised: a retry would fail the same way."""
        pause = 0.2
        for attempt in range(1, 6):
            try:
                report = await self.clients[name].reconcile(self.journal.live(name))
            except brokapi.RateLimited as error:
                if attempt == 5:
                    raise
                await asyncio.sleep(error.retry_after.total_seconds())
            except brokapi.Transport:
                if attempt == 5:
                    raise
                await asyncio.sleep(pause)
                pause *= 2
            else:
                for snapshot in report.confirmed:
                    self.journal.set(name, snapshot.cid, "working")
                for cid in report.closed_offline:
                    self.journal.set(name, cid, "done", "closed while away or never sent")
                self.degraded.discard(name)
                return report
        raise AssertionError("unreachable")

    async def place(
        self, name: str, instrument: brokapi.InstrumentId, qty: Decimal, price: Decimal
    ) -> tuple[uuid.UUID, Optional[brokapi.BrokapiError]]:
        """One order on one account. The journal line goes first; the outcome is written after."""
        cid = brokapi.new_cid()
        self.journal.set(name, cid, "sending")
        try:
            await self.clients[name].place(
                cid=cid, instrument=instrument, side=brokapi.Side.BUY, qty=qty, price=price
            )
        except brokapi.Unknown as error:
            return cid, error  # the journal says "sending": the next reconcile or order_state settles it
        except brokapi.BrokapiError as error:
            self.journal.set(name, cid, "done", f"not placed: {error}")  # nothing was sent, or the broker refused
            return cid, error
        self.journal.set(name, cid, "working")
        return cid, None

    async def close(self) -> None:
        for client in self.clients.values():
            await client.close()

place пишет строку в журнал до вызова. Если ответ потерялся (Unknown), строка остается «отправляю», а решает ее следующая сверка или order_state. Отказ и ошибка до отправки закрывают строку сразу: заявки нет.

Один цикл событий

brokapi.merge читает потоки всех клиентов как один. Заявка ушла в конец (исполнена, снята) - строка журнала закрывается. Overflow и Reconnected (поток заявок оборвался и открыт снова) помечают счет: поток надо дочитать, потом сверить именно этот счет.

async def watch(infra: Infra) -> None:
    """One loop over the events of all the accounts. `source` says whose each event is."""
    async for envelope in brokapi.merge(*infra.clients.values()):
        event = envelope.payload
        name = envelope.source.removesuffix("-ud").removesuffix("-md")
        if isinstance(event, brokapi.OrderSnapshot) and event.state.is_final:
            infra.journal.set(name, event.cid, "done", event.state.kind.value)
        elif isinstance(event, (brokapi.Overflow, brokapi.Reconnected)):
            # Events were lost (a full buffer, or a stream of the orders that was cut and opened again). Read the
            # stream to the end, then reconcile. The loop does both: it reads, and marks the account.
            infra.degraded.add(name)

merge кончается, когда закрыты все клиенты. Не бросайте чтение, пока работаете с этими клиентами: событие, которое цикл только что достал, при выходе теряется.

Рестарт

Что делает тест, это и есть сценарий. Первая жизнь: на каждом из четырех счетов ставится заявка, плюс в журнале строка для заявки, которая так и не ушла. Процесс уходит, не снимая заявок. Пока его нет, одна заявка исполняется. Вторая жизнь: подключение со сверкой. Заявка, которой не было у брокера, закрывается как «не уходила», остальные подтверждаются, исполненная находится через order_state.

Чего библиотека не делает за бота: журнал, решение, что делать с чужими заявками (foreign), поиск итога по заявкам из closed_offline.

Вся программа

"""One process, several brokers and accounts: one event stream, one order journal in a file, and a restart that
reconciles every account against that journal.

The code of the page "Как собрать инфраструктуру на несколько брокеров и счетов" of the Python section of the book.
The accounts are BCS (one), T-Bank (two, one token), Finam (one) and ALOR (one). The tests play two lives of the process against
the imitations. Nothing here touches the network or money.
"""

import asyncio
import os
import uuid
from decimal import Decimal
from pathlib import Path
from typing import Optional

import brokapi

ACCOUNTS = ["bcs", "tbank-a", "tbank-b", "finam", "alor"]


# ANCHOR: journal
class Journal:
    """The order journal: a text file, one line per change, `account TAB cid TAB state TAB detail`. The last line of
    a cid wins. Every line is flushed to disk before the call that needs it."""

    def __init__(self, path: Path) -> None:
        self.path = path
        self.orders: dict[uuid.UUID, tuple[str, str]] = {}  # cid -> (account, state)
        if path.exists():
            for line in path.read_text().splitlines():
                parts = line.split("\t", 3)
                if len(parts) < 3:
                    continue  # a line cut by a crash carries no complete change
                try:
                    self.orders[uuid.UUID(parts[1])] = (parts[0], parts[2])
                except ValueError:
                    continue

    def set(self, account: str, cid: uuid.UUID, state: str, detail: str = "") -> None:
        """`state`: sending (written BEFORE place), working, or done."""
        self.orders[cid] = (account, state)
        with self.path.open("a") as file:
            file.write(f"{account}\t{cid}\t{state}\t{detail}\n")
            file.flush()
            os.fsync(file.fileno())

    def live(self, account: str) -> list[uuid.UUID]:
        """The ledger of one account for `reconcile`: the orders it believes are alive."""
        return [c for c, (a, s) in self.orders.items() if a == account and s != "done"]
# ANCHOR_END: journal


# ANCHOR: infra
class Infra:
    """All the clients of the process and the journal."""

    def __init__(self, clients: dict[str, brokapi.Client], journal: Journal) -> None:
        self.clients = clients
        self.journal = journal
        self.degraded: set[str] = set()  # accounts that lost events (Overflow, Reconnected): reconcile them before trading

    @classmethod
    async def start(cls, settings: dict[str, dict], journal_path: Path) -> "Infra":
        """Connects everything, subscribes, reconciles every account with the journal, and only then returns."""
        clients: dict[str, brokapi.Client] = {}
        # One limiter per area where the broker counts a limit. T-Bank counts per user: both accounts share one.
        # BCS counts per token, Finam per user, ALOR per login. The brokers never share.
        clients["bcs"] = await brokapi.connect("bcs", name="bcs", **settings.get("bcs", {}))
        clients["tbank-a"] = await brokapi.connect("tbank", name="tbank-a", **settings.get("tbank-a", {}))
        clients["tbank-b"] = await brokapi.connect(
            "tbank", name="tbank-b", limiter=clients["tbank-a"].limiter, **settings.get("tbank-b", {})
        )
        clients["finam"] = await brokapi.connect("finam", name="finam", **settings.get("finam", {}))
        clients["alor"] = await brokapi.connect("alor", name="alor", **settings.get("alor", {}))
        infra = cls(clients, Journal(journal_path))
        # Subscribe to the statuses and fills of every account FIRST, then reconcile it with ITS part of the journal.
        for client in clients.values():
            await client.subscribe_order_state()
            await client.subscribe_executions()
        for name in ACCOUNTS:
            await infra.reconcile(name)
        return infra

    async def reconcile(self, name: str) -> brokapi.ReconcileReport:
        """A reconcile that does not give up on the first hiccup: a limit or a network error means "no sealed
        answer yet", so wait and ask again, a few times. Any other error is raised: a retry would fail the same way."""
        pause = 0.2
        for attempt in range(1, 6):
            try:
                report = await self.clients[name].reconcile(self.journal.live(name))
            except brokapi.RateLimited as error:
                if attempt == 5:
                    raise
                await asyncio.sleep(error.retry_after.total_seconds())
            except brokapi.Transport:
                if attempt == 5:
                    raise
                await asyncio.sleep(pause)
                pause *= 2
            else:
                for snapshot in report.confirmed:
                    self.journal.set(name, snapshot.cid, "working")
                for cid in report.closed_offline:
                    self.journal.set(name, cid, "done", "closed while away or never sent")
                self.degraded.discard(name)
                return report
        raise AssertionError("unreachable")

    async def place(
        self, name: str, instrument: brokapi.InstrumentId, qty: Decimal, price: Decimal
    ) -> tuple[uuid.UUID, Optional[brokapi.BrokapiError]]:
        """One order on one account. The journal line goes first; the outcome is written after."""
        cid = brokapi.new_cid()
        self.journal.set(name, cid, "sending")
        try:
            await self.clients[name].place(
                cid=cid, instrument=instrument, side=brokapi.Side.BUY, qty=qty, price=price
            )
        except brokapi.Unknown as error:
            return cid, error  # the journal says "sending": the next reconcile or order_state settles it
        except brokapi.BrokapiError as error:
            self.journal.set(name, cid, "done", f"not placed: {error}")  # nothing was sent, or the broker refused
            return cid, error
        self.journal.set(name, cid, "working")
        return cid, None

    async def close(self) -> None:
        for client in self.clients.values():
            await client.close()
# ANCHOR_END: infra


# ANCHOR: events
async def watch(infra: Infra) -> None:
    """One loop over the events of all the accounts. `source` says whose each event is."""
    async for envelope in brokapi.merge(*infra.clients.values()):
        event = envelope.payload
        name = envelope.source.removesuffix("-ud").removesuffix("-md")
        if isinstance(event, brokapi.OrderSnapshot) and event.state.is_final:
            infra.journal.set(name, event.cid, "done", event.state.kind.value)
        elif isinstance(event, (brokapi.Overflow, brokapi.Reconnected)):
            # Events were lost (a full buffer, or a stream of the orders that was cut and opened again). Read the
            # stream to the end, then reconcile. The loop does both: it reads, and marks the account.
            infra.degraded.add(name)
# ANCHOR_END: events


async def main() -> None:
    # Every setting comes from the environment: BCS_REFRESH_TOKEN, BCS_IS_WRITE, TBANK_TOKEN, FINAM_SECRET,
    # ALOR_REFRESH_TOKEN, ALOR_PORTFOLIO, ...
    # The two T-Bank accounts differ in account_id.
    settings = {
        "tbank-a": {"account_id": os.environ["TBANK_ACCOUNT_ID"]},
        "tbank-b": {"account_id": os.environ["TBANK_ACCOUNT_ID_2"]},
    }
    infra = await Infra.start(settings, Path("orders.journal"))
    try:
        await watch(infra)
    finally:
        await infra.close()


if __name__ == "__main__":
    asyncio.run(main())

Как проверить

Для этой команды нужен клон репозитория (git clone https://github.com/runinfra/brokapi, затем pip install brokapi pytest pytest-asyncio): тесты и примеры в пакет pip install brokapi не входят.

cd crates/python
pytest tests/test_examples.py -k infrastructure

Один токен в двух процессах делит одну квоту брокера, а счетчик лимитов у каждого процесса свой.

Как скачать историю свечей

Инструкция. Цель: выгрузить длинную историю свечей по нескольким бумагам в файлы, не нарушая лимитов брокера, и после сбоя продолжить с того места, где остановились. Код - куски программы history.py, она запускается тестом против имитации БКС.

Как библиотека читает длинную историю

Один запрос свечей брокер принимает лишь в пределах: у БКС не больше 1440 баров, у Т-Банка предел зависит от таймфрейма, у Финама он осторожный, АЛОР предела не называет (вся история одним запросом, если не задать окно). Год часовых баров поэтому не один запрос, а несколько, и каждый тратит квоту. candle_pages режет период на окна по пределу брокера и читает их по одному на каждом шаге async for:

• на RateLimited ждет retry_after и читает окно снова
• на Transport читает окно еще раз с растущей паузой (чтение безопасно повторять, команды нет)
• на любой другой отказ останавливается: тот же запрос даст то же
• склеивает окна без дублей: бар, который вернули оба соседних окна, остается один раз
• страница бывает пустой (выходные, торги стояли). Это не конец, конец - StopAsyncIteration

async for page in client.candle_pages(instrument, brokapi.Timeframe.H1, start, end):
    ...  # page: список Candle, по порядку времени

Простой client.candles(...) читает один запрос, и если период длиннее предела, это Rejected. Для нескольких тысяч баров есть load_candles, он собирает все в память одним вызовом, а для больше пишите по страницам.

Файл сам себе контрольная точка

Один файл на бумагу: текст, строка на бар (время, открытие, максимум, минимум, закрытие, объем). Продолжение идет с конца файла: отдельного состояния нет, поэтому оно не может разойтись с данными. Сбой посреди записи оставляет оборванную строку, ее отрезают перед продолжением, иначе следующая страница приклеится к ней.

def last_bar(path: Path) -> datetime | None:
    """The open time of the last COMPLETE line of the file, or None. A line cut by a crash is ignored."""
    if not path.exists():
        return None
    last = None
    for line in path.read_text().splitlines():
        parts = line.split(",")
        if len(parts) == 6:
            last = datetime.fromisoformat(parts[0])
    return last


def cut_broken_tail(path: Path) -> None:
    """A crash can leave a half line at the end. Cut it off, or the next page would be glued to it."""
    if path.exists():
        text = path.read_text()
        keep = text[: text.rfind("\n") + 1]
        if keep != text:
            path.write_text(keep)


def write_page(path: Path, bars: list[brokapi.Candle]) -> None:
    """A page goes to the file with one write and is flushed before the next page is asked for."""
    text = "".join(
        f"{b.open_ts.isoformat()},{b.open},{b.high},{b.low},{b.close},{b.volume}\n" for b in bars
    )
    with path.open("a") as file:
        file.write(text)
        file.flush()

Выгрузка

async def download(
    client: brokapi.Client,
    ticker: str,
    timeframe: brokapi.Timeframe,
    start: datetime,
    end: datetime,
    folder: Path,
    *,
    attempts: int = 5,
) -> int:
    """Downloads [start, end) into `<folder>/<ticker>.csv` and returns the bars written in this run."""
    instrument = await client.instrument(ticker)
    path = folder / f"{ticker}.csv"
    written = 0
    stuck = 0
    while True:
        cut_broken_tail(path)
        # Go on after the last bar in the file (nothing is read twice), or from `start` for a new file.
        done = last_bar(path)
        begin = start if done is None else done + timedelta(seconds=timeframe.seconds)
        if begin >= end:
            return written
        pages = client.candle_pages(instrument, timeframe, begin, end)
        try:
            async for page in pages:
                write_page(path, page)
                written += len(page)
                stuck = 0
            return written
        except brokapi.BrokapiError as error:
            if error.error_class is not brokapi.ErrorClass.RETRYABLE:
                raise  # the same read fails again: check the instrument, the timeframe and the period
            stuck += 1
            if stuck >= attempts:
                raise
            # RateLimited or Transport after the reader's own patience: wait and go on from the end of the file.
            wait = error.retry_after.total_seconds() if isinstance(error, brokapi.RateLimited) else 0.5
            await asyncio.sleep(wait)

Ошибки разбираются по классу (error.error_class):

Любое чтение тратит квоту, не только свечи: instrument у Т-Банка, last_trades, подписка. Любое может вернуть RateLimited. Если выгружаете несколько бумаг, делайте это по очереди на один клиент: у брокера один счетчик лимитов на все.

Вся программа

"""A long candle history into files, within the rate limit, that goes on where it stopped.

The code of the page "Как скачать историю свечей" of the Python section of the book. One file per instrument: text,
one line per bar. The file is its own checkpoint: where it ends, the download goes on. The tests run it against the
imitations.
"""

import asyncio
from datetime import datetime, timedelta, timezone
from decimal import Decimal
from pathlib import Path

import brokapi


# ANCHOR: files
def last_bar(path: Path) -> datetime | None:
    """The open time of the last COMPLETE line of the file, or None. A line cut by a crash is ignored."""
    if not path.exists():
        return None
    last = None
    for line in path.read_text().splitlines():
        parts = line.split(",")
        if len(parts) == 6:
            last = datetime.fromisoformat(parts[0])
    return last


def cut_broken_tail(path: Path) -> None:
    """A crash can leave a half line at the end. Cut it off, or the next page would be glued to it."""
    if path.exists():
        text = path.read_text()
        keep = text[: text.rfind("\n") + 1]
        if keep != text:
            path.write_text(keep)


def write_page(path: Path, bars: list[brokapi.Candle]) -> None:
    """A page goes to the file with one write and is flushed before the next page is asked for."""
    text = "".join(
        f"{b.open_ts.isoformat()},{b.open},{b.high},{b.low},{b.close},{b.volume}\n" for b in bars
    )
    with path.open("a") as file:
        file.write(text)
        file.flush()
# ANCHOR_END: files


# ANCHOR: download
async def download(
    client: brokapi.Client,
    ticker: str,
    timeframe: brokapi.Timeframe,
    start: datetime,
    end: datetime,
    folder: Path,
    *,
    attempts: int = 5,
) -> int:
    """Downloads [start, end) into `<folder>/<ticker>.csv` and returns the bars written in this run."""
    instrument = await client.instrument(ticker)
    path = folder / f"{ticker}.csv"
    written = 0
    stuck = 0
    while True:
        cut_broken_tail(path)
        # Go on after the last bar in the file (nothing is read twice), or from `start` for a new file.
        done = last_bar(path)
        begin = start if done is None else done + timedelta(seconds=timeframe.seconds)
        if begin >= end:
            return written
        pages = client.candle_pages(instrument, timeframe, begin, end)
        try:
            async for page in pages:
                write_page(path, page)
                written += len(page)
                stuck = 0
            return written
        except brokapi.BrokapiError as error:
            if error.error_class is not brokapi.ErrorClass.RETRYABLE:
                raise  # the same read fails again: check the instrument, the timeframe and the period
            stuck += 1
            if stuck >= attempts:
                raise
            # RateLimited or Transport after the reader's own patience: wait and go on from the end of the file.
            wait = error.retry_after.total_seconds() if isinstance(error, brokapi.RateLimited) else 0.5
            await asyncio.sleep(wait)
# ANCHOR_END: download


async def main() -> None:
    client = await brokapi.connect("bcs")
    try:
        end = datetime.now(timezone.utc).replace(minute=0, second=0, microsecond=0)
        folder = Path("bars")
        folder.mkdir(exist_ok=True)
        for ticker in ("SBER", "GAZP"):
            count = await download(client, ticker, brokapi.Timeframe.H1, end - timedelta(days=365), end, folder)
            print(f"{ticker}: {count} bars")
    finally:
        await client.close()


if __name__ == "__main__":
    asyncio.run(main())

Как проверить

Для этой команды нужен клон репозитория (git clone https://github.com/runinfra/brokapi, затем pip install brokapi pytest pytest-asyncio): тесты и примеры в пакет pip install brokapi не входят.

cd crates/python
pytest tests/test_examples.py -k history

Тест выгружает 100 дней часовых баров (2400 штук, БКС отдает 1440 за запрос), проверяет, что баров ровно 2400 без пропусков и дублей, что второй запуск ничего не просит у брокера, и что после обрезанного файла с битой строкой выгрузка дописывает ровно недостающее. Пределы брокеров взяты из их документации.

Стоп-заявки, Python

Инструкция. Цель: поставить стоп-заявку, посмотреть, что она ждет, найти ее после потерянного ответа и снять. Что такое стоп-заявка, чем различаются брокеры и почему так, написано в общей части: Стоп-заявки (примеры там на Rust, таблицы и правила одни и те же). Здесь то, что зависит от Python. Код ниже - куски программы stops.py, она запускается тестом против имитаций всех брокеров.

Стоп-заявка лежит у брокера и ждет цены. Пока цена не дошла до заданной, на бирже ее нет. Когда дошла, брокер выставляет обычную заявку, рыночную или лимитную. Она есть у всех брокеров: (await client.caps()).ud.supports_stop_orders.

Методы

Виды (StopOrderKind): STOP_LOSS (защита позиции), TAKE_PROFIT (фиксация прибыли), STOP_LIMIT (как стоп-лосс, но после срабатывания всегда лимитная заявка, limit_price обязателен). Срок (StopExpiry): good_till_cancel(), end_of_day(), good_till_date(момент). Без expiry стоп живет до отмены. Цены и количество - Decimal, float отвергается, как везде. Количество в штуках инструмента, не в лотах.

Поставить

async def protect(
    client: brokapi.Client, instrument: brokapi.InstrumentId, stop_price: Decimal
) -> tuple[uuid.UUID, brokapi.OrderAck]:
    """Puts a stop-loss that sells one lot if the price falls to `stop_price`, at market."""
    params = await client.trading_params(instrument)  # the unit of the quantity is the instrument, not the lot
    cid = brokapi.new_cid()  # made by the bot, and written to its journal BEFORE the call, as for any order
    ack = await client.place_stop(
        cid=cid,
        instrument=instrument,
        side=brokapi.Side.SELL,
        kind=brokapi.StopOrderKind.STOP_LOSS,
        qty=params.lot_size,
        stop_price=stop_price,
        # limit_price=None: a market order at the trigger. expiry=None: until cancelled.
    )
    # Keep ack.broker_id too: after a restart T-Bank cannot find a stop by its cid, only by the id of the broker.
    return cid, ack

Правила те же, что у обычной заявки. cid придумывает бот и записывает в свой журнал до вызова. Он уходит не больше одного раза: повтор с тем же cid вернет Rejected с кодом duplicate_place, второго стопа у брокера не появится. Стопы стоят за тем же шлюзом: до reconcile будет NotReconciled. Проверки без сети (нет цены у стоп-лимита, срок, которого нет у брокера, количество не кратно лоту) библиотека делает сама до отправки, они не тратят квоту и дают Rejected.

Что ждет и что сработало

async def waiting(client: brokapi.Client) -> list[brokapi.StopOrderSnapshot]:
    """The stops that have not triggered yet. This list is the only way to learn that one has: there is no event."""
    return [stop for stop in await client.active_stop_orders() if stop.state.kind is brokapi.StopOrderStateKind.ACTIVE]

reconcile и active_orders стопов не показывают, у них свой список. О срабатывании узнать можно только опросом: события для стопов нет (потока статусов не дает ни один брокер, библиотека сама не опрашивает). Когда стоп сработал, брокер ставит обычную заявку, и ее ведет обычный поток заявок. Связь между стопом и порожденной заявкой библиотека не строит.

Потерянный ответ

Unknown у place_stop значит то же, что у place: стоп мог дойти до брокера. Повторять с тем же cid нельзя, ставить новый стоп наугад тоже: выйдет два. Смотрите в список. Есть три исхода, их возвращает protect_once:

• Нашелся стоп с вашим cid (Placement.stop). Он ваш, ничего больше не делайте. БКС, Финам, АЛОР и Bybit возвращают cid сами, Т-Банк - нет, его коннектор узнает стоп по тому, что вы просили, и по времени (подробности в Т-Банк).
• Нашлись стопы без cid на той же бумаге и в ту же сторону (Placement.unclear). Один из них может быть вашим, сказать наверняка нельзя: у Т-Банка так выглядит и стоп прошлого запуска, и стоп, поставленный вручную. Второй стоп не ставьте. Посмотрите их сами и, если один ваш, дальше работайте с ним по broker_id.
• Ничего нет (оба поля пустые). Стопа у брокера нет, можно вызвать protect_once еще раз: он возьмет новый cid. Рецепт сначала ждет несколько секунд (wait) и смотрит второй раз, потому что медленный брокер принимает стоп с опозданием.

@dataclass(frozen=True)
class Placement:
    """What is known about the stop after `protect_once`. At most one of the two fields is filled."""

    stop: brokapi.StopOrderSnapshot | None = None
    """Our stop is at the broker, found by its `cid`."""
    unclear: tuple[brokapi.StopOrderSnapshot, ...] = ()
    """Stops without a `cid` on the same instrument and side. One of them may be ours, there is no way to tell. Do not
    place another one: a person looks, or the bot takes one of them by its `broker_id` if it knows it is its own."""
    # Both empty: there is no stop at the broker. It is safe to call `protect_once` again (it makes a NEW cid).


async def protect_once(
    client: brokapi.Client,
    instrument: brokapi.InstrumentId,
    stop_price: Decimal,
    wait: float = 5.0,
    *,
    qty: Decimal | None = None,
) -> Placement:
    """Puts the stop; when the answer is lost, looks for it at the broker instead of putting it again.

    `qty` is in units of the instrument; without it the stop covers one lot."""
    cid = brokapi.new_cid()
    side = brokapi.Side.SELL
    try:
        await client.place_stop(
            cid=cid,
            instrument=instrument,
            side=side,
            kind=brokapi.StopOrderKind.STOP_LOSS,
            qty=qty if qty is not None else (await client.trading_params(instrument)).lot_size,
            stop_price=stop_price,
        )
    except brokapi.Rejected:
        return Placement()  # the broker said no: there is no stop
    except (brokapi.Unknown, brokapi.Transport):
        pass  # it may be there. NEVER place again under this cid: look.

    async def look() -> Placement:
        stops = await client.active_stop_orders()
        ours = next((stop for stop in stops if stop.cid == cid), None)
        if ours is not None:
            return Placement(stop=ours)
        unclear = (
            stop
            for stop in stops
            if stop.cid is None and stop.instrument.key == instrument.key and stop.side is side
        )
        return Placement(unclear=tuple(unclear))

    found = await look()
    if found.stop is None and not found.unclear:
        await asyncio.sleep(wait)  # a slow broker takes the stop late: look once more before saying "nothing"
        found = await look()
    return found

Как проверить свой код на этом сбое: mock.lose_stop_answers() у имитации любого брокера. Брокер принимает стоп, а ответ теряется.

Бот со стопом: старт и рестарт

Бот держит позицию под защитой стопа. Бот упал или его перезапустили, пока позиция была открыта, и теперь неизвестно, стоит ли стоп: его могли не успеть поставить, ответ на place_stop мог потеряться, стоп мог сработать или истечь. Позиция без стопа - самое опасное, что остается на счете после рестарта. Поэтому на каждом старте, первом и после рестарта, бот сначала проверяет защиту и только потом торгует:

1. Подписки и reconcile(журнал): стопы стоят за тем же шлюзом, что и заявки.
2. positions() и список ждущих стопов (waiting). Позиции чужие тоже видны (купленные руками), поэтому бот работает только с теми, для которых знает цену стопа.
3. По каждой своей длинной позиции складываются количества стопов на продажу по этому инструменту. Хватает - позиция защищена, второй стоп не ставят. Нет ни одного - ставят стоп на всю позицию. Есть, но на часть - решает человек: остаток бот сам не ставит.
4. Стоп ставит protect_once. Если ответ на place_stop потерялся (Unknown), стоп ищут в active_stop_orders, а не ставят заново: как в разделе «Потерянный ответ» выше. Сверка стопов идет по инструменту и стороне, а не по cid: после рестарта Т-Банк cid стопа не возвращает.
5. Позиции, которые остались без стопа (брокер отказал, стоп не нашелся), функция возвращает списком. Для них бот не открывает новых сделок и сообщает человеку.

async def protect_on_start(
    client: brokapi.Client,
    ledger: Sequence[uuid.UUID],
    stop_price_of: Callable[[brokapi.Position], Decimal | None],
) -> list[brokapi.Position]:
    """Called once, right after the subscriptions, on every start of the bot (the first one and every restart).

    `stop_price_of(position)` is the stop price the bot wants for its own position, or None for a position that is not
    the bot's (the account may hold others, bought by hand): those are left alone.

    Returns the positions that are NOT protected after it. For them the bot does not trade and tells a person."""
    await client.reconcile(ledger)  # the gate of the commands opens; stop orders are behind it too
    unprotected = []
    stops = await waiting(client)  # the stops of every earlier run, whoever put them
    for position in await client.positions():
        stop_price = stop_price_of(position)
        if position.qty <= 0 or stop_price is None:
            continue  # nothing to protect, or not ours (a short position needs a stop on the other side: not in this recipe)
        covered = sum(
            stop.qty
            for stop in stops
            if stop.instrument.key == position.instrument.key and stop.side is brokapi.Side.SELL
        )
        if covered >= position.qty:
            continue  # the stop of the earlier run is there: do not put a second one
        if covered > 0:
            unprotected.append(position)  # a stop for a part: a person decides what to do with the rest
            continue
        # No stop at all. `protect_once` puts it for the whole position. At `Unknown` it looks for the stop at the
        # broker (active_stop_orders) and never sends the same cid again.
        placed = await protect_once(client, position.instrument, stop_price, qty=position.qty)
        if placed.stop is None:
            unprotected.append(position)  # refused, or the stop is not found, or there is one without a cid to look at
    return unprotected

Цену стопа знает бот: он берет ее из своего журнала (цена входа и правило), поэтому она приходит параметром stop_price_of. Для позиции, которая не бота, функция возвращает None, и такую позицию рецепт не трогает. О срабатывании стопа события нет: если позиции или стопа нет на старте, это не ошибка, а возможный результат срабатывания, и бот проверяет это по positions() и по порожденной заявке. Короткие позиции (стоп на покупку) в рецепт не входят.

Снять

async def release(client: brokapi.Client, stop: brokapi.StopOrderSnapshot) -> None:
    """Takes the stop off, by the id of the broker: that works after a restart for every broker."""
    await client.cancel_stop(brokapi.StopOrderRef.broker(stop.broker_id))

Снимать надежнее по номеру брокера (OrderAck.broker_id, StopOrderSnapshot.broker_id): его знают все брокеры и после перезапуска. StopOrderRef.cid(cid) Т-Банк после перезапуска не найдет и вернет Rejected с кодом unknown_stop_order: он не возвращает cid, связь хранится в памяти процесса, который поставил заявку. Повторная отмена ничего не создает. Неизвестный стоп или уже сработавший - Rejected.

Что отличается у брокеров

Подробная таблица на странице Стоп-заявки, коротко:

• Срок. «До отмены» есть у всех (у Bybit только оно). «До конца дня» у Финама и АЛОРа, «до даты» у Т-Банка и АЛОРа (у Финама только для тейк-профита). Чего нет, то Rejected с кодом unsupported_expiry.
• Цена после срабатывания тейк-профита. У Финама нет: Rejected, unsupported_limit_price. У БКС, Т-Банка, АЛОРа и Bybit есть.
• cid в списке. У Т-Банка пока работает процесс, который поставил заявку. После перезапуска StopOrderSnapshot.cid пуст. Исключение - стоп с потерянным ответом: его cid коннектор восстанавливает, если такой стоп один.

Как проверить

Для этих команд нужен клон репозитория: тесты и примеры в пакет pip install brokapi не входят. Версия пакета должна быть той же, что у клона (последний выпуск и его тег).

git clone https://github.com/runinfra/brokapi && cd brokapi
pip install brokapi pytest pytest-asyncio
cd crates/python
pytest tests/test_stops.py tests/test_examples.py tests/test_guides.py

Тесты идут на имитациях всех брокеров: стоп далеко от рынка ждет в списке и снимается, повтор с тем же cid не дублирует, стоп-лимит без цены отвергается до отправки, потерянный ответ ищется в списке (все четыре брокера, и случай, когда рядом стоит такой же стоп без cid). Срабатывание стопа проверено на имитациях БКС и Финама (mock.fill(cid, ...): стоп уходит из списка, заявка исполнена). Имитация Т-Банка срабатывание стопа не умеет: mock.fill для него вернет ValueError, а стоп останется в списке.

Любой метод брокера, Python

Инструкция. Общий интерфейс закрывает то, что умеют все брокеры. Но у каждого брокера есть много своего: купоны и дивиденды, отчеты, избранное, корпоративные действия, свежие методы. Чтобы они не оказались закрыты, у клиента есть await client.raw(...). Он вызывает любой метод API брокера с теми же токеном, адресом и счетчиком лимитов, что у самого клиента. Общая часть, одна для Rust и Python: Любой метод брокера: raw. Там примеры на Rust и правила квоты. Здесь то, как это выглядит в Python. Код ниже - куски программы raw.py, она запускается тестом против имитаций.

reply = await client.raw(method, args=None, *, command=False)   # reply: dict (или list, как ответит брокер)

В Rust метод вызывается замыканием над типизированным клиентом. В Python замыкания нет, поэтому метод называют строкой, а аргументы передают словарем. Ответ приходит словарем.

Как называть метод и что передавать

Т-Банк и Финам говорят по gRPC. Описание всех сервисов и сообщений вшито в библиотеку, метод ищется в нем по имени, словарь становится сообщением запроса, а ответ снова словарем. Поэтому годится любой метод API, в том числе тот, которого нет в общем интерфейсе. Формат как у протокола брокера: 64-разрядные числа записаны строками ("units": "274"), время - строка RFC 3339, деньги Т-Банка - {"units": "274", "nano": 50000000}, число Финама - {"value": "100.05"}. Имена полей в ответе - как в .proto. Лишнее поле в запросе дает ошибку, а не молча пропадает.

БКС говорит по REST. Методы, которые библиотека знает по имени, лежат в таблице (глагол и путь), остальные вызываются как "GET /путь" или "POST /путь". Числа с дробной частью в ответе БКС приходят как Decimal, float в Python не попадает нигде.

async def tbank_prices(client: brokapi.Client) -> dict[str, str]:
    """T-Bank (gRPC): the method is named as in the API description, the arguments are the request message."""
    reply = await client.raw("GetLastPrices", {"instrument_id": ["SBER_TQBR", "GAZP_TQBR"]})
    # int64 is text, money is {"units": "274", "nano": 50000000}: the wire form of the broker.
    return {p["ticker"]: f'{p["price"]["units"]}.{p["price"]["nano"]:09d}' for p in reply["last_prices"]}

async def bcs_quotes(client: brokapi.Client) -> dict[str, Any]:
    """BCS (REST): a name from its rate limit file, `query` for the URL and `body` for the JSON of a POST."""
    reply = await client.raw("GetQuotes", {"body": {"instruments": [{"ticker": "SBER", "classCode": "TQBR"}]}})
    return {record["ticker"]: record["last"] for record in reply["records"]}  # prices are Decimal

async def finam_quote(client: brokapi.Client) -> str:
    """Finam (gRPC): the same as T-Bank. `google.type.Decimal` is {"value": "100.05"}."""
    reply = await client.raw("LastQuote", {"symbol": "SBER@MISX"})
    return reply["quote"]["last"]["value"]

АЛОР говорит по REST, как БКС, но методы называются глаголом и путем из описания API брокера: "GET /md/v2/time". Числа с дробной частью приходят как Decimal. Команде заявки передают request_id: брокер отвечает на повторный идентификатор копией первого ответа и второй заявки не создает (по его документации).

async def alor_summary(client: brokapi.Client) -> Any:
    """ALOR (REST): the verb and the path of the API description. `query` is for the URL, `body` for a POST or PUT."""
    reply = await client.raw("GET /md/v2/Clients/MOEX/D00001/summary")  # your own portfolio in the path
    return reply["portfolioEvaluation"]  # prices are Decimal

В аргументах raw Decimal уходит текстом, UUID текстом, datetime с поясом строкой RFC 3339, float отвергается (TypeError).

Что происходит при вызове

1. Берется квота. Имя метода ищется в файле лимитов брокера. Нет такого имени - тратится общее ведро (маршрут "*"). Бесплатно не уходит ни один вызов. Квоты нет - вызов не отправляется, и это RateLimited с retry_after. Счетчик общий с клиентом и с клиентами на том же limiter=: raw и portfolio() тратят одно ведро, если у них один маршрут.
2. Идет вызов с токеном клиента и его таймаутом.
3. Ошибка брокера переводится в те же исключения, что везде (Ошибки).

async def raw_read(client: brokapi.Client, method: str, args: dict[str, Any], tries: int = 3) -> Any:
    """A read through `raw` spends the same quota as every other call: when it is spent, wait and ask again."""
    for _ in range(tries - 1):
        try:
            return await client.raw(method, args)
        except brokapi.RateLimited as error:
            await asyncio.sleep(error.retry_after.total_seconds())
    return await client.raw(method, args)

Чтение и команда

• command=False (по умолчанию) - для чтения. Сетевой сбой и таймаут - Transport, вызов можно повторить.
• command=True - для всего, что меняет счет. Нет ответа (таймаут, обрыв, ошибка сервера) - Unknown: брокер мог выполнить команду. Библиотека такой вызов не повторяет. Как и place, команда доходит до конца, даже если вы перестали ее ждать (отмена задачи, таймаут).

Если сомневаетесь, меняет ли метод счет, ставьте command=True.

async def raw_command(client: brokapi.Client, method: str, args: dict[str, Any]) -> Any:
    """Anything that changes the account goes with command=True: a lost answer is Unknown and it is never repeated."""
    try:
        return await client.raw(method, args, command=True)
    except brokapi.Unknown:
        raise  # ask the broker what became of it (a report, a list): do not call this again

Чего raw не делает

raw обходит гарантии общего интерфейса.

• Он не знает про заявки клиента. Заявка, поставленная через raw, не ведется коннектором как своя: ни учета «в пути», ни шлюза reconcile, ни проверок (шаг цены, лот, цена у стоп-лимита). Заявки ставьте place и place_stop. Через raw вызывайте то, чего в общем интерфейсе нет.
• Он не добавляет счет в ваш запрос: account_id кладите сами.
• Потоки не отдаются. Метод, который открывает поток (server-streaming), дает Unsupported с capability == "raw_streaming". В Rust квота покрывает открытие, а поток читает ваш код. Python так передать не может. Потоки читайте общим интерфейсом (subscribe_*).
• Неизвестный метод и аргументы, которые не подходят методу, дают Config. Ничего не отправлено, квота не потрачена.
• У БКС и АЛОРа WebSocket-каналы через raw не открываются: это есть в Rust (connect_ws, у АЛОРа еще connect_cws), в Python нет.

Как проверить

Для этой команды нужен клон репозитория (git clone https://github.com/runinfra/brokapi, затем pip install brokapi pytest pytest-asyncio): тесты и примеры в пакет pip install brokapi не входят.

pytest crates/python/tests/test_raw.py

На имитации всех брокеров: чтение возвращает ответ словарем, неизвестный метод и лишнее поле отвергаются без отправки, потоковый метод отвергается, квота тратится общая с интерфейсом и с соседним клиентом на том же limiter, команда с отказом брокера не становится Unknown.

Запись событий и проигрыш, Python

Инструкция. Цель: записать поток событий в файл и проигрывать его из файла столько раз, сколько нужно для разбора, одним и тем же кодом разбора для живого потока и для файла. Формат и правила общие для Rust и Python: файл один и тот же, журнал, записанный в Rust, читается в Python и наоборот (Как собрать исследовательский движок). Код ниже - куски программы record.py, она запускается тестом против имитации БКС.

Модуль называется brokapi.record.

Файл: строка-заголовок {"brokapi_log":1,"envelope_schema":1} и по строке JSON на событие (конверт). Цены, количества и деньги записаны строками, поэтому возвращаются точно (250.25 остается 250.25).

Один разбор на живой поток и на файл

replay отдает Envelope так же, как client.events, поэтому функция разбора читает любой из них.

@dataclass
class Stats:
    kinds: Counter[str] = field(default_factory=Counter)
    traded: Decimal = Decimal(0)  # the sum of price * qty of your fills


async def analyze(events: AsyncIterator[brokapi.Envelope], stop_after: int | None = None) -> Stats:
    """Reads events and counts them. It does not know whether they are live or from a file."""
    stats = Stats()
    async for envelope in events:
        payload = envelope.payload
        stats.kinds[type(payload).__name__] += 1
        if isinstance(payload, brokapi.Execution):
            stats.traded += payload.price * payload.qty
        if stop_after is not None and sum(stats.kinds.values()) >= stop_after:
            break
    return stats

Записать

async def record_run(client: brokapi.Client, path: Path, count: int) -> Stats:
    """The live stream, written to `path` as it is read, and analysed."""
    async with contextlib.aclosing(record.record_events(client.events, path)) as events:
        return await analyze(events, stop_after=count)

record_events пропускает события дальше и перед этим пишет каждое в файл. Каждое событие сбрасывается на диск сразу, поэтому программа, которая остановилась посреди работы (сбой, break), оставляет журнал, полный до последнего прочитанного события. Он записывает то, что прочитал ваш код, то есть поток таким, каким его видел бот. Файл закрывается, когда поток кончился или генератор закрыт (contextlib.aclosing).

Новый файл создается при создании писателя. Если такой файл есть, это LogError (kind == "io"): запись одного запуска не должна молча затираться вторым. Нужно заменить файл - overwrite=True.

Писать можно только конверт, который пришел от коннектора или из журнала: он помнит строку, из которой сделан. Envelope, собранный руками, записать нельзя (TypeError).

Проиграть

async def analyze_file(path: Path) -> Stats:
    """The same analysis over the file. A replay waits for the reader, so nothing is lost."""
    return await analyze(record.replay(path))

Скорость: ReplaySpeed.instant() (насколько быстро читает потребитель, по умолчанию) или ReplaySpeed.paced(factor, max_gap): темп записи, деленный на factor. Темп - разница rx_ts соседних конвертов, пауза не длиннее max_gap, чтобы ночь между двумя сессиями не останавливала проигрыш.

Отличие от живого потока. Проигрыш ждет потребителя, поэтому медленный потребитель замедляет проигрыш и ничего не теряется. Живой коннектор ждать не может и применяет режим подписки. Значит, проигрыш никогда не даст Overflow: код, который разбирает Overflow, нужно проверять отдельно.

Прочитать без asyncio

def sources(path: Path) -> set[str]:
    """Reading a log without asyncio: an iterator of Envelope. A bad line raises brokapi.LogError and ends it."""
    return {envelope.source for envelope in record.EnvelopeReader(path)}

Что файл хранит и чего нет

• Монотонные часы получения (rx_mono в Rust) не хранятся, а в Python их нет совсем. Для порядка и замеров используйте Timestamps.rx_ns и broker_ns.
• Поврежденная строка останавливает чтение: brokapi.LogError с kind == "format" и номером строки (заголовок - строка 1). Пропустить строку молча нельзя. Проигрыш отдает конверты до нее и потом поднимает эту ошибку.
• Файл более новой версии формата или с более новыми конвертами читать нельзя: LogError с kind == "schema" (found, supported). Сбой диска или пути - kind == "io". Текст ошибки побуквенно равен тексту LogError в Rust.
• Это журнал потока, а не каталог: индекса по инструменту и времени нет, фильтруйте при чтении. Для лет данных нужен каталог (в Rust-части страницы есть сравнение с NautilusTrader).

Как проверить

Для этой команды нужен клон репозитория (git clone https://github.com/runinfra/brokapi, затем pip install brokapi pytest pytest-asyncio): тесты и примеры в пакет pip install brokapi не входят.

pytest crates/python/tests/test_record.py

Главная проверка: записанные события, прочитанные из файла и проигранные из файла, дают ту же последовательность, что видел бот, на имитациях всех трех брокеров. Еще проверено: журнал в формате Rust читается и записывается обратно байт в байт, поврежденная строка и новая версия отвергаются с номером строки, второй запуск не затирает первый журнал, медленный читатель проигрыша ничего не теряет.

Как тестировать код против имитаций брокеров (Python)

Инструкция. Цель: проверить своего бота без брокера, сети и денег. В пакете есть модуль brokapi.testing с имитациями брокеров. Каждый пример этой книги идет именно на них.

Имитацию можно запустить и обычным скриптом через asyncio.run, не только тестом: так начинается Быстрый старт.

Что такое имитация

Это настоящий сервер на 127.0.0.1 со случайным портом, который говорит на протоколе брокера: HTTP и WebSocket у БКС, gRPC у Т-Банка и Финама. Клиент brokapi.Client подключается к нему так же, как к брокеру, поэтому тест идет по тому же коду, что и боевой запуск, а не по подмене. Сервер хранит состояние: поставленные заявки видны в active_orders, снимаются, исполняются.