Использование

Описание всех текущих методов API и параметров их вызова доступно по адресу https://trade-api.finam.ru/swagger/index.html. Там же можно выполнить запросы по токену прямо в браузере.

Все методы можно разделить на группы. Далее идет описание групп и основных методов.

Важно: Все запросы к нашему API должны включать обязательный заголовок "User-Agent" для повышения безопасности и эффективности обработки. Убедитесь, что ваше приложение отправляет уникальный и специфичный "User-Agent", иначе запросы будут отклонены.

Адреса подключения:

• gRPC: trade-api.finam.ru:443
• RestAPI: https://trade-api.finam.ru

Авторизация

Для выполнения методов API необходимо передавать токен доступа в каждом запросе.

Формат заголовка: Authorization: Bearer <токен_доступа>.

Рыночная информация

Сюда относятся методы получения текущей рыночной информации:

• Получение информации о доступных инструментах и их параметрах GET ​/api​/v1​/securities;
• Получение информации об истории торгов по инструменту (график);
• Получение потоковой информации market data. Реализовано в виде методов подписки на события. Можно подписываться на следующие события:
  • биржевой стакан,
  • заявки,
  • сделки.

Клиентский счет

Trade API позволяет получить доступ только к Единым счетам, открытым в АО "Финам". Оперирование идет по торговому коду, который вы видите в ИТС TRANSAQ. Торговый код необходимо использовать в поле ClientID.

Сюда относятся методы:

• Получения текущего состояния счета GET ​/api​/v1​/portfolio;
• Получение информации о заявках GET ​/api​/v1​/orders или стоп-заявках GET ​/api​/v1​/stops по счетам;
• Получение информации о сделках по счетам.

Торговые операции

Сюда относятся методы:

• Выставить новую заявку (рыночную / лимитированную условную) по счету POST ​/api​/v1​/orders;
• Отменить заявку DELETE ​/api​/v1​/orders или стоп-заявку DELETE ​/api​/v1​/stops.

На обработку нового поручения по размещению заявки в биржевой стакан требуется некоторое время, поэтому этот метод возвращает структуру с transaction_id, которая может быть использована для поиска соответствующей заявки через GetOrdersRequest или в сообщении OrderEvent от сервиса событий (EventResponse.event.order).

Справка

transaction_id - это целочисленный номер, который однозначно идентифицирует транзакцию внутри текущего сеанса связи с сервером.

После того как в результате транзакции на Бирже появится соответствующий объект (заявка), основным идентификатором этого объекта становится регистрационный номер Биржи. Transaction_id является также основным идентификатором условной заявки (результата транзакции) до тех пор, пока заявка не будет выставлена на Биржу и не приобретёт регистрационный номер Биржи.

Значения property:

• PutInQueue: неисполненная часть заявки помещается в очередь заявок Биржи;
• FOK: сделки совершаются только в том случае, если заявка может быть удовлетворена полностью;
• IOC: неисполненная часть заявки снимается с торгов;
• Для выставления рыночной заявки достаточно указать в поле price значение 0.

Допустимые типы условия условных заявок:

• Bid: лучшая цена покупки;
• BidOrLast: лучшая цена покупки или сделка по заданной цене и выше;
• Ask: лучшая цена продажи;
• AskOrLast: лучшая цена продажи или сделка по заданной цене и ниже;
• CovDown: обеспеченность ниже заданной;
• CovUp: обеспеченность выше заданной;
• LastUp: сделка на рынке по заданной цене или выше;
• LastDown: сделка на рынке по заданной цене или ниже.

Такие поля как, например, condition или validbefore являются необязательными. Их можно не указывать в запросе.

Для отмены заявки нужно также указать transaction_id.

Стоп-заявки

Cтоп-заявка в системе TRANSAQ (или cтоп) — это распоряжение, предписывающее серверу TRANSAQ выполнить в автоматизированном режиме транзакционные действия, реализующие логику стоп-лосс или тейк-профит в зависимости от ценовых условий на рынке.

Основное предназначение стоп-заявок — автоматизировать управление существующей или потенциальной позицией клиента, которое заключается в своевременном выполнении одного из следующих действий:

• своевременно закрыть позицию при неблагоприятном изменении цены, ограничив убытки заранее определённой величиной (исполнить стоп-лосс);
• зафиксировать прибыль после достижения ценой достаточно прибыльного уровня при возникновении признаков окончания благоприятного тренда (исполнить тейк-профит).

Cтоп-заявки могут также с успехом применяться для автоматизированного открытия новой позиции при определённых условиях, например, при возникновении признаков смены тренда или, наоборот, для открытия позиции «по тренду».

Стоп-заявка состоит из двух частей:

• Стоп-лосс (далее — SL),
• Тейк-профит (далее — TP).

При выполнении условия для одной части стоп-заявки вторая ее часть снимается. Вторая часть стоп-заявки снимается даже в том случае, если попытка выставить заявку на Биржу при исполнении оказалась неуспешной. Допускаются стоп-заявки, содержащие только одну часть (SL или TP). Для закрытия коротких позиций следует выставлять стопы на покупку, для закрытия длинных позиций - стопы на продажу. Обе части стоп-заявки допускают использование признака «по рынку».

Cтоп-лосс

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

• для стопа на продажу часть SL активируется, когда цена на рынке станет меньше либо равна цене активации стоп-лосса;
• для стопа на покупку часть SL активируется, когда цена на рынке станет больше либо равна цене активации стоп-лосса.

При выставлении SL необходимо задать цену активации и цену заявки, которая будет отправлена на Биржу при достижении рынком цены активации.

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

Защитное время задаётся в целых секундах и отсчитывается от времени получения сервером первой сделки, удовлетворяющей цене активации. Если в течение защитного времени на рынке будут зафиксированы сделки, не подтверждающие наступление уровня цены активации (т.е. сделки по цене выше цены активации для SL на продажу, либо по цене ниже цены активации для SL на покупку), то стоп-лосс возвращается в состояние «Ожидает активации».

Если защитное время не задано, то даже одна сделка на рынке по цене, удовлетворяющей цене активации, приводит к исполнению стоп-лосса.

Тейк-профит

TP предназначен для закрытия позиций с фиксацией прибыли. Следовательно:

• для стопа на продажу часть TP активируется, когда цена на рынке станет больше либо равна цене активации;
• для стопа на покупку часть TP активируется, когда цена на рынке станет меньше либо равна цене активации.

Простой TP

Для ввода простого TP достаточно задать цену активации и количество.

В этом случае на Биржу будет отправлена заявка с ценой, равной цене первой же сделки на рынке, которая удовлетворяет цене активации.

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

Для простого TP также можно установить защитное время (см. выше описание SL).

При использовании защитного времени в качестве цены рынка (от которой определяется цена заявки, исполняющей TP) принимается цена последней по времени сделки, полученной сервером в течение защитного времени.

Следящий (trailing) TP

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

Для того чтобы включить механизм отслеживания тренда, необходимо при выставлении TP задать значение поля коррекция.

Это значение используется сервером TRANSAQ для определения момента окончания благоприятного тренда следующим образом:

• для TP на продажу считается, что растущий тренд заканчивается в тот момент, когда после того, как рынок вырос до уровня цены активации или выше, он снизится на величину коррекции от максимальной цены;
• для TP на покупку считается, что нисходящий тренд заканчивается в тот момент, когда после того, как рынок снизился до уровня цены активации или ниже, он вырастет на величину коррекции от минимальной цены; Величина коррекции может быть задана как в виде абсолютного изменения цены, так и в виде процента от цены. Для следящего TP также могут быть заданы защитный спрэд и/или защитное время.

Если для следящего TP задано защитное время, то оно действует как при определении факта достижения цены активации, так и при определении факта окончания тренда (достижения заданного уровня коррекции).

Связанные заявки

Любая стоп-заявка может иметь «связь по исполнению» с активной заявкой на бирже. Такая связь означает, что действие стоп-заявки начнётся не с момента её ввода в TRANSAQ, а в тот момент, когда соответствующая активная заявка исполнится (или частично исполнится) на Бирже. «Связь по исполнению» удобно применять в тех случаях, когда необходимо обеспечить стоп-процессинг для позиции, которая ещё не открыта, но может быть открыта при исполнении активной заявки.

Несколько стоп-заявок могут иметь связь по исполнению с одной и той же активной заявкой. Это позволяет организовать ступенчатое закрытие позиции частями на разных ценовых уровнях в заданных пропорциях.

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

При вводе связанного стопа его направление (покупка/продажа) устанавливается противоположным направлению активной заявки.

Инструмент, Режим и Клиент также копируются из активной заявки, но при необходимости могут быть изменены.

Если в момент ввода связанного стопа заявка уже исполнена (в т.ч. частично), то он сразу переходит в состояние ожидания активации.

Связь по исполнению может быть использована как способ автоматизации торговых операций в одном финансовом инструменте по условию цены в другом инструменте. Выставляется «триггерная» заявка на минимальный объём в индикативном инструменте и к ней привязывается стоп по исполнению, открывающий или закрывающий позицию в торговом инструменте. К этой же «триггерной» заявке можно привязать стоп, который автоматически закроет позицию, возникшую при ее исполнении.