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

Статусная модель заявок

Метод выставления заявок

Одной из главных функций торгового робота, безусловно, является выставление на бирже заявок. Для решения этой задачи можно использовать unary-метод postOrder.

Unary-метод postOrder позволяет выставлять все типы заявок (рыночные, лимитные).

PostOrder принимает на вход параметр instrument_id - Идентификатор инструмента, принимает значения Figi или instrument_uid. Подробнее можно ознакомится на странице с информаций об идентификаторах.

Подробнее о торговых поручениях, их видах и особенностях исполнения на биржах можно почитать в статье: Работа с торговыми поручениями.

Важно! Для исключения дублирования заявок в процессе работы используется параметр order_id, который требуется сгенерировать любым удобным способом перед вызовом метода. Если сервис получит несколько запросов с одинаковым order_id, то на биржу выставится только одно торговое поручение. Все последующие запросы, содержащие существующий order_id, будут возвращать статус этого торгового поручения.

Важно! На данный момент мы имеем два параметра с одинаковым наименованием:

• order_id как входной параметр - ключ идемпотентности. Срок хранения ключа идемпотентности один год.
• order_id как выходной параметр - биржевой идентификатор заявки, используемый в дальнейшем для отслеживания статуса ордера.

При выполнении операций с облигациями следует также учитывать накопленный купонный доход. Размер НКД можно узнать при помощи параметра aci_value методов получения информации по облигациям или метода выставления торгового поручения. Обратите внимание, что в параметре aci_value возвращается размер НКД в валюте расчётов за 1 лот. Т.е. при покупке облигаций к стоимости сделки будет добавлено произведение НКД на количество лотов в сделке (aci_value*quantity), при продаже на это произведение сумма сделки будет уменьшена.

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

Рекомендация! Поскольку на данный момент нет возможности выставить заявку стоимостью свыше 6 млн через Tinkoff Invest API (потребуется подтверждение заявки по sms), необходимо разбивать заявки стоимостью свыше 6 млн на заявки меньшего размера.

Получение списка активных заявок по счёту

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

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

Несмотря на то, что статус исполнения поданного торгового поручения можно получить повторным вызовом метода выставления (с тем же параметром order_id), рекомендуется использовать для этих целей метод getOrderState. Данный метод возвращает, в том числе, стадии выполнения заявки (массив stages).

Важно! Метод получения статуса торгового поручения не предусмотрен для получения глубокой истории и может не возвращать информацию по поручениям "старше" одних суток.

Идентификатор ключа идемпотентности

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

Поэтому для этой операции выдвигается требование идемпотентности. Это свойство означает, что сколько бы раз операция не была вызвана, эффект будет одинаковым. В нашем примере, должно быть не важно, один раз был отправлен запрос или 10 – должен быть создан ровно один или ноль (в случае ошибки) ордеров.

Стандартный способ достичь этого свойства – генерация на стороне клиента ключа идемпотентности. Это просто некое уникальное значение. На стороне обработки запроса выполняется только та операция, ключ которой еще не встречался. Таким образом становится возможно делать retry безопасно.

Важно! В целях сохранения единообразия в запросах метода postOrder параметр order_id - ключ идемпотентности, передаваемый от клиента. А в ответах метода postOrder order_id - биржевой идентификатор заявки. Ключом идемпотентности, передаваемым от клиента, в ответах методов является параметр order_request_id. В параметр order_id запроса метода getOrderState необходимо передавать order_id из ответа метода postOrder, т.е. биржевой идентификатор заявки.

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

Отмена торгового поручения

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

Stream исполнения поручений пользователя

TINKOFF INVEST API предоставляет stream с трансляцией исполнения сделок. В данный стрим попадают все совершённые сделки по всем счетам пользователя.

Для сохранения стабильного подключения при отсутствии данных в stream-соединении сервером периодически отправляется ping-пакет. Клиенту реагировать на него нет необходимости.

Изменение выставленных заявок

Для изменения уже выставленных поручений в TINKOFF INVEST API добавлен метод replaceOrder.

Данный метод позволяет изменить существующую выставленную заявку, путем ее отмены и выставления новой заявки с измененными параметрами.

Для использования данного метода необходимо использовать идентификатор заявки на бирже, полученный при выставлении заявки с помощью Unary-метода postOrder.

Во время использования метода, могут произойти различные события на разных этапах исполнения. Так если ошибка произойдет из-за невозможности отмены поручения, то вернется ошибка с кодом 30059, и описание причины в message. В случаях если после отмены поручения невозможно выставить новое поручение, то вернется ошибка метода postOrder с соответствующим кодом и описанием. Все коды и описания ошибок вы можете найти в соответствующем разделе.

TradesStream - стрим совершенных сделок пользователя

В TINKOFF INVEST API представлен gRPC server-side TradesStream получения сделок с биржи. Стрим предназначен для получения событий по поручениям пользователя, по факту их исполнения. Использование TradesStream поможет в быстром получении информации об исполнении поручения, и выполненных сделках в рамках поручения, с отображением номера счета, на котором выполнилось поручение.

Для работы со стрим-соединениями также существуют ограничения, согласно лимитной политике

Торговые статусы инструментов и расписание торгов

Информацию о статусах инструментов и расписаниях торгов вы можете получить на странице Торговые статусы инструментов и расписание торгов.

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

Выставление заявок по опционам

На данный момент в TINKOFF INVEST API для работы с опционами доступны только лимитные заявки. Рыночная заявка, Тейк-профиты и стоп-заявки появятся совсем скоро.