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
Перенести бота с `tinkoff-investments` (или с QUIK)	Если вы пришли с tinkoff-investments
Написать торгового бота на событиях	Торговый бот на событиях, Python
Держать несколько брокеров и счетов в одном процессе	Несколько брокеров и счетов
Выгрузить длинную историю свечей	История свечей
Поставить стоп-заявку, найти ее и снять. Проверить стоп после рестарта	Стоп-заявки, Python
Остановить бота и знать, что останется на счете	Аварийная остановка бота
Вызвать метод брокера, которого нет в общем интерфейсе	Любой метод брокера, Python
Записать поток событий в файл и проиграть его из файла	Запись событий и проигрыш, Python
Проверить свой код без сети и денег	Тесты против имитаций, Python
Подключить бота к гейтвею вместо брокера	Подключить бота: Python
Понять, как Python связан с ядром, и чем отличается от Rust	Как это устроено
Найти класс, метод или поле до последней подробности	Справочник API: Python

Что умеет первая версия

Возможность	Как в Python
Подключиться к БКС, Т-Банку, Финаму, АЛОРу, Bybit	`await brokapi.connect("bcs")`, настройки из переменных окружения или аргументами
Подключиться через гейтвей	`await brokapi.connect_gateway("bcs-main", bot="my-bot")`: тот же `Client`, остальной код бота не меняется
Стакан, сделки рынка, котировки, свечи	`order_book`, `last_trades`, `candles`, подписки `subscribe_*`, история по окнам `candle_pages`
Свои заявки и исполнения	`subscribe_order_state`, `subscribe_executions`, `executions`
Заявки	`reconcile`, `place`, `cancel`, `replace` (где брокер умеет), `order_state`, `active_orders`
Стоп-заявки	`place_stop`, `cancel_stop`, `active_stop_orders`, `subscribe_stop_orders` (потока статусов нет ни у кого: `Unsupported`)
Любой метод API брокера	`await client.raw("GetLastPrices", {...})`: имя метода и словарь, ответ словарем, квота общая с клиентом
Запись и проигрыш событий	`brokapi.record`: `EnvelopeWriter`, `EnvelopeReader`, `replay`. Файл тот же, что у Rust
Справочник, лот, шаг цены, статус торгов, расписание	`instrument`, `find`, `trading_params`, `trading_status`, `schedule`
Портфель	`portfolio`, `positions`, `balances`, подписка `subscribe_portfolio`
События	`async for envelope in client.events`, один поток на клиента, `brokapi.merge` для нескольких
Ошибки	исключения с теми же именами и текстом, что у `Error` в Rust: `Unknown`, `Rejected`, `RateLimited`, `NotReconciled`, `Degraded` и другие
Тесты	`brokapi.testing.mock_bcs()`, `mock_tbank()`, `mock_finam()`, `mock_alor()`: имитации брокеров, на них идет каждый пример книги

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).

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