Справочная информация о ценных бумагах

Получить параметры ценных бумаг

Первоочередная задача, которая стоит перед разработчиком торгового робота — получить справочную информацию об инструментах, торгуемых на бирже. Для этого в Tinkoff Invest API есть unary-методы.

Обратите внимание

Методы разделены по типам инструментов — акции, облигации, фонды и другие. Например, чтобы получить:

список облигаций — используйте метод Bonds;

информацию по конкретной облигации — BondBy.

В методах для получения информации по конкретному инструменту в качестве идентификатора можно использовать FIGI, ISIN или связку тикер плюс класс-код. Подробнее об особенностях идентификации инструментов.

Получить расписание торгов

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

Расписание торгов по конкретной бирже и по всему списку доступных торговых площадок в Tinkoff Invest API можно получить через метод TradingSchedules.

Расписание торгов можно получить на период не больше одной недели с текущего дня — раcписания в прошлом недоступны.

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

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

Важно
Метод TradingSchedules возвращает торговое расписание на секции биржи внутри брокера Тинькофф. Это расписание может не совпадать с реальным расписанием торгов на бирже.

Получить расписания выплаты купонов по облигациям

Облигация — это долговая ценная бумага, почти как долговая расписка. Выпуская облигации, компания или государство берёт деньги в долг и возвращает их с процентами. Подробнее про облигации.

Купоны — это операции по регулярным выплатам процентов по облигации. Чтобы получить график выплаты купонов для запрошенного периода времени, используйте метод getAccruedInterests.

Получить размер гарантийного обеспечения (ГО) по фьючерсу

Фьючерс — это договор между покупателем и продавцом о поставке базового актива в будущем или выплате одной из сторон другой разницы между стоимостью контракта и стоимостью базового актива в будущем. Подробнее про срочный рынок.

Для операций с фьючерсами брокер «замораживает» определённый размер гарантийного обеспечения на счёте пользователя. Чтобы получить информацию о размере обеспечения, используйте метод getFuturesMargin.

Важно
Метод возвращает примерное значение средств к блокировке, которое рассчитывается биржей. Это значение не является конечным резервируемым объёмом ГО — после заключения сделки заблокированная сумма может измениться.

Инструменты

Получить и изменить список избранных инструментов

Список избранных инструментов можно получить через метод GetFavorites — в ответе возвращаются инструменты, которые робот добавил в избранное через метод EditFavorites.

Чтобы добавить или удалить инструменты из списка избранных, используйте метод EditFavorites. С помощью него можно автоматизировать выделение наиболее интересных инструментов через редактирование списка избранных инструментов.

Ограничение на использование метода — 100 инструментов. Если вы передадите больше 100 инструментов, вернётся ошибка с кодом 30091 и сообщением quantity of instruments can't be more than 100.

Важно
Если вы хотите добавить валюту в список избранных инструментов, это нужно делать через валюту с лотностью 1. Инструменты валюты с разной лотностью имеют разные значения идентификаторов.

У позиции (валюты) есть разные инструменты, которыми можно торговать. Например, у доллара это могут быть инструменты с лотностью в 1 доллар или 1000 долларов.

Примеры идентификаторов:

FIGI доллара США с лотностью 1000 — TCS0013HGFT4, а FIGI доллара США с лотностью 1 — USD000UTSTOM.

FIGI евро с лотностью 1000 — BBG0013HJJ31, а FIGI доллара США с лотностью 1 — EUR000UTSTOM.

Все инструменты, которые вы добавили в избранное, будут отображаться в списке избранных в мобильном приложении Инвестиций и на сайте Тинькофф Инвестиции.

Определить биржу, на которой исполняются расчёты по инструменту

В Tinkoff Invest API есть параметр real_exchange — он передаётся для определения биржи, на которой исполняются расчёты по финансовому инструменту.

Список методов:

GetInstrumentBy — получить основную информацию об инструменте.
BondBy — получить облигацию по её идентификатору.
Bonds — получить список облигаций.
ShareBy — получить акцию по её идентификатору.
Shares — получить список акций.
EtfBy — получить инвестиционный фонд по его идентификатору.
Etfs — получить список инвестиционных фондов.
FutureBy — получить фьючерс по его идентификатору.
Futures — получить список фьючерсов.
OptionBy — получить опцион по его идентификатору.
OptionsBy и Options — получить список опционов.
CurrencyBy — получить валюту по её идентификатору.
Currencies — получить список валют.

Найти инструменты

Для поиска инструментов в Tinkoff Invest API используйте следующие методы — в зависимости от типа искомого инструмента:

GetInstrumentBy — получить основную информацию об инструменте.
BondBy — получить облигацию по её идентификатору.
Bonds — получить список облигаций.
ShareBy — получить акцию по её идентификатору.
Shares — получить список акций.
EtfBy — получить инвестиционный фонд по его идентификатору.
Etfs — получить список инвестиционных фондов.
FutureBy — получить фьючерс по его идентификатору.
Futures — получить список фьючерсов.
OptionBy — получить опцион по его идентификатору.
OptionsBy и Options — получить список опционов.
CurrencyBy — получить валюту по её идентификатору.
Currencies — получить список валют.
Indicatives — получить список индексов и товаров.

Также у нас есть метод поиска инструмента по различным параметрам — FindInstrument. Он выполняет регистронезависимый поиск по вхождению строки query согласно приоритету:

position_uid;
uid;
figi;
isin;
ticker;
name.

Чтобы найти базовый актив фьючерса, можно использовать метод FindInstrument — для этого в query передайте значение параметра basic_asset_position_uid, которое возвращается в методах GetFutureBy и GetFutures.

Посмотреть доступность торговли инструмента через API

Чтобы получить информацию о возможности торговли инструментом через API, используйте метод FindInstrument.

В нём есть параметр api_trade_available_flag — если api_trade_available_flag = true, торговать инструментом через API можно.

Получить справочник стран

Чтобы получить справочник стран, используйте метод getCountries. Он возвращает массив объектов с двухбуквенными и трёхбуквенными кодами страны, а также её полное и краткое название.

Полученный список стран можно применять для сопоставления страны риска актива.

Получить активы

В Tinkoff Invest API есть два метода для получения активов:

getAssets — получить список всех активов. Метод работает для всех инструментов, кроме срочных: опционов и фьючерсов. Возвращает краткую информацию об активе:
- Идентификатор.
- Тип актива.
- Название актива.
- Массив инструментов актива.
getAssetBy — найти актив по его идентификатору. Метод возвращает более подробную информацию о запрошенном активе. Набор данных отличается в зависимости от типа актива.

Получить бренды

В Tinkoff Invest API есть два метода для получения брендов:

getBrands — получить список всех брендов.
getBrandBy — найти бренд по его идентификатору.

Получить индикативные инструменты

Через метод Indicatives можно получить информацию об активах, которые не торгуются на бирже — например, по индексу IMOEX или нефти.

С идентификатором такого актива можно построить свечи через метод getCandles, как для других инструментов. Для построения свечей по индикативам в качестве идентификатора лучше использовать UID.

Найти инструмент по позиции

Для поиска инструмента по идентификатору позиции (position_uid) есть тип идентификатора инструмента — INSTRUMENT_ID_TYPE_POSITION_UID.

Использовать id_type = INSTRUMENT_ID_TYPE_POSITION_UID можно в методах:

InstrumentBy — получить основную информацию об инструменте.
BondBy — получить облигацию по её идентификатору.
ShareBy — получить акцию по её идентификатору.
EtfBy — получить инвестиционный фонд по его идентификатору.
FutureBy — получить фьючерс по его идентификатору.
OptionBy — получить опцион по его идентификатору.
CurrencyBy — получить валюту по её идентификатору.

Получить информацию по опционам

Для получения информации по опционам, страйкам и датам экспирации в Tinkoff Invest API есть следующие методы:

GetOptionBy — получить опцион по его идентификатору.
GetOptions — получить опционы.
getPositions — получить массив опционов в портфеле.

Также вы можете получить информацию о базовом активе опциона и найти его по идентификатору позиции базового инструмента — basicAssetPositionUid.

Важно
Сейчас через метод FindInstrument получить информацию об опционах нельзя.

Получить торговые статусы инструментов и расписание торгов

Статусы торговых инструментов и расписания торгов

Также рекомендуем смотреть актуальную информацию по режимам и статусам торгов на сайтах Московской биржи и СПБ биржи.

Определить доступность торговли инструментом квалифицированному инвестору

В методах сервиса инструментов есть флаг for_qual_investor_flag — он нужен, чтобы определить доступность торговли инструментом для неквалифицированных инструментов.

Флаг отображает доступность торговли инструментом только для квалифицированных инвесторов.

Получить график выплаты дивидендов по инструменту

Чтобы получить информацию по срокам выплаты дивидендов по инструменту, используйте метод getDividends.

Учитывайте, что входной параметр to (окончание запрашиваемого периода в часовом поясе UTC) фильтрует выходные данные по параметру record_date — дате фиксации реестра.

Получить фундаментальные показатели компаний

Метод getAssetFundamentals возвращает показатели компании по активу — как правило, акции компании.

Обычно данные обновляются на следующий рабочий день после публикации, в редких случаях это может занять больше недели. Информация доступна не по всем активам.

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

pe_ratio_ttm — показывает соотношение рыночной капитализации компании к её чистой прибыли только при наличии прибыли;
price_to_sales_ttm — не рассчитывается при отсутствии выручки;
ebitda_ttm — не рассчитывается для некоторых секторов экономики.

Метод возвращает все параметры контракта. Значение 0 в ответе следует приравнивать к отсутствию данных.

Пагинация

В ряде методов сервиса используется пагинация. Структура paging:

В запросе

Поле	Тип	Описание
`limit`	int64	Количество запрашиваемых записей
`page_number`	int64	Номер страницы

В ответе

Поле	Тип	Описание
`limit`	int64	Количество запрашиваемых записей
`page_number`	int64	Номер страницы
`total_count`	int64	Всего записей