# brokapi

> brokapi - единый интерфейс к торговым API: один и тот же код бота работает с любым брокером. Начинаем с API брокеров российского рынка (БКС, Т-Банк, Финам, АЛОР) и технический коннектор к API Bybit, дальше другие брокеры и биржевые протоколы. Писать можно на Rust (ядро) или на Python (пакет brokapi, тонкая обертка над ядром): рыночные данные, заявки, сверка со счетом, лимиты запросов. Третий путь - Gateway, программа brokapi: служба держит связь со счетами за все боты (gRPC для любого языка, один счетчик лимитов), команды ею управляют и читают счет (вывод --json). Стадия: открытая альфа. Bybit проверен вживую, БКС, Т-Банк, Финам и АЛОР проверены только на имитациях, на настоящих счетах не запускались: для боевого счета сначала прочитайте before-live.md и agents/unverified.md. Правило 0: боевой токен выдает человек, первую боевую заявку ставят только с его слова (agent-contract.md). Документация: https://brokapi.ru/docs/

Как пользоваться этим набором. Книга написана по задачам и состоит из общей части (как устроено, брокеры, ошибки, события, контракт для агентов) и разделов продуктов: Rust, Python, Gateway (программа brokapi: служба и команды). Писать код можно на Rust или на Python, оба работают сейчас (альфа); Gateway - программа brokapi, раздел gateway/. Если пользователь пишет на Python, берите отдельный индекс для Python: https://brokapi.ru/docs/python/llms.txt, в нем только то, что нужно для Python, и справочник пакета одним файлом. Если боты на нескольких языках или несколько ботов на одном счете, берите Gateway: он запускается командами brokapi (gateway/quickstart.md), бот подключается к нему по gRPC (gateway/bots.md): для Rust есть клиент RemoteClient, для Python бот берет тот же brokapi.Client через brokapi.connect_gateway (gateway/bots.md), для Go готового клиента пока нет, контракт - файлы .proto (api-gateway.md). Если код пойдет на боевой счет, сначала before-live.md и agents/unverified.md (допущения по документации брокеров, как их обойти). Если нужно написать код: прочитайте "Контракт для агентов" (все обязательные правила на одной странице, они одни для любого языка), затем инструкцию из раздела нужного языка, ближайшую к задаче (торговый бот, несколько брокеров и счетов, история или исследовательский движок), и копируйте код оттуда: каждый пример - рабочий тест против имитаций. Общие страницы (круги механики, заявки, сверка) показывают код вкладками Rust и Python. Точные объявления типов и сигнатуры методов - в api-reference.md (Rust, из rustdoc) и python/api-reference.md (Python, из docstring), а также в самих справочниках. Весь текст книги одним файлом: llms-full.txt. У каждой страницы есть markdown-исходник рядом с HTML (замените .html на .md). Все адреса ниже - на https://brokapi.ru/docs/, справочник API Rust - на https://brokapi.ru/docs/api/, справочник Python - на https://brokapi.ru/docs/api/python/.

## Начало

- [Что это](https://brokapi.ru/docs/index.md): Что такое brokapi, выбор пути (Rust, Python, Gateway) и статус каждого, три главных правила

## Начать

- [Установка](https://brokapi.ru/docs/install.md): Установка: cargo add brokapi и pip install brokapi, самая свежая версия из репозитория, проверка и частые ошибки
- [Перед боевым счетом](https://brokapi.ru/docs/before-live.md): Перед боевым счетом: правило 0 (токен и первая боевая заявка только от человека), с чего начать на настоящем счете, песочницы, первая заявка
- [Аварийная остановка бота](https://brokapi.ru/docs/emergency-stop.md): Аварийная остановка бота: что делает close(), что делает brokapi cancel-all (снимает и защитные стопы), как снять только заявки бота и оставить позицию защищенной

## Как устроено

- [Карта: сущности и три круга](https://brokapi.ru/docs/architecture.md): Карта: коннекторы MD и UD, счетчик лимитов, канал событий и три круга механики со схемами
- [Круг событий: подписки, буферы, обрывы](https://brokapi.ru/docs/streams.md): Круг событий: подписки, режимы буфера (Conflate, DropNewest, Lossless), Overflow, Resync, обрывы
- [Круг команд: заявки](https://brokapi.ru/docs/orders.md): Круг команд: cid, порядок проверок place, исходы команды, почему нет автоповтора, машина состояний заявки
- [Круг жизни: шлюз и сверка](https://brokapi.ru/docs/reconcile.md): Круг жизни: шлюз торговых команд и сверка reconcile, три списка отчета, что хранит бот
- [Лимиты запросов](https://brokapi.ru/docs/limits.md): Лимиты запросов: BrokerLimiter, ведра, RateLimited, почему отмена в отдельном ведре
- [Деньги, цены и количества](https://brokapi.ru/docs/numbers.md): Price, Qty, Money на Decimal, округление до шага цены, PriceGrid, перевод форматов брокеров

## Брокеры

- [Брокеры](https://brokapi.ru/docs/brokers/README.md): Сравнение брокеров: идентификаторы инструментов, единицы, особенности
- [БКС](https://brokapi.ru/docs/brokers/bcs.md): БКС: токены, идентификаторы, единицы количества, ограничения
- [Т-Банк](https://brokapi.ru/docs/brokers/tbank.md): Т-Банк: песочница, счета, лоты, uid инструмента, ограничения
- [Финам](https://brokapi.ru/docs/brokers/finam.md): Финам: секрет и JWT, где взять секрет и счет, первый день без песочницы, символ SBER@MISX, количество в штуках, нет replace
- [АЛОР](https://brokapi.ru/docs/brokers/alor.md): АЛОР: refresh-токен, портфель и биржа, тикер и режим торгов, лоты и штуки, X-REQID и cid, нет расписания
- [Bybit](https://brokapi.ru/docs/brokers/bybit.md): Bybit: подключение к API: ключ и секрет, демо-счет, категория linear (спота нет), BTCUSDT@linear, количество в базовой монете, нет replace, стоп-заявки, что проверено вживую и что нет

## Rust

- [brokapi на Rust](https://brokapi.ru/docs/rust/index.md): Раздел Rust (работает сейчас, альфа): как подключить крейт и таблица инструкций по задачам
- [Быстрый старт на Rust](https://brokapi.ru/docs/rust/quickstart.md): Rust: от нуля до первой заявки на БКС, Т-Банке, Финаме, АЛОРе и Bybit: подключение, сверка, подписки, заявка, отмена
- [Торговый бот на событиях, Rust](https://brokapi.ru/docs/rust/howto-trading-bot.md): Rust: как написать торгового бота на событиях: стакан, сигнал, заявка, статусы, выход из Unknown, остановка
- [Несколько брокеров и счетов: инфраструктура, Rust](https://brokapi.ru/docs/rust/howto-infrastructure.md): Rust: как собрать один процесс на несколько брокеров и счетов: журнал заявок в файле, рестарт со сверкой
- [Исследовательский движок](https://brokapi.ru/docs/rust/howto-research.md): Rust: как собрать исследовательский движок: выгрузка длинной истории свечей по лимитам, запись и воспроизведение событий
- [Запуск, рестарт и остановка бота](https://brokapi.ru/docs/rust/lifecycle.md): Rust: как запустить, перезапустить и остановить бота: порядок start, подписка, reconcile, shutdown
- [Если что-то пошло не так](https://brokapi.ru/docs/rust/recovery.md): Rust: что делать при Unknown, Overflow, Degraded и долгом обрыве связи, с кодом
- [Несколько счетов и брокеров](https://brokapi.ru/docs/rust/accounts.md): Rust: несколько счетов и брокеров: UD на счет, MD на брокера, один счетчик лимитов на область квоты
- [Стоп-заявки](https://brokapi.ru/docs/rust/stop-orders.md): Rust: стоп-лосс, тейк-профит и стоп-лимит: place_stop, cancel_stop, active_stop_orders
- [Любой метод брокера: raw](https://brokapi.ru/docs/rust/raw.md): Rust: любой метод брокера через raw(): те же токен, адрес и счетчик лимитов
- [Тесты против имитаций, Rust](https://brokapi.ru/docs/rust/mocks.md): Rust: как тестировать код против имитаций брокеров brokapi-mocks: запуск, настройка, подтверждение исхода

## Python

- [brokapi для Python](https://brokapi.ru/docs/python/index.md): Раздел Python (работает, альфа): как поставить пакет, таблица инструкций, что умеет первая версия, чего нет
- [Быстрый старт на Python](https://brokapi.ru/docs/python/quickstart.md): Python: от нуля до первой заявки: имитация без токена и денег (mock_tbank), песочница Т-Банка, потом боевой счет (БКС, Т-Банк, Финам, АЛОР, Bybit): connect, чтение, reconcile, place, cancel, close
- [Если вы пришли с tinkoff-investments](https://brokapi.ru/docs/python/from-tinkoff-investments.md): Python: переезд с tinkoff-investments: таблица соответствий (лоты и штуки, uid, cid, один поток событий, обязательный reconcile, Quotation и Decimal, стоп-заявки), абзац про QUIK
- [Торговый бот на событиях, Python](https://brokapi.ru/docs/python/howto-trading-bot.md): Python: как написать торгового бота на событиях: журнал, сверка, исходы place, Unknown, Overflow, остановка
- [Несколько брокеров и счетов, Python](https://brokapi.ru/docs/python/howto-infrastructure.md): Python: несколько брокеров и счетов в одном процессе: общий limiter, merge событий, журнал в файле, рестарт со сверкой
- [История свечей](https://brokapi.ru/docs/python/howto-history.md): Python: выгрузка длинной истории свечей в файлы по лимитам брокера с продолжением после сбоя (candle_pages)
- [Стоп-заявки, Python](https://brokapi.ru/docs/python/stop-orders.md): Python: стоп-заявки (place_stop, cancel_stop, active_stop_orders), потерянный ответ Unknown, рецепт «бот со стопом: старт и рестарт», различия брокеров
- [Любой метод брокера, Python](https://brokapi.ru/docs/python/raw.md): Python: любой метод API брокера через client.raw(имя, словарь): Т-Банк и Финам по имени из .proto, БКС по таблице или пути, квота, command=True, чего raw не делает
- [Запись событий и проигрыш, Python](https://brokapi.ru/docs/python/record.md): Python: запись потока событий в файл и проигрыш (brokapi.record: EnvelopeWriter, EnvelopeReader, replay, LogError), формат файла как у Rust
- [Тесты против имитаций, Python](https://brokapi.ru/docs/python/testing.md): Python: тесты против имитаций brokapi.testing (mock_bcs, mock_tbank, mock_finam, mock_alor), fill, ожидание событий без sleep
- [Как Python связан с ядром](https://brokapi.ru/docs/python/design.md): Объяснение: как пакет Python связан с ядром, мост tokio и asyncio, Decimal, ошибки, отличия от Rust

## Gateway

- [Gateway](https://brokapi.ru/docs/gateway/index.md): Gateway, программа brokapi (служба и команды, один продукт): когда нужен, схема служба - гейтвеи - боты - брокеры, что гарантирует, чего пока нет
- [Быстрый старт: служба brokapi](https://brokapi.ru/docs/gateway/quickstart.md): Gateway: быстрый старт на песочнице Т-Банка: brokapi init, check, up -d, ps, quote, down, без заявок
- [Подключить бота](https://brokapi.ru/docs/gateway/bots.md): Gateway: подключить бота: доступ (gateway.addr, access.key, заголовки authorization и x-brokapi-bot), Rust через RemoteClient, любой язык по .proto, ошибки
- [Запуск и обслуживание](https://brokapi.ru/docs/gateway/operations.md): Gateway: запуск и обслуживание: юнит systemd, несколько служб, сбои и перезапуск, остановка и снятие заявок, файлы состояния, что значат сообщения
- [События и сверка после перезапуска](https://brokapi.ru/docs/gateway/events.md): Gateway: поток событий Events (epoch, seq, Ready, Gap, Lagged), кольцо, что бот делает после обрыва и перезапуска гейтвея, сверка
- [Чем гейтвей отличается от прямого подключения](https://brokapi.ru/docs/gateway/differences.md): Gateway: чем гейтвей отличается от прямого подключения (потерянный ответ, события, подписки, лимиты, остановка) и чего он пока не делает
- [Конфиг brokapi.toml](https://brokapi.ru/docs/gateway/config.md): Справочник конфига brokapi.toml: state_dir, [service], [service.restart], [[gateway]], токены, кольцо событий, ведра лимитов
- [Команды brokapi](https://brokapi.ru/docs/gateway/commands.md): Справочник команд brokapi (init, check, up, down, ps, top, status, start, stop, restart, add, remove, reload, logs, portfolio, orders, book, quote, direct, cancel-all, gateway run), коды выхода, --help каждой

## Справочник

- [Контракт для агентов](https://brokapi.ru/docs/agent-contract.md): Контракт для агентов: обязательные правила с причинами, последствиями и кодом, частые ошибки
- [Ошибки и что с ними делать](https://brokapi.ru/docs/errors.md): Ошибки и состояния: что значат, почему бывают, что делать (Unknown, Rejected, RateLimited, Degraded...)
- [События и возможности](https://brokapi.ru/docs/events.md): Конверт Envelope, события Event, возможности коннекторов caps()
- [Покрытие API](https://brokapi.ru/docs/coverage.md): Какие методы API каждого брокера закрыты общим интерфейсом, а какие только через raw()
- [Справочник Rust](https://brokapi.ru/docs/api.md): Справочник API Rust (rustdoc): список крейтов и ссылки на страницы справочника
- [Справочник Python](https://brokapi.ru/docs/api-python.md): Справочник API Python (pdoc, из docstring): модули brokapi, models, errors, numbers, record, testing и ссылки на страницы справочника
- [Gateway (gRPC)](https://brokapi.ru/docs/api-gateway.md): Справочник gRPC-интерфейса Gateway (из .proto): сервисы Gateway и Service, все вызовы, сообщения, перечисления

## Версии

- [Изменения](https://brokapi.ru/docs/changelog.md): Журнал изменений по выпускам, в том числе программа brokapi (Gateway)

## Для агентов (страница не в меню книги)

- [Допущения по документации брокеров](https://brokapi.ru/docs/agents/unverified.md): Допущения по документации брокеров, которые не проверены на настоящих счетах, и как подстраховаться в коде (для боевого счета)

## Справочник API (rustdoc, английский)

- [api-reference.md](https://brokapi.ru/docs/api-reference.md): справочник API одним markdown-файлом: объявления типов, поля, варианты, методы трейтов с разделами Errors и Contract (без примеров кода)
- [brokapi](https://brokapi.ru/docs/api/brokapi/index.html): Главный крейт: все под одним именем, брокеры включаются флагами bcs, tbank, finam, alor, bybit
- [brokapi_core](https://brokapi.ru/docs/api/brokapi_core/index.html): Типы, трейты возможностей (OrderExecutor, OrderBookSource...), события, ошибки. С него начинать
- [brokapi_runtime](https://brokapi.ru/docs/api/brokapi_runtime/index.html): Лимиты (BrokerLimiter), PriceGrid, history (CandlePages), record (запись и воспроизведение событий)
- [brokapi_bcs](https://brokapi.ru/docs/api/brokapi_bcs/index.html): Коннекторы БКС и их настройка
- [brokapi_tbank](https://brokapi.ru/docs/api/brokapi_tbank/index.html): Коннекторы Т-Банка и их настройка
- [brokapi_finam](https://brokapi.ru/docs/api/brokapi_finam/index.html): Коннекторы Финама и их настройка
- [brokapi_alor](https://brokapi.ru/docs/api/brokapi_alor/index.html): Коннекторы АЛОРа и их настройка
- [brokapi_bybit](https://brokapi.ru/docs/api/brokapi_bybit/index.html): Коннекторы Bybit и их настройка

- [python/api-reference.md](https://brokapi.ru/docs/python/api-reference.md): справочник API пакета Python одним markdown-файлом: сигнатуры и описания классов, методов, ошибок
- [brokapi (Python)](https://brokapi.ru/docs/api/python/brokapi.html): справочник пакета для Python в HTML (pdoc)

## Optional

- [llms-full.txt](https://brokapi.ru/docs/llms-full.txt): вся книга одним markdown-файлом