Сервис получения информации о портфеле по конкретному счёту
Получение списка операций по счёту
В процессе работы торговому роботу требуется получать информацию об операциях по счёту. Например, чтобы корректно рассчитывать доходности и собирать статистику своей работы. Для реализации данных потребностей можно использовать метод getOperations, а также более новый метод getOperationsByCursor.
При работе с данными методами необходимо учитывать особенности взаимодействия.
Метод getOperationsByCursor является более предпочтительным для использования, возвращает список всех операций по указанному счету. Данный метод возвращает информацию обо всех операциях, в том числе отмененных, поддерживает пагинацию и расширенную фильтрацию. Плюс данный метод обладает всеми преимуществами метода getOperations.
Важно!!! Метод getOperations не поддерживает опционы. Для получения информации по операциям с опционами мы рекомендуем использовать метод getOperationsByCursor.
Для вызова данных методов во входных параметрах достаточно указать только account_id.
Метод getOperations, в том числе, возвращает отменённые операции (параметр state), это нужно обязательно учитывать в алгоритме работы.
Важно!!! Метод getOperations возвращает только последнюю тысячу операций.
Команда TINKOFF INVEST API не рекомендует использовать метод получения операций для идентификации изменения статусов торговых поручений, т.к. некоторые операции могут происходить с задержкой относительно реального исполнения. Для получения статусов исполнения торговых поручений рекомендуется использовать соответствующий stream сервиса работы с торговыми поручениями.
На что нужно обратить внимание в методах получения списка операций
- id операций могут меняться со временем. Не стоит ориентироваться на id операций, как на первичный ключ. Если у вас есть потребность перезагрузить историю операций, при повторном запросе операции, рекомендуем старые id операции удалить.
- По инструментам, прошедшим корпоративные действия, история операций может быть не полной как в api, так и в мобильном приложении. Для получения точной информации рекомендуем воспользоваться брокерским отчетом.
Получение портфолио
Для получения торговым роботом текущего состояния портфеля по счёту используется метод getPortfolio. Данный метод в отличие от метода getPositions возвращает также статистическую информацию по портфелю (абсолютные и относительные доходности, текущую стоимость активов и т.п.).
Обратите внимание, что для расчёта суммарной стоимости активов используются текущие цены биржевых инструментов. Если торги в данный момент не ведутся, то берётся цена закрытия последней торговой сессии.
Важно!!! в данный момент запрос портфолио по счету инвесткопилки ( "type": "ACCOUNT_TYPE_INVEST_BOX") не доступен.
В данный метод добавлен булев параметр blocked, принимающий значение true, если инструмент заблокирован депозитарием.
Значения средних цен покупки инструментов (параметры average_position_price, average_position_price_pt и average_position_price_fifo) рассчитываются асинхронно. Возможна задержка в пересчёте до одной секунды.
Параметр average_position_price - Средневзвешенная цена позиции.
Параметр average_position_price_fifo - Средняя цена позиции по методу FIFO.
Более подробно о методах расчета с примерами можно почитать на сайте Тинькофф.
Получение списка позиций портфеля по счёту
Для принятия решений торговому роботу требуется получать список актуальных позиций в портфеле, т.е. количество ценных бумаг, валютных позиций по счёту, включая заблокированные средства. Для этого используется метод getPositions. Команда TINKOFF INVEST API рекомендует использовать именно этот метод, когда требуется получить актуальный список позиций, т.к. он является более быстрым и "лёгким" по сравнению с методом получения портфолио.
В данном методе также возвращается тип инструмента для списка ценно-бумажных позиций портфеля в параметре instrument_type.
В данный метод добавлен булев параметр exchange_blocked, принимающий значение true, если инструмент заблокирован депозитарием.
В метод getPositions добавлен массив опционов в портфеле.
Важно!!!. Данный метод не возвращает объём средств, заблокированных под гарантийное обеспечение фьючерсов. Для получения этой информации воспользуйтесь методом getWithdrawLimits.
Получение доступного остатка для вывода денежных средств
Метод getWithdrawLimits позволяет в удобном виде получить доступный для вывода баланс денежных средств, а также количество заблокированных валютных позиций.
Получение различных отчётов
TINKOFF INVEST API позволяет получать различные отчёты. Например, брокерский отчёт или справка о доходах за пределами РФ. Обратите внимание, что операции формирования отчётов достаточно трудоёмки, поэтому существуют ограничения на период формирования отчёта и лимиты на количество вызовов соответствующих методов. Запрос справки о доходах за пределами РФ работает корректно в случае, если верхний интервал запрашиваемых дат не позднее, чем 2 рабочих дня от текущей даты.
Стрим позиций и доходности портфеля
Для получения информации об изменении портфеля по факту совершения сделок также можно подписаться на gRPC server-side stream PortfolioStream. Стрим позиций и доходностей портфеля возвращает статистическую информацию по портфелю (абсолютные и относительные доходности, текущую стоимость активов и т.п.).
Средневзвешенная цена позиции, текущая рассчитанная доходность, текущая цена инструмента, средняя цена лота в позиции по методу FIFO - возвращаются в валюте инструмента.
Средняя цена лота в позиции в пунктах (для фьючерсов) - возвращает количество в пунктах.
Стрим изменения позиций портфеля
PositionsStream - gRPC server-side stream, предназначенный для получения информации по изменению позиций портфеля.
Стрим в качестве входного необязательного параметра принимает массив идентификаторов счетов, по которым вы хотите получать изменения позиций.
В качестве сообщений стрима приходят изменения позиций, объекты money, securities, futures, options, а также дата и время операции, изменившей позицию.
Торговые статусы инструментов и расписание торгов
Информацию о статусах инструментов и расписаниях торгов вы можете получить на странице Торговые статусы инструментов и расписание торгов.
Также рекомендуем смотреть актуальную информацию по режимам и статусам торгов на сайтах Московской биржи и СПБ биржи.