# Справочная информация о ценных бумагах
## Получить параметры ценных бумаг
Первоочередная задача, которая стоит перед разработчиком торгового робота — получить справочную информацию об инструментах, торгуемых на бирже. Для этого в T-Invest API есть unary-методы.
<blockquote>
<p><strong>Обратите внимание</strong></p>
<p>Методы разделены по типам инструментов — акции, облигации, фонды и другие. Например, чтобы получить:</p>
<ul>
<li>список облигаций — используйте метод <a href="/investAPI/instruments#bonds">Bonds</a>;</li>
<li>информацию по конкретной облигации — <a href="/investAPI/instruments#bondby">BondBy</a>. </li>
</ul>
</blockquote>
В методах для получения информации по конкретному инструменту в качестве идентификатора можно использовать
FIGI, ISIN или связку тикер плюс класс-код. [Подробнее об особенностях идентификации инструментов](/investAPI/faq_identification/).
## Получить расписание торгов
Чтобы определить время запуска или остановки торгового робота, разработчику также нужно учитывать
расписание торгов на той или иной торговой площадке внутри брокера. [Подробнее о режимах торгов](/investAPI/markets/).
Расписание торгов по конкретной бирже и по всему списку доступных торговых площадок в T-Invest API можно получить через метод [TradingSchedules](/investAPI/instruments#tradingschedules).
Расписание торгов можно получить на период не больше одной недели с текущего дня — раcписания в прошлом недоступны.
>**Обратите внимание** <br>
>Расписание торгов может меняться из-за внешних обстоятельств — специалисты Т-Инвестиций стараются максимально оперативно реагировать на такие изменения. Лучше не ориентироваться на расписание, запрошенное по длительному периоду, а запрашивать режимы торгов на более короткие интервалы — например, на текущий день.
Также учитывайте, что в процессе работы торговой площадки торги по той или иной ценной бумаге могут приостанавливаться — например, из-за резко возросшей волатильности. Поэтому для определения доступности торгов в данный момент по конкретному инструменту лучше использовать параметр `trading_status`, который возвращается в рамках подписки на получение статуса инструмента [сервиса котировок](/investAPI/head—marketdata/).
>**Важно** <br>
>Метод [TradingSchedules](/investAPI/instruments#tradingschedules) возвращает торговое расписание на секции биржи внутри брокера. Это расписание может не совпадать с реальным расписанием торгов на бирже.
## Получить расписания выплаты купонов по облигациям
Облигация — это долговая ценная бумага, почти как долговая расписка. Выпуская облигации, компания
или государство берёт деньги в долг и возвращает их с процентами. [Подробнее про облигации](https://www.tbank.ru/invest/help/educate/how-it-works/ways-to-invest/bonds/).
Купоны — это операции по регулярным выплатам процентов по облигации. Чтобы получить график выплаты купонов для запрошенного периода времени, используйте метод [getAccruedInterests](/investAPI/instruments#getaccruedinterests).
## Получить размер гарантийного обеспечения (ГО) по фьючерсу
Фьючерс — это договор между покупателем и продавцом о поставке базового актива в будущем или выплате
одной из сторон другой разницы между стоимостью контракта и стоимостью базового актива в
будущем. [Подробнее про срочный рынок](https://www.tbank.ru/invest/help/brokerage/account/forts/).
Для операций с фьючерсами брокер «замораживает» определённый размер гарантийного обеспечения на счёте
пользователя. Чтобы получить информацию о размере обеспечения, используйте методы [Futures](/investAPI/instruments/#futures), [FutureBy](/investAPI/instruments/#futureby) и [getFuturesMargin](/investAPI/instruments#getfuturesmargin).
Параметры `initial_margin_on_buy` и `initial_margin_on_sell` возвращают Гарантийное обеспечение, рассчитанное Биржей, а коэффициенты `dshort_client` и `dlong_client` определяют сумму заблокированных брокером средств при торговле фьючерсами.
>**Важно** <br>
>Метод возвращает примерное значение средств к блокировке, которое рассчитывается биржей.
Это значение не является конечным резервируемым объёмом ГО — после заключения сделки заблокированная сумма может измениться.
>**Важно** <br>
>Точную сумму денежных средств блокируемых брокером можно посчитать используя параметры `dshort_client` и `dlong_client`, которые определяют коэффициент блокируемых средств от суммы сделки.
## Инструменты
### Получить и изменить список избранных инструментов
Список избранных инструментов можно получить через метод [GetFavorites](/investAPI/instruments#getfavorites) — в ответе возвращаются инструменты, которые робот добавил в избранное через метод [EditFavorites](/investAPI/instruments#editfavorites).
Чтобы добавить или удалить инструменты из списка избранных, используйте метод [EditFavorites](/investAPI/instruments#editfavorites). С помощью него можно автоматизировать выделение наиболее интересных инструментов через редактирование списка избранных инструментов.
Ограничение на использование метода — 100 инструментов. Если вы передадите больше 100 инструментов, вернётся ошибка с кодом `30091` и сообщением `quantity of instruments can't be more than 100`.
>**Важно**
><p>Если вы хотите добавить валюту в список избранных инструментов, это нужно делать через валюту с лотностью 1. Инструменты валюты с разной лотностью имеют разные значения идентификаторов.</p>
><p>У позиции (валюты) есть разные инструменты, которыми можно торговать. Например, у доллара это могут быть инструменты с лотностью в 1 доллар или 1000 долларов.</p>
><p>Примеры идентификаторов:</p>
><ul>
><li>FIGI доллара США с лотностью <code>1000</code> — <code>TCS0013HGFT4</code>, а FIGI доллара США с лотностью <code>1</code> — <code>USD000UTSTOM</code>.</li>
><li>FIGI евро с лотностью <code>1000</code> — <code>BBG0013HJJ31</code>, а FIGI доллара США с лотностью <code>1</code> — <code>EUR000UTSTOM</code>.</li>
></ul>
Все инструменты, которые вы добавили в избранное, будут отображаться в списке избранных в мобильном приложении Инвестиций и на сайте [Т-Инвестиции](https://www.tbank.ru/invest/favorites/).
### Определить биржу, на которой исполняются расчёты по инструменту
В T-Invest API есть параметр [real_exchange](/investAPI/instruments/#realexchange) — он передаётся для определения биржи, на которой исполняются расчёты по финансовому инструменту.
Список методов:
* [GetInstrumentBy](/investAPI/instruments/#getinstrumentby) — получить основную информацию об инструменте.
* [BondBy](/investAPI/instruments/#bondby) — получить облигацию по её идентификатору.
* [Bonds](/investAPI/instruments/#bonds) — получить список облигаций.
* [ShareBy](/investAPI/instruments/#shareby) — получить акцию по её идентификатору.
* [Shares](/investAPI/instruments/#shares) — получить список акций.
* [EtfBy](/investAPI/instruments/#etfby) — получить инвестиционный фонд по его идентификатору.
* [Etfs](/investAPI/instruments/#etfs) — получить список инвестиционных фондов.
* [FutureBy](/investAPI/instruments/#futureby) — получить фьючерс по его идентификатору.
* [Futures](/investAPI/instruments/#futures) — получить список фьючерсов.
* [OptionBy](/investAPI/instruments/#optionby) — получить опцион по его идентификатору.
* [OptionsBy](/investAPI/instruments/#optionsby) и [Options](/investAPI/instruments/#options) — получить список опционов.
* [CurrencyBy](/investAPI/instruments/#currencyby) — получить валюту по её идентификатору.
* [Currencies](/investAPI/instruments/#currencies) — получить список валют.
### Найти инструменты
Для поиска инструментов в T-Invest API используйте следующие методы — в зависимости от типа искомого инструмента:
* [GetInstrumentBy](/investAPI/instruments/#getinstrumentby) — получить основную информацию об инструменте.
* [BondBy](/investAPI/instruments/#bondby) — получить облигацию по её идентификатору.
* [Bonds](/investAPI/instruments/#bonds) — получить список облигаций.
* [ShareBy](/investAPI/instruments/#shareby) — получить акцию по её идентификатору.
* [Shares](/investAPI/instruments/#shares) — получить список акций.
* [EtfBy](/investAPI/instruments/#etfby) — получить инвестиционный фонд по его идентификатору.
* [Etfs](/investAPI/instruments/#etfs) — получить список инвестиционных фондов.
* [FutureBy](/investAPI/instruments/#futureby) — получить фьючерс по его идентификатору.
* [Futures](/investAPI/instruments/#futures) — получить список фьючерсов.
* [OptionBy](/investAPI/instruments/#optionby) — получить опцион по его идентификатору.
* [OptionsBy](/investAPI/instruments/#optionsby) и [Options](/investAPI/instruments/#options) — получить список опционов.
* [CurrencyBy](/investAPI/instruments/#currencyby) — получить валюту по её идентификатору.
* [Currencies](/investAPI/instruments/#currencies) — получить список валют.
* [Indicatives](/investAPI/instruments/#indicatives) — получить список индексов и товаров.
Также у нас есть метод поиска инструмента по различным параметрам — [FindInstrument](/investAPI/instruments/#findinstrument). Он выполняет регистронезависимый поиск по вхождению строки **query** согласно приоритету:
* `position_uid`;
* `uid`;
* `figi`;
* `isin`;
* `ticker`;
* `name`.
Чтобы найти базовый актив фьючерса, можно использовать метод [FindInstrument](/investAPI/instruments/#findinstrument) — для этого в **query** передайте значение параметра `basic_asset_position_uid`, которое возвращается в методах [GetFutureBy](/investAPI/instruments/#futureby) и [GetFutures](/investAPI/instruments/#futures).
### Посмотреть доступность торговли инструмента через API
Чтобы получить информацию о возможности торговли инструментом через API, используйте метод [FindInstrument](/investAPI/instruments/#findinstrument).
В нём есть параметр `api_trade_available_flag` — если `api_trade_available_flag = true`, торговать инструментом через API можно.
### Получить справочник стран
Чтобы получить справочник стран, используйте метод [getCountries](/investAPI/instruments/#getcountriesrequest).
Он возвращает массив объектов с двухбуквенными и трёхбуквенными кодами страны, а также её полное и краткое название.
Полученный список стран можно применять для сопоставления страны риска актива.
### Получить активы
<p>В T-Invest API есть два метода для получения активов:</p>
<ol>
<li><p><a href="/investAPI/instruments/#getassets">getAssets</a> — получить список всех активов. Метод работает для всех инструментов, кроме срочных: опционов и фьючерсов. Возвращает краткую информацию об активе: </p>
<ul>
<li>Идентификатор.</li>
<li>Тип актива.</li>
<li>Название актива.</li>
<li>Массив инструментов актива.</li>
</ul>
</li>
<li><p><a href="/investAPI/instruments/#getassetby">getAssetBy</a> — найти актив по его идентификатору.
Метод возвращает более подробную информацию о запрошенном активе. Набор данных отличается в зависимости от типа актива.</p>
</li>
</ol>
### Получить бренды
В T-Invest API есть два метода для получения брендов:
1. [getBrands](/investAPI/instruments/#getbrands) — получить список всех брендов.
2. [getBrandBy](/investAPI/instruments/#getbrandby) — найти бренд по его идентификатору.
### Получить индикативные инструменты
Через метод [Indicatives](/investAPI/instruments/#indicatives) можно получить информацию об активах, которые не торгуются на бирже — например, по индексу IMOEX или нефти.
С идентификатором такого актива можно построить свечи через метод [getCandles](/investAPI/marketdata/#getcandles), как для других инструментов. Для построения свечей по индикативам в качестве идентификатора лучше использовать `UID`.
### Найти инструмент по позиции
Для поиска инструмента по идентификатору позиции (`position_uid`) есть тип идентификатора инструмента — `INSTRUMENT_ID_TYPE_POSITION_UID`.
Использовать `id_type = INSTRUMENT_ID_TYPE_POSITION_UID` можно в методах:
* [InstrumentBy](/investAPI/instruments/#getinstrumentby) — получить основную информацию об инструменте.
* [BondBy](/investAPI/instruments/#bondby) — получить облигацию по её идентификатору.
* [ShareBy](/investAPI/instruments/#shareby) — получить акцию по её идентификатору.
* [EtfBy](/investAPI/instruments/#etfby) — получить инвестиционный фонд по его идентификатору.
* [FutureBy](/investAPI/instruments/#futureby) — получить фьючерс по его идентификатору.
* [OptionBy](/investAPI/instruments/#optionby) — получить опцион по его идентификатору.
* [CurrencyBy](/investAPI/instruments/#currencyby) — получить валюту по её идентификатору.
### Получить информацию по опционам
Для получения информации по опционам, страйкам и датам экспирации в T-Invest API есть следующие методы:
* [GetOptionBy](/investAPI/instruments/#optionby) — получить опцион по его идентификатору.
* [GetOptions](/investAPI/instruments/#options) — получить опционы.
- [getPositions](/investAPI/operations#getpositions) — получить массив опционов в портфеле.
Также вы можете получить информацию о базовом активе опциона и найти его по идентификатору позиции базового инструмента — `basicAssetPositionUid`.
>**Важно** <br>
>Сейчас через метод [FindInstrument](/investAPI/instruments/#findinstrument) получить информацию об опционах нельзя.
### Получить торговые статусы инструментов и расписание торгов
[Статусы торговых инструментов и расписания торгов](https://russianinvestments.github.io/investAPI/faq_trading_status/)
Также рекомендуем смотреть актуальную информацию по режимам и статусам торгов на сайтах [Московской биржи](https://www.moex.com/) и [СПБ биржи](https://spbexchange.ru/).
### Определить доступность торговли инструментом квалифицированному инвестору
В методах сервиса инструментов есть флаг `for_qual_investor_flag` — он нужен, чтобы определить доступность торговли инструментом для неквалифицированных инструментов.
Флаг отображает доступность торговли инструментом только для квалифицированных инвесторов.
### Получить график выплаты дивидендов по инструменту
Чтобы получить информацию по срокам выплаты дивидендов по инструменту, используйте метод [getDividends](/investAPI/instruments/#getdividends).
Учитывайте, что входной параметр `to` (окончание запрашиваемого периода в часовом поясе UTC) фильтрует выходные данные по параметру `record_date` — дате фиксации реестра.
### Получить фундаментальные показатели компаний
Метод [getAssetFundamentals](/investAPI/instruments/#getassetfundamentals) возвращает показатели компании по активу — как правило, акции компании.
Обычно данные обновляются на следующий рабочий день после публикации, в редких случаях это может занять больше недели. Информация доступна не по всем активам.
Ряд фундаментальных показателей, которые доступны в методе, могут не публиковаться компаниями или быть недоступными.
Некоторые значения зависят от финансового результата, например:
- `pe_ratio_ttm` — показывает соотношение рыночной капитализации компании к её чистой прибыли только при наличии прибыли;
- `price_to_sales_ttm` — не рассчитывается при отсутствии выручки;
- `ebitda_ttm` — не рассчитывается для некоторых секторов экономики.
Метод возвращает все параметры контракта. Значение `0` в ответе следует приравнивать к отсутствию данных.
## Пагинация
В ряде методов сервиса используется пагинация. Структура `paging`:
**В запросе**
| Поле | Тип | Описание |
| ----- | ---- | ----------- |
| `limit` | [int64](#int64) | Количество запрашиваемых записей |
| `page_number` | [int64](#int64) | Номер страницы |
<!-- end Fields -->
<!-- end HasFields -->
**В ответе**
| Поле | Тип | Описание |
| ----- | ---- | ----------- |
| `limit` | [int64](#int64) | Количество запрашиваемых записей |
| `page_number` | [int64](#int64) | Номер страницы |
| `total_count` | [int64](#int64) | Всего записей |
<!-- end Fields -->
<!-- end HasFields -->