TKSBrokerAPI is the trading platform for automation and simplifying the implementation of trading scenarios, as well as working with Tinkoff Invest API server via the REST protocol. The TKSBrokerAPI platform may be used in two ways: from the console, it has a rich keys and commands, or you can use it as Python module. Developers blog (ru):
TKSBrokerAPI — платформа для автоматизации торговли на бирже
Нечёткие технологии
Технологии · Знания · Наука
TKSBrokerAPI — это платформа для упрощения автоматизации торговых сценариев на Python и работы с Tinkoff Invest API сервером через REST-протокол. Платформа TKSBrokerAPI может использоваться в двух вариантах: из консоли (она имеет богатый набор ключей и команд) или её можно использовать как обычный Python модуль через python import. TKSBrokerAPI помогает автоматизировать рутинные торговые операции и реализовать торговые сценарии, или упростить получение необходимой для аналитики информации с сервера брокера. Платформа достаточно легко интегрируется в различные CI/CD конвейеры.
Статус сборок и деплоя CI/CD
| Branch | Status | |---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | master | 
| | develop | 
|
❗ Если вам не хватает возможностей платформы или какого-либо примера в документации, для лучшего понимания работы платформы TKSBrokerAPI (в консоли или как Python API), то опишите ваш случай в разделе 👉 Issues 👈, пожалуйста. По мере возможности постараемся реализовать нужную функциональность и добавить примеры в очередном релизе.
Полезные ссылки
* ⚙ Автоматическая API-документация на английском для модуля TKSBrokerAPI (API documentation here) * 🇺🇸 Релиз-ноты на английском * 🇷🇺 Релиз-ноты на русском * 💡 Все запланированные релизы и вошедшие в них фичи * 📂 Все открытые задачи в беклоге- 🎁 Поддержать проект донатом на ЮМани-кошелёк: 410015019068268
Введение
Если вы занимаетесь одновременно инвестированием, автоматизацией и алгоритмической торговлей, то наверняка слышали про Tinkoff Open API (к нему есть неплохая Swagger-документация) — это API, предоставляемое брокером Тинькофф Инвестиции для автоматизации работы биржевых торговых роботов. Если ещё не слышали, то можете завести себе аккаунт по ссылке и протестировать его возможности сами.
При работе с любыми API, всегда возникают технические трудности: высокий порог вхождения, необходимость в изучении документации, написание и отладка кода для выполнения сетевых запросов по формату API. Пройдёт много времени, прежде чем у вас дойдёт дело до реализации торгового алгоритма.
Платформа TKSBrokerAPI — это более простой инструмент, который можно использовать как обычный Python модуль или запускать из командной строки, и сразу из коробки получить возможность работать со счётом у брокера Тинькофф Инвестиции: получать информацию о состоянии портфеля, включая элементарную аналитику, открывать и закрывать позиции, получать общую информацию о торгуемых на бирже инструментах, запрашивать цены и получать отчёты об операциях за указанный период. Все данные выводятся сразу в консоль: в текстовом виде или сохраняются в файлах формата Markdown.
Пример запроса клиентского портфеля и вывод информации в консоль
$ tksbrokerapi --overview
TKSBrokerAPI.py L:1821 INFO [2022-08-10 22:06:27,150] Statistics of client's portfolio:
Client's portfolio
- Actual date: [2022-08-10 19:06:27] (UTC)
Account ID: [*]
- Portfolio cost: 405705.77 RUB
- Changes: +2098.76 RUB (+0.52%)
Open positions
| Ticker [FIGI] | Volume (blocked) | Lots | Curr. price | Avg. price | Current volume cost | Profit (%) |-----------------------------|---------------------------------|----------|--------------|--------------|---------------------|---------------------- | Ruble | 5.62 (0.00) rub | | | | | | | | | | | | | Currencies: | | | | | 13886.03 RUB | | EURRUB_TOM [BBG0013HJJ31] | 5.29 (0.00) eur | 0.0053 | 62.75 rub | 61.41 rub | 331.96 rub | +7.10 rub (+2.19%) | CNYRUB_TOM [BBG0013HRTL0] | 928.93 (0.00) cny | 0.9289 | 9.09 rub | 8.95 rub | 8443.97 rub | +134.69 rub (+1.62%) | CHFRUB_TOM [BBG0013HQ5K4] | 1.00 (0.00) chf | 0.0010 | 60.54 rub | 64.00 rub | 60.54 rub | -3.46 rub (-5.41%) | GBPRUB_TOM [BBG0013HQ5F0] | 10.00 (0.00) gbp | 0.0100 | 74.39 rub | 75.88 rub | 743.85 rub | -14.94 rub (-1.97%) | TRYRUB_TOM [BBG0013J12N1] | 100.00 (0.00) try | 0.1000 | 3.42 rub | 3.41 rub | 342.00 rub | +0.65 rub (+0.19%) | USD000UTSTOM [BBG0013HGFT4] | 34.42 (0.05) usd | 0.0344 | 60.66 rub | 60.33 rub | 2088.09 rub | +11.44 rub (+0.55%) | HKDRUB_TOM [BBG0013HSW87] | 237.75 (0.00) hkd | 0.2378 | 7.89 rub | 7.83 rub | 1875.61 rub | +14.27 rub (+0.77%) | | | | | | | | Shares: | | | | | 199987.52 RUB | | POSI [TCS00A103X66] | 3 (0) | 3 | 1161.80 rub | 1120.20 rub | 3485.40 rub | +124.60 rub (+3.71%) | 288 [BBG00699M8Q7] | 800 (0) | 8 | 5.53 hkd | 5.69 hkd | 4424.00 hkd | -128.00 hkd (-2.81%) | YNDX [BBG006L8G4H1] | 4 (0) | 4 | 1971.80 rub | 1958.80 rub | 7887.20 rub | +52.22 rub (+0.67%) | IBM [BBG000BLNNH6] | 1 (1) | 1 | 131.03 usd | 131.13 usd | 131.03 usd | -0.10 usd (-0.08%) | 1810 [BBG00KVTBY91] | 1100 (0) | 11 | 11.79 hkd | 11.76 hkd | 12969.00 hkd | +30.00 hkd (+0.23%) | 9988 [BBG006G2JVL2] | 60 (0) | 6 | 91.80 hkd | 91.05 hkd | 5508.00 hkd | +45.50 hkd (+0.83%) | | | | | | | | Bonds: | | | | | 56240.33 RUB | | RU000A105104 [TCS00A105104] | 5 (0) | 5 | 1012.00 cny | 1013.00 cny | 5064.80 cny | -5.00 cny (-0.10%) | RU000A101YV8 [TCS00A101YV8] | 10 (0) | 10 | 1015.40 rub | 1011.21 rub | 10201.30 rub | +41.90 rub (+0.41%) | | | | | | | | Etfs: | | | | | 135586.27 RUB | | TGLD [BBG222222222] | 30000 (0) | 300 | 0.07 usd | 0.07 usd | 2235.00 usd | -3.39 usd (-0.15%) | | | | | | | | Futures: no trades | | | | | |
Opened pending limit-orders: 1
| Ticker [FIGI] | Order ID | Lots (exec.) | Current price (% delta) | Target price | Action | Type | Create date (UTC) |-----------------------------|----------------|--------------|-------------------------|---------------|-----------|-----------|--------------------- | IBM [BBG000BLNNH6] | | 1 (0) | 131.02 usd (-4.36%) | 137.00 usd | ↓ Sell | Limit | 2022-08-10 22:02:44
Opened stop-orders: 3
| Ticker [FIGI] | Stop order ID | Lots | Current price (% delta) | Target price | Limit price | Action | Type | Expire type | Create date (UTC) | Expiration (UTC) |-----------------------------|--------------------------------------|--------|-------------------------|---------------|---------------|-----------|-------------|--------------|---------------------|--------------------- | 1810 [BBG00KVTBY91] | ----** | 11 | N/A hkd (0.00%) | 14.00 hkd | Market | ↓ Sell | Take profit | Until cancel | 2022-08-10 11:24:57 | Undefined | 288 [BBG00699M8Q7] | ----** | 8 | N/A hkd (0.00%) | 5.80 hkd | Market | ↓ Sell | Take profit | Until cancel | 2022-08-10 11:06:28 | Undefined | IBM [BBG000BLNNH6] | ----** | 1 | 130.99 usd (-4.49%) | 137.15 usd | Market | ↓ Sell | Take profit | Until cancel | 2022-08-10 19:02:21 | Undefined
Analytics
- Current total portfolio cost: 405705.77 RUB
- Changes: +2098.76 RUB (+0.52%)
Portfolio distribution by assets
| Type | Uniques | Percent | Current cost |------------|---------|---------|----------------- | Ruble | 1 | 0.00% | 5.62 rub | Currencies | 7 | 3.42% | 13886.03 rub | Shares | 6 | 49.29% | 199987.52 rub | Bonds | 2 | 13.86% | 56240.33 rub | Etfs | 1 | 33.42% | 135586.27 rub
Portfolio distribution by companies
| Company | Percent | Current cost |---------------------------------------------|---------|----------------- | All money cash | 3.42% | 13891.65 rub | [POSI] Positive Technologies | 0.86% | 3485.40 rub | [288] WH Group | 8.60% | 34900.94 rub | [YNDX] Yandex | 1.94% | 7887.20 rub | [IBM] IBM | 1.96% | 7948.93 rub | [1810] Xiaomi | 25.22% | 102312.44 rub | [9988] Alibaba | 10.71% | 43452.61 rub | [RU000A105104] РУСАЛ выпуск 5 | 11.35% | 46039.03 rub | [RU000A101YV8] Позитив Текнолоджиз выпуск 1 | 2.51% | 10201.30 rub | [TGLD] Тинькофф Золото | 33.42% | 135586.28 rub
Portfolio distribution by sectors
| Sector | Percent | Current cost |----------------|---------|----------------- | All money cash | 3.42% | 13891.65 rub | it | 30.55% | 123948.08 rub | consumer | 19.31% | 78353.55 rub | telecom | 1.94% | 7887.20 rub | materials | 11.35% | 46039.03 rub | other | 33.42% | 135586.28 rub
Portfolio distribution by currencies
| Instruments currencies | Percent | Current cost |--------------------------|---------|----------------- | [rub] Российский рубль | 5.32% | 21579.52 rub | [hkd] Гонконгский доллар | 44.99% | 182541.60 rub | [usd] Доллар США | 35.89% | 145623.30 rub | [cny] Юань | 13.43% | 54483.01 rub | [eur] Евро | 0.08% | 331.96 rub | [chf] Швейцарский франк | 0.01% | 60.54 rub | [gbp] Фунт стерлингов | 0.18% | 743.85 rub | [try] Турецкая лира | 0.08% | 342.00 rub
Portfolio distribution by countries
| Assets by country | Percent | Current cost |------------------------------------|---------|----------------- | All other countries | 36.84% | 149472.30 rub | [RU] Российская Федерация | 16.67% | 67612.93 rub | [CN] Китайская Народная Республика | 44.53% | 180665.99 rub | [US] Соединенные Штаты Америки | 1.96% | 7948.93 rub
TKSBrokerAPI.py L:1827 INFO [2022-08-10 22:06:27,153] Client's portfolio is saved to file: [overview.md]
Платформа TKSBrokerAPI позволяет автоматизировать рутинные торговые операции и реализовать ваши торговые сценарии, либо только получать нужную информацию от брокера. Благодаря богатой системе консольных команд её достаточно просто встроить в системы автоматизации CI/CD.
В будущем, на основе этой платформы, в опенсорс будут выложены готовые торговые сценарии и шаблоны для написания собственных сценариев на языке Python.
Основные возможности
На момент последнего релиза инструмент TKSBrokerAPI умеет:
- Скачивать с сервера брокера исторические данные в ценовой модели OHLCV (доступны интервалы:
1min,5min,15min,hourиdayза любой период времени, начиная с1970-01-01);
--history и дополнительные ключи: --interval, --only-missing и --csv-sep;
- API-метод: History().
- Параллельно скачивать историю тикеров по крону с сохранением в отдельные CSV-файлы (с аналогичными опциями как выше);
--history-auto-updater и дополнительные ключи: --crontab, --date-start, --wait-after-iteration и --wait-next;
- API-метод: HistoryAutoUpdater().
- Кэшировать по умолчанию все данные по всем торгуемым инструментам в файл
dump.jsonи использовать его в дальнейшем, что позволяет уменьшить число обращений на сервер брокера;
--no-cache отменяет использование локального кэша, данные запрашиваются с сервера при каждом запуске;
- API-метод: DumpInstruments().
- Получать с сервера брокера список всех доступных для указанного аккаунта инструментов: валют, акций, облигаций, фондов и фьючерсов, в табличном виде в формате Markdown (человеко-читаемая таблица) или в формате XLSX, для дальнейшего использования датасайнтистами или биржевыми аналитиками;
--list или -l для Markdown-файла, ключ --list-xlsx или -x для XLSX-файла;
- API-методы: Listing() и DumpInstrumentsAsXLSX().
- Выполнять поиск инструментов, указав только часть их имени, тикера или FIGI идентификатора, либо задав регулярное выражение;
--search или -s;
- API-метод: SearchInstruments().
- Запрашивать у брокера информацию об инструменте, зная его тикер или идентификатор FIGI;
--info или -i;
- API-методы: SearchByTicker(), SearchByFIGI() и ShowInstrumentInfo().
- Запрашивать у брокера стакан актуальных биржевых цен для указанного по тикеру или FIGI инструмента, при этом можно указать глубину стакана;
--price совместно с ключом --depth;
- API-метод: GetCurrentPrices().
- Получать с сервера брокера таблицу последних цен;
--prices с перечислением списка интересующих инструментов;
- API-метод: GetListOfPrices().
- Получать информацию о состоянии портфеля пользователя и аналитику по нему: распределение портфеля по активам, компаниям, секторам, валютам и странам активов;
--overview или -o;
- API-метод: Overview().
- Получать с сервера брокера информацию о совершённых сделках за указанный период и представлять её в табличном виде;
--deals или -d;
- API-метод: Deals().
- Совершать сделки по рынку, покупая или продавая активы в стакане, удовлетворяя имеющиеся заявки от продавцов или покупателей;
--trade и дополнительные ключи: --buy, --sell;
- API-методы: Trade(), Buy() и Sell().
- Открывать ордера любого типа: отложенные лимитные, действующие в пределах одной торговой сессии, и стоп-ордера, которые могут действовать до отмены или до указанной даты;
--order и дополнительные ключи: --buy-limit, --sell-limit, --buy-stop, --sell-stop;
- API-методы: Order(), BuyLimit(), SellLimit(), BuyStop() и SellStop().
- Закрывать открытые ранее ордера или списки ордеров любого типа по их ID;
--close-order или --cancel-order, --close-orders или --cancel-orders;
- API-метод: CloseOrders().
- Закрывать ранее открытые позиции полностью (кроме заблокированных объёмов), указав конкретный инструмент или список инструментов через их тикеры или FIGI;
--close-trade (--cancel-trade) или --close-trades (--cancel-trades);
- API-метод: CloseTrades().
- Отменять все открытые ранее ордера и закрывать текущие позиции по всем инструментам сразу, кроме заблокированных объёмов и позиций по валютам, которые необходимо закрывать отдельно;
--close-all (возможно использовать совместно с ключами --ticker или --figi), также можно конкретизировать ордера, тип актива или указать через пробел сразу несколько ключевых слов после ключа --close-all: orders, shares, bonds, etfs или futures;
- API-методы: CloseAll(), CloseAllByTicker(), CloseAllByFIGI(), IsInLimitOrders(), GetLimitOrderIDs(), IsInStopOrders(), GetStopOrderIDs(), CloseAllOrders() и CloseAllTrades().
- Получать лимиты пользователя на доступные для вывода средства;
--limits (--withdrawal-limits, -w);
- API-методы: RequestLimits() и OverviewLimits().
- Строить интерактивные или статические свечные графики цен (используя библиотеку PriceGenerator), источником цен при этом могут быть как загруженные с сервера данные, так и ранее сохранённые файлы в csv-формате;
--render-chart, который используется совместно с одним из ключей --history (загрузка данных с сервера) или --load-history (загрузка из csv-файла);
- API-методы: ShowHistoryChart(), History() и LoadHistory().
- Запрашивать общую информацию о пользователе, список аккаунтов (в том числе
accountIdвсех счетов), доступные средства для маржинальной торговли и лимиты подключений через API для текущего тарифа;
--user-info (-u) для получения всей информации или ключ --account (--accounts, -a) для получения списка аккаунтов;
- API-методы: RequestAccounts(), RequestUserInfo(), RequestMarginStatus(), RequestTariffLimits(), OverviewUserInfo() и OverviewAccounts().
- Запрашивать данные об облигациях, обогащать их и превращать в Pandas DataFrame с большим количеством дополнительной информации для будущего использования датасайнтистами или биржевыми аналитиками: основные данные, текущая цена, календарь выплат по облигациям, купонный доход, текущая доходность и некоторая статистика, а также сохранять эти данные в XLSX-файл;
--bonds-xlsx (-b) для обогащения данных по всем сразу или по указанным облигациям;
- API-методы: RequestBondCoupons() и ExtendBondsData().
- Генерировать календарь выплат по всем сразу или по списку облигаций и сохранять его в файл формата Markdown или в XLSX-файл;
--calendar (-c) для построения календаря выплат по купонам;
- API-методы: CreateBondsCalendar() и ShowBondsCalendar().
- Генерировать HTML-отчёты из любых отчётов формата Markdown;
--html (--HTML), который можно указать с любой из команд: --list, --info, --search, --prices, --deals, --limits, --calendar, --account, --user-info, --overview, --overview-digest, --overview-positions, --overview-orders, --overview-analytics и --overview-calendar;
- API-методы: Listing(), ShowInstrumentInfo(), SearchInstruments(), GetListOfPrices(), Deals(), OverviewLimits(), CreateBondsCalendar(), OverviewAccounts(), OverviewUserInfo() и Overview() с включенным параметром TinkoffBrokerServer.useHTMLReports = True.
Как установить
Проще всего использовать установку через PyPI:
pip install tksbrokerapiПосле этого можно проверить установку командой:
pip show tksbrokerapi
tksbrokerapi --versionТакже можно использовать модуль TKSBrokerAPI, скачав его напрямую из репозитория через git clone и взяв кодовую базу любого протестированного релиза.
В первом случае инструмент будет доступен в консоли через команду tksbrokerapi, а во втором случае вам придётся запускать его как обычный Python-скрипт, через python TKSBrokerAPI.py из каталога с исходным кодом.
❗ Важное замечание: модуль TKSBrokerAPI тестировался для python >= 3.9. В более ранних версиях будут возникать ошибки. Далее все примеры написаны для случая, когда TKSBrokerAPI установлен через PyPI и запускается в python == 3.9.
Аутентификация
Токен
Сервис TINKOFF INVEST API использует для аутентификации токен. Токен — это набор символов, в котором зашифрованы данные о владельце, правах доступ и прочая информация, необходимая для авторизации в сервисе. Токен необходимо передавать на сервер с каждым сетевым запросом.
Платформа TKSBrokerAPI берёт всю работу с токенами на себя. Есть три варианта задания токена пользователя:
- при вызове
tksbrokerapiв консоли укажите ключ:--token "yourtokenhere"; - либо укажите
tokenпри инициализации класса в Python-скрипте:TKSBrokerAPI.TinkoffBrokerServer(token="yourtoken_here", ...); - или же можно заранее установить специальную переменную в пользовательском окружении:
TKSAPITOKEN=yourtokenhere.
❗ Важное замечание: никогда и никому не передавайте свои токены, не используйте их в примерах, а также не сохраняйте их в пабликах и в коде. Токеном может воспользоваться кто угодно, но все операции у брокера будут отображаться от вашего имени. Если вы хотите использовать свои токены для автоматизации в CI/CD-системах, то обязательно пользуйтесь сокрытием переменных окружения (пример установки "hidden variables" для Travis CI, и пример установки "protected variables" для GitLab CI).
Идентификатор счёта пользователя
Второй важный параметр для работы TKSBrokerAPI — это идентификатор конкретного счёта пользователя. Он не является обязательным, но без его указания будет невозможно выполнить многие операции через API (посмотреть портфель по брокерскому счёту, выполнить торговые операции, узнать лимиты на вывод средств и многие другие).
Вы можете найти этот идентификатор в любом брокерском отчёте (их можно заказать либо из мобильного приложения Тинькофф Инвестиции, либо в личном кабинете на сайте). Обычно идентификатор счёта пользователя находится сверху, в "шапке" отчётов. Также можно узнать этот номер спросив в чате техподдержки Тинькофф Инвестиции.
Но самый простой способ — это воспользоваться командой --user-info и TKSBrokerAPI покажет вам список всех доступных счетов пользователя и их идентификаторы (токен должен быть задан, см. раздел "Получить информацию о пользователе и счетах").
Есть три варианта задания идентификатора счёта пользователя:
- при вызове
tksbrokerapiв консоли укажите ключ:--account-id youridnumber"; - либо укажите
accountIdпри инициализации класса в Python-скрипте:TKSBrokerAPI.TinkoffBrokerServer(token="...", accountId=yourid_number, ...); - или же можно заранее установить специальную переменную в пользовательском окружении:
TKSACCOUNTID=youridnumber.
Справка по ключам
Используется ключ --help (-h), действие не указывается. В консоль будет выведен актуальный для данного релиза список ключей и их краткое описание.
tksbrokerapi --help🚀 Как запустить
Платформу можно использовать двумя способами:
# Как модуль Python
python TKSBrokerAPI.py [options] [command]
Как CLI-инструмент (если установлен с entry point)
tksbrokerapi [options] [command]💡 Обзор платформы
TKSBrokerAPI — это торговая платформа, предназначенная для автоматизации и упрощения торговых сценариев. Она работает с Tinkoff Invest API (REST) и поддерживает полный цикл: торговлю, получение данных, управление ордерами и исполнение сигналов.
⚙️ Опции
| Option | Описание | Пример | |---------------------------------|-------------------------------------------------------------------------------|---------------------------------| | --token TOKEN | API токен. Если не задан — используется переменная окружения TKSAPITOKEN. | --token abc123 | | --account-id ACCOUNTID | ID счёта. Можно узнать из отчётов брокера и установить в TKSACCOUNT_ID. | --account-id 123456789 | | --ticker TICKER, -t TICKER | Тикер инструмента, например: GAZP, SBER, USD. | --ticker YNDX | | --figi FIGI, -f FIGI | FIGI-код инструмента. | --figi BBG000TJ6F42 | | --depth DEPTH | Глубина стакана (DOM), целое число ≥1. | --depth 10 | | --output OUTPUT | Путь к файлу для сохранения (CSV, MD, XLSX). | --output deals.md | | --interval INTERVAL | Интервал свечей: 1min, 5min, 15min, hour, day. | --interval hour | | --date-start DATE, -ds DATE | Дата начала для исторических данных. | --date-start 2024-01-01 | | --only-missing | Добавлять только недостающие свечи в файл. | --only-missing | | --html | Генерировать HTML-отчёты из Markdown. | --html | | --debug-level N, -v N | Уровень логов: 10=DEBUG, 20=INFO и т.д. | -v 20 | | --more | Включить расширенное логирование, включая HTTP-заголовки. | --more | | --tag TAG | Опциональный тег для различения параллельных запусков. | --tag "Backtest#1" | | --crontab CRON | Cron-выражение в формате pycron. | --crontab "/5 10-23 * 1-5" | | --wait-after-iteration SECS | Пауза после каждой итерации cron. | --wait-after-iteration 60 | | --wait-next SECS | Пауза перед следующим cron-запросом. | --wait-next 2 | | --no-cache | Игнорировать локальный кеш dump.json. | --no-cache | | --csv-sep SEP | Разделитель CSV, по умолчанию ,. | --csv-sep ; | | --no-cancelled | Не показывать отменённые сделки. | --no-cancelled | | --version, --ver | Показать версию TKSBrokerAPI. | --version |
🛠 Команды
🔍 Рыночные данные
| Command | Описание | Пример | |-----------------------|----------------------------------------|---------------------------| | --list, -l | Показать все доступные инструменты. | --list | | --search NAME, -s | Найти инструмент по названию/тикеру. | --search "Газпр" | | --info, -i | Подробная информация по тикеру/FIGI. | --ticker YDEX --info | | --calendar, -c | Календарь выплат по облигациям. | --calendar SBER | | --price | Актуальная цена по одному инструменту. | --ticker GAZP --price | | --prices, -p | Цены по нескольким инструментам. | --prices GAZP SBER YDEX |
📊 Отчёты и история
| Command | Описание | Пример | |------------------------|-----------------------------------|------------------------| | --deals, -d | Все сделки за указанный период. | --deals week | | --overview, -o | Полный снимок портфеля. | --overview | | --overview-digest | Краткая сводка. | --overview-digest | | --overview-positions | Только открытые позиции. | --overview-positions | | --overview-orders | Только лимитные и стоп-заявки. | --overview-orders | | --limits, -w | Таблица лимитов на вывод средств. | --limits | | --user-info, -u | Информация о пользователе/счетах. | --user-info | | --account, -a | Перечень всех аккаунтов. | --account |
📈 Исторические данные
| Command | Описание | Пример | |-------------------------------------|--------------------------------------------------|---------------------------------------------------------| | --history, --get-history, -gh | Скачать свечи по инструменту. | --ticker GAZP --history today | | --load-history, -lh | Загрузить данные из файла и вывести таблицу. | --load-history mydata.csv | | --render-chart | Построить график: interact или non-interact. | --render-chart i | | --history-auto-updater, -hu | Автообновление истории по расписанию (cron). | --history-auto-updater GAZP SBER YDEX --date-start -3 |
📤 Торговые операции
| Command | Описание | Пример | |-------------------------------------|---------------------------------------|-------------------------------| | --trade | Открыть рыночную позицию. | --trade Buy 1 200.0 180.0 | | --buy, --sell | Мгновенная покупка/продажа. | --buy 2 220.0 190.0 | | --order | Универсальный лимит/стоп-ордер. | --order Buy Limit 1 190.0 | | --buy-limit, --sell-limit | Лимитная заявка. | --buy-limit 2 180.0 | | --buy-stop, --sell-stop | Стоп-заявка. | --sell-stop 1 150.0 | | --close-order, --cancel-order | Отмена одного ордера по ID. | --close-order abc123 | | --close-orders, --cancel-orders | Отмена нескольких ордеров по ID. | --close-orders id1 id2 | | --close-trade, --cancel-trade | Закрыть одну позицию. | --ticker YNDX --close-trade | | --close-trades, --cancel-trades | Закрыть список позиций. | --close-trades GAZP SBER | | --close-all, --cancel-all | Закрыть все (кроме валютных) позиции. | --close-all |
Примеры использования
Далее рассмотрим некоторые сценарии использования платформы TKSBrokerAPI: при её запуске в консоли или как Python-скрипт.
❗ По умолчанию в консоль выводится информация уровня INFO. В случае возникновения каких-либо ошибок, рекомендуется повысить уровень логирования до DEBUG. Для этого укажите вместе с командой любой из ключей: --debug-level=10, --verbosity=10 или -v 10. После этого скопируйте логи с проблемой и создайте новый баг в разделе 👉 Issues 👈, пожалуйста. Желательно указывать версию проблемной сборки, которую можно узнать по ключу --version (или --ver).
Также информация уровня DEBUG всегда выводится в служебный файл TKSBrokerAPI.log (он создаётся в рабочей директории, где происходит вызов tksbrokerapi или скрипта python TKSBrokerAPI.py). Начиная с TKSBrokerAPI v1.5.120 можно использовать ключ --more (--more-debug), который дополнительно включает во всех методах отладочную информацию и выводит её в логи, например, сетевые запросы, ответы и их заголовки.
Если вы запускаете несколько экземпляров платформы TKSBrokerAPI в параллельном режиме, можно использовать дополнительный тег для упрощения отладки и идентификации экземпляров в логах. Тег добавляется ключом --tag (начиная с TKSBrokerAPI v1.6.*).
Из командной строки
При запуске платформы TKSBrokerAPI в консоли можно указать множество параметров и выполнить одно действие. Формат команд следующий:
tksbrokerapi [необязательные ключи и параметры] [одно действие]❗ Для выполнения большинства команд вы должны каждый раз указывать свой токен через ключ --token и идентификатор пользователя через ключ --account-id, либо один раз установить их через переменные окружения TKSAPITOKEN и TKSACCOUNTID (см. раздел "Аутентификация").
Примечание: в примерах ниже токен доступа и ID счёта были заранее заданы через переменные окружения TKSAPITOKEN и TKSACCOUNTID, поэтому ключи --token и --account-id не фигурируют в логах.
Локальный кэш данных
Начиная с версии TKSBrokerAPI v1.2.62 добавлена возможность использования локального кэша dump.json с данными по торгуемым инструментам, что позволяет избежать постоянных запросов этих данных с сервера брокера и существенно сэкономить время. Кэш используется по умолчанию при исполнении любой команды, специально задавать его не требуется.
Если текущий день отличается от дня последнего изменения кэша, то он автоматически обновится при очередном запуске программы. Если файл dump.json не существует в локальном каталоге, он также будет создан автоматически.
Обычно на биржах редко происходят критические изменения по инструментам в течение дня и обновление кэша минимум раз в день оправданно. Но если вы хотите быть полностью уверены в консистентности данных, то можете указывать ключ --no-cahce вместе с каждой командой. В этом случае данные по инструментам будут запрашиваться каждый раз.
Получить список всех доступных для торговли инструментов
Используется ключ --list (-l). При этом запрашивается информация с сервера брокера по инструментам, доступным для текущего аккаунта. Дополнительно можно использовать ключ --output для указания файла, куда следует сохранить полученные данные в виде таблицы в человеко-читаемом формате Markdown (по умолчанию instruments.md в текущей рабочей директории). Для генерации файла instruments.md используются данные из локального кеша dump.json.
Ключ --debug-level=10 (или --verbosity 10, -v 10) выведет всю отладочную информацию в консоль (можно его не указывать).
Начиная с TKSBrokerAPI v1.4.90 вы можете использовать ключ --list-xlsx (-x), чтобы сохранить сырые данные по доступным инструментам в формате XLSX, пригодном для дальнейшей обработки датасайнтистами или биржевыми аналитиками. По умолчанию используются данные из локального кеша dump.json, которые трансформируются в XLSX-формат и сохраняются в файл dump.xlsx.
На выходе получится XLSX-файл, содержащий сырые данные и заголовки, полученные с сервера брокера. Пример можно посмотреть в файле ./docs/media/dump.xlsx. Что означают заголовки в XLSX-файле, смотрите в разделах "Получить обогащённые данные по облигациям" и "Построить календарь выплат по облигациям".
Команда для получения списка всех доступных инструментов в формате Markdown
$ tksbrokerapi --debug-level=10 --list --output ilist.md
TKSBrokerAPI.py L:2804 DEBUG [2022-07-26 22:04:39,571] TKSBrokerAPI module started at: [2022-07-26 19:04:39] (UTC), it is [2022-07-26 22:04:39] local time TKSBrokerAPI.py L:198 DEBUG [2022-07-26 22:04:39,572] Bearer token for Tinkoff OpenApi set up from environment variable TKSAPITOKEN. See https://tinkoff.github.io/investAPI/token/ TKSBrokerAPI.py L:210 DEBUG [2022-07-26 22:04:39,572] String with user's numeric account ID in Tinkoff Broker set up from environment variable TKSACCOUNTID TKSBrokerAPI.py L:240 DEBUG [2022-07-26 22:04:39,573] Broker API server: https://invest-public-api.tinkoff.ru/rest TKSBrokerAPI.py L:411 DEBUG [2022-07-26 22:04:39,573] Requesting all available instruments from broker for current user token. Wait, please... TKSBrokerAPI.py L:412 DEBUG [2022-07-26 22:04:39,574] CPU usages for parallel requests: [7] TKSBrokerAPI.py L:389 DEBUG [2022-07-26 22:04:39,581] Requesting available [Currencies] list. Wait, please... TKSBrokerAPI.py L:389 DEBUG [2022-07-26 22:04:39,581] Requesting available [Shares] list. Wait, please... TKSBrokerAPI.py L:389 DEBUG [2022-07-26 22:04:39,581] Requesting available [Bonds] list. Wait, please... TKSBrokerAPI.py L:389 DEBUG [2022-07-26 22:04:39,581] Requesting available [Etfs] list. Wait, please... TKSBrokerAPI.py L:389 DEBUG [2022-07-26 22:04:39,582] Requesting available [Futures] list. Wait, please... TKSBrokerAPI.py L:925 INFO [2022-07-26 22:04:40,400] # All available instruments from Tinkoff Broker server for current user token
- Actual on date: [2022-07-26 19:04] (UTC)
- Currencies: [21]
- Shares: [1900]
- Bonds: [655]
- Etfs: [105]
- Futures: [284]
Currencies available. Total: [21]
| Ticker | Full name | FIGI | Cur | Lot | Step |--------------|----------------------------------------------------------------|--------------|-----|--------|--------- | USDCHF_TOM | Швейцарский франк - Доллар США | BBG0013HPJ07 | chf | 1000 | 1e-05 | EURRUB_TOM | Евро | BBG0013HJJ31 | rub | 1000 | 0.0025 | CNYRUB_TOM | Юань | BBG0013HRTL0 | rub | 1000 | 0.0001 | ... | ... | ... | ... | ... | ... | RUB000UTSTOM | Российский рубль | RUB000UTSTOM | rub | 1 | 0.0025 | USD000UTSTOM | Доллар США | BBG0013HGFT4 | rub | 1000 | 0.0025
[... далее идёт аналогичная информация по другим инструментам ...]
TKSBrokerAPI.py L:931 INFO [2022-07-26 22:04:41,211] All available instruments are saved to file: [ilist.md] TKSBrokerAPI.py L:3034 DEBUG [2022-07-26 22:04:41,213] All operations with Tinkoff Server using Open API are finished success (summary code is 0). TKSBrokerAPI.py L:3039 DEBUG [2022-07-26 22:04:41,214] TKSBrokerAPI module work duration: [0:00:01.641989] TKSBrokerAPI.py L:3042 DEBUG [2022-07-26 22:04:41,215] TKSBrokerAPI module finished: [2022-07-26 19:04:41] (UTC), it is [2022-07-26 22:04:41] local time
Команда для получения сырых данных по всем доступным инструментам в XLSX-формате
$ tksbrokerapi -v 10 --list-xlsx
TKSBrokerAPI.py L:3482 DEBUG [2022-10-19 01:20:35,574] >>> TKSBrokerAPI module started at: [2022-10-18 22:20:35] UTC, it is [2022-10-19 01:20:35] local time TKSBrokerAPI.py L:3496 DEBUG [2022-10-19 01:20:35,576] TKSBrokerAPI major.minor.build version used: [1.3.dev77] TKSBrokerAPI.py L:3497 DEBUG [2022-10-19 01:20:35,576] Host CPU count: [8] TKSBrokerAPI.py L:210 DEBUG [2022-10-19 01:20:35,576] Bearer token for Tinkoff OpenApi set up from environment variable TKSAPITOKEN. See https://tinkoff.github.io/investAPI/token/ TKSBrokerAPI.py L:222 DEBUG [2022-10-19 01:20:35,576] String with user's numeric account ID in Tinkoff Broker set up from environment variable TKSACCOUNTID TKSBrokerAPI.py L:270 DEBUG [2022-10-19 01:20:35,576] Broker API server: https://invest-public-api.tinkoff.ru/rest TKSBrokerAPI.py L:395 DEBUG [2022-10-19 01:20:35,599] Local cache with raw instruments data is used: [dump.json] TKSBrokerAPI.py L:396 DEBUG [2022-10-19 01:20:35,599] Dump file was last modified [2022-10-18 20:38:59] UTC TKSBrokerAPI.py L:603 INFO [2022-10-19 01:20:37,278] XLSX-file for further used by data scientists or stock analytics: [dump.xlsx] TKSBrokerAPI.py L:3806 DEBUG [2022-10-19 01:20:37,278] All operations were finished success (summary code is 0). TKSBrokerAPI.py L:3813 DEBUG [2022-10-19 01:20:37,278] >>> TKSBrokerAPI module work duration: [0:00:01.703956] TKSBrokerAPI.py L:3814 DEBUG [2022-10-19 01:20:37,279] >>> TKSBrokerAPI module finished: [2022-10-18 22:20:37 UTC], it is [2022-10-19 01:20:37] local time
Найти инструмент
Чтобы работать с биржевыми инструментами, получать информацию по ним, запрашивать цены и совершать сделки, обычно требуется указать тикер (ключ --ticker) или FIGI (ключ --figi). Но вряд ли есть много людей, кто знает их наизусть. Чаще всего имеется лишь предположение о части символов тикера или примерного названия компании. В этом случае можно воспользоваться поиском по паттерну: части имени, тикера или FIGI, либо указав регулярное выражение. Поиск осуществляется стандартным Python модулем re, без учёта регистра.
Начиная с версии TKSBrokerAPI v1.2.62 добавлен ключ --search, после которого нужно указать паттерн. Например, требуется найти все инструменты группы компаний Сбер, тогда можно попробовать задать часть слова: tksbrokerapi --search "sbe" (или по-русски "сбер"). Или же хочется узнать все инструменты компаний, в названии которых встречаются слова "Российские", "акции" и "облигации". В этом случае можно попробовать скомбинировать слова и задать регулярное выражение: tksbrokerapi --search "(Росс.).(?:.*ции)".
Дополнительно к ключу --search можно указать ключ --output и задать имя файла, куда сохранить результаты поиска. По умолчанию полные результаты поиска сохраняются в search-results.md. В консоли отображаются только первые 5 найденных инструмента каждого типа.
После того как нужный инструмент был найден и стали известны его тикер и FIGI, посмотреть более подробную информацию можно командой tksbrokerapi -t TICKER --info или tksbrokerapi -f FIGI --info (подробнее).
Команда для поиска инструмента по части названия
$ tksbrokerapi --search "сбер"
TKSBrokerAPI.py L:1065 INFO [2022-08-11 22:00:31,171] # Search results
- Search pattern: [сбер]
- Found instruments: [21]
Note: you can view info about found instruments with key --info, e.g.: tksbrokerapi -t TICKER --info or tksbrokerapi -f FIGI --info.
Shares: [2]
| Type | Ticker | Full name | FIGI | |------------|--------------|----------------------------------------------------------------|--------------| | Shares | SBER | Сбер Банк | BBG004730N88 | | Shares | SBERP | Сбер Банк - привилегированные акции | BBG0047315Y7 |
Bonds: [8]
| Type | Ticker | Full name | FIGI | |------------|--------------|----------------------------------------------------------------|--------------| | Bonds | RU000A101QW2 | Сбер Банк | BBG00V9STNC5 | | Bonds | RU000A103YM3 | Сбер Банк 002P выпуск 1 | BBG013J0F816 | | Bonds | RU000A101C89 | Сбер Банк 001P-SBER15 | BBG00RKBQ4D2 | | Bonds | RU000A102FR3 | Сбербанк | BBG00YHVQ768 | | Bonds | RU000A103G75 | Сбер Банк 001P-SBER32 | BBG0122KNFZ0 | | ... | ... | ... | ... |
Etfs: [1]
| Type | Ticker | Full name | FIGI | |------------|--------------|----------------------------------------------------------------|--------------| | Etfs | RU000A104172 | ЗПИФ ПАРУС-Сберлог | TCS00A104172 |
Futures: [10]
| Type | Ticker | Full name | FIGI | |------------|--------------|----------------------------------------------------------------|--------------| | Futures | SPH2 | SBPR-3.22 Сбер Банк (привилегированные) | FUTSBPR03220 | | Futures | SRU2 | SBRF-9.22 Сбер Банк (обыкновенные) | FUTSBRF09220 | | Futures | SRH3 | SBRF-3.23 Сбер Банк (обыкновенные) | FUTSBRF03230 | | Futures | SRH2 | SBRF-3.22 Сбер Банк (обыкновенные) | FUTSBRF03220 | | Futures | SPM2 | SBPR-6.22 Сбер Банк (привилегированные) | FUTSBPR06220 | | ... | ... | ... | ... |
TKSBrokerAPI.py L:1066 INFO [2022-08-11 22:00:31,172] You can view info about found instruments with key --info, e.g.: tksbrokerapi -t IBM --info or tksbrokerapi -f BBG000BLNNH6 --info TKSBrokerAPI.py L:1072 INFO [2022-08-11 22:00:31,172] Full search results were saved to file: [search-results.md]
Команда для поиска инструмента по регулярному выражению
``commandline $ tksbrokerapi --search "(Росс.).(?:.*ции)"
TKSBrokerAPI.py L:1067 INFO [2022-08-11 22:41:39,039] # Search results
Search pattern: [(Росс.).(?:.ции)]
- Found instruments: [5]
, e.g.: tksbrokerapi -t TICKER --info or tksbrokerapi -f FIGI --info`.
Shares: [1]
| Type | Ticker | Full name | FIGI | |------------|--------------|----------------------------------------------------------------|--------------| | Shares | RSTIP | Российские сети - акции привилегированные | BBG000KTF667 |
Etfs: [4]
| Type | Ticker | Full name | FIGI | |------------|--------------|----------------------------------------------------------------|--------------| | Etfs | AMRE | АТОН Российские акции + | TCS00A102XX4 | | Etfs | AMRB | АТОН Российские облигации + | TCS00A102XY2 | | Etfs | SBCB | Первая - Фонд Российские еврооблигации | BBG00NB6KGN0 | | Etfs | AKME
README truncated. View on GitHub
