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

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

Выставить заявку

Одна из главных функций торгового робота — выставление заявок на бирже.

Для этого можно использовать unary-метод 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 нелья — её нужно подтверждать по СМС. Поэтому мы рекомендуем разбивать такие заявки на заявки меньшего размера.

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

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

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

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

Несмотря на то, что статус исполнения поданного торгового поручения можно получить через повторный вызов метода postOrder с тем же параметром order_id, мы рекомендуем использовать метод getOrderState. Помимо статуса он возвращает стадии выполнения заявки — массив stages.

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

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

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

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

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

Важно
Для сохранения единообразия параметр order_id означает:

• В запросах метода postOrder — ключ идемпотентности, передаваемый от клиента.
• В ответах метода postOrder — биржевой идентификатор заявки.

В ответах других методов ключ идемпотентности, который передаётся клиентом, — это параметр order_request_id.

В запросе метода getOrderState в параметре order_id нужно передавать order_id из ответа метода postOrder — то есть биржевой идентификатор заявки.

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

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

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

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

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

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

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

Изменить выставленную заявку

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

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

Во время использования метода на этапах исполнения могут произойти разные события, и вернётся ошибка. Например:

• Если поручение нельзя отменить, вернётся ошибка с кодом 30059 и описанием причины в message.
• Если после отмены поручения нельзя выставить новое, вернётся ошибка метода postOrder с соответствующим кодом и описанием.

Все коды и описания ошибок

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

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

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

Для работы со стрим-соединениями есть ограничения.

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

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

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

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

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