Экспериментальный API комбинаций

Комбинации (combos) позволяют торговать фиксированным соотношением опционных ног одной заявкой. При исполнении все обязательные ноги исполняются вместе. Ваши позиции при этом остаются позициями по отдельным опционам.

Экспериментальный контракт

Все эндпоинты /experimental и явно помеченные как экспериментальные сообщения WebSocket нестабильны. Несовместимые изменения могут вступать в силу с уведомлением за один день (24 часа), включая удаление или переименование полей и эндпоинтов, изменение типов полей и изменение поведения запросов или ответов. Изменения публикуются в журнале изменений API. Клиенты обязаны отслеживать эти уведомления и обновляться до указанного момента вступления изменений в силу. На существующие неэкспериментальные контракты API эта политика не распространяется.

Доступность зависит от вашей среды. Эта страница описывает экспериментальный интерфейс; она не объявляет о доступности в основной сети и не анонсирует новый интерфейс в торговом приложении.

Общие соглашения о подключении и подписи описаны в справочнике REST, руководстве по аутентификации и руководстве по WebSocket.

Поиск комбинации

Запрос	Результат
GET /experimental/combos	Ограниченная страница определений без наступившей экспирации, с необязательным фильтром по underlying
GET /experimental/combos/{symbol}	Одно определение без наступившей экспирации и разрешённые опционные ноги

Создание первой заявкой: если комбинация ещё не доступна для поиска, отправьте каноническое combo_definition вместе с POST /order. Первая принятая заявка публикует определение, в том числе если она исполняется сразу. Отклонённая заявка ничего не публикует. Отдельного эндпоинта для создания нет.

Срок доступности для поиска: определение остаётся доступным до экспирации первой из ног, даже если по нему нет активных заявок.

Пагинация: ответы содержат combos и next_cursor. Задайте limit от 1 до 1 000 (по умолчанию 100). Передайте полученный курсор как cursor в следующем запросе, сохранив тот же фильтр underlying. Курсор null означает, что следующих строк обнаружено не было. Недопустимые значения лимита или курсора возвращают HTTP 400.

GET /experimental/combos?underlying=BTC&limit=100
GET /experimental/combos?underlying=BTC&limit=100&cursor=<next_cursor>

Порядок на странице: сначала по ближайшей экспирации ноги, затем по ID комбинации. Считайте курсоры непрозрачными. Каждая страница отражает текущее состояние каталога; между запросами определения могут истекать или добавляться. Чтобы получить новые определения, которые сортируются раньше сохранённого курсора, используйте обновления о создании или запустите поиск заново.

Идентичность: символ имеет вид COMBO-, за которым следуют 64 шестнадцатеричных символа в нижнем регистре. Его ID, привязанный к содержимому, фиксирует инструменты ног и целочисленные соотношения со знаком. Значение существующего символа изменить нельзя.

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

Сторона, цена и размер

Для канонического определения с соотношениями +1 A, -1 B:

• Покупка одного пакета: купить один A и продать один B.
• Продажа одного пакета: продать один A и купить один B.
• Нетто-цена: price(A) - price(B), котируется за пакет.
• Лимит: покупка принимает нетто-цену на уровне лимита или ниже; продажа принимает нетто-цену на уровне лимита или выше.

Отрицательные и нулевые цены допустимы. Если A торгуется по $8, а B по$10, каноническая нетто-цена равна -2. Покупатель такого пакета получает $2 до комиссий. Продавец платит$2 до комиссий. При этом каждая реальная опционная нога исполняется по положительной цене.

Шаги заявки: размер пакета задаётся в контрактах с шагом 0.000001; лимитная нетто-цена имеет шаг 0.000001. Каждая исполненная нога также должна соответствовать собственным шагам количества и цены. Частичное исполнение сохраняет все соотношения и исполняет полное допустимое количество пакетов.

Комиссии: действуют существующие ставки и условия по каждой ноге, без скидки за пакет. Входящая заявка является тейкером по своим ногам с указанной в ней атрибуцией билдера. На маршруте исполнения аутрайт-заявки через комбинацию родительская заявка комбинации получает обычную тейкерскую атрибуцию комиссии по дополнительным поддерживающим ногам против поддерживающих аутрайт-мейкеров; у этих ног нет атрибуции билдера. Резервирование под активные заявки комбинаций консервативно учитывает потенциальные тейкерские комиссии по валовым суммам ног. Текущее исполнение в режиме Standard Margin требует нулевых торговых комиссий для исполнений через книгу заявок и RFQ; маршрут с участием SM-участника не может исполниться при ненулевых торговых комиссиях.

Маржа: биржа проверяет итоговые опционные позиции и оставшуюся экспозицию по заявкам для каждого счёта. Комбинация не объединяет обеспечение разных кошельков и не гарантирует какого-либо снижения маржинальных требований. Если уровень вашего счёта допускает только покрытые продажи опционов, активные аутрайт-заявки и ноги на продажу каждой родительской заявки комбинации используют один и тот же исполненный длинный инвентарь. Разные родительские заявки и раздельные исполнения не могут повторно использовать этот инвентарь; неисполненные ноги на покупку покрытия не добавляют.

Размещение заявки

Используйте существующий подписанный запрос POST /order с символом комбинации. Поля подписи заявки не меняются. Подписывайте ровно те строки symbol, size и price, которые отправляете, включая знак минус у отрицательной цены. Для новой комбинации добавьте её каноническое combo_definition, как описано ниже. Подписанный символ, привязанный к содержимому, фиксирует это определение; несовпадающее определение отклоняется. Для известных комбинаций его можно не указывать.

{
  "wallet": "<your wallet>",
  "symbol": "<discovered COMBO symbol>",
  "side": "Buy",
  "size": "1",
  "price": "-2",
  "tif": "gtc",
  "route": "best_execution",
  "client_id": "spread-001",
  "reduce_only": false,
  "mmp_enabled": false,
  "nonce": 1,
  "signature": "<signed order>"
}

Замените плейсхолдеры и nonce своими значениями. Цена приведена для иллюстрации и не является текущей рыночной котировкой.

Параметр	Поведение
route: "book_only"	Исполнение против доступной прямой и поддерживаемой имплицитной ликвидности, затем применяется срок действия заявки
route: "best_execution"	Рассматривается аукцион ценового улучшения для всего пакета, при необходимости с переходом к исполнению через книгу заявок
route: "rfq_only"	Отклоняется на /order
tif: "gtc"	Неисполненный остаток пакета остаётся в книге
tif: "ioc"	Неисполненный остаток отменяется
tif: "fok"	Исполняется всё запрошенное количество пакетов либо ничего

Ценовое улучшение сравнивает подписанную нетто-цену всего пакета с исполнимым референсом из книги на полный объём. Поставщики котировок должны котировать каждую ногу точно в запрошенном соотношении и количестве. Ранжировать котировку только по первой ноге недостаточно. В референс могут входить как прямая ликвидность по комбинации, так и поддерживаемые имплицитные маршруты. Если референс недоступен или неполон, заявка направляется на исполнение через книгу.

Допуск котировок: действуют также существующие правила комиссий для RFQ. Если любой из участников использует Standard Margin, исполнение через RFQ требует нулевых торговых комиссий. Котировка, не прошедшая проверки комиссий, обеспечения или точного распределения, оставляет исполнение на текущем пути через книгу; частичного исполнения её ног не происходит.

Имплицитное сопоставление может объединять комбинацию с поддерживающей аутрайт-ликвидностью по опционам. Например, аутрайт-заявка по A может атомарно исполниться против комбинации A минус B и ликвидности по B. Клиент, торгующий только A, не получает позиции по B.

Имплицитный поиск ограничен по ресурсам. Если аутрайт-заявка упирается в эти ограничения, поддерживающая ликвидность становится недоступной или необязательный маршрут не может отразить шаги аутрайт-заявки, она всё равно может исполниться против прямой книги заявок по опциону по обычным правилам. Поддержка комбинаций не меняет допустимые шаги количества и цены для аутрайт-заявок. Целевой опцион должен оставаться допущенным к торговле через книгу. Заявка комбинации, превышающая лимиты поиска, отклоняется без частичного распределения.

Текущие ограничения: нативные заявки комбинаций требуют mmp_enabled: false. Защищённые аутрайт-участники сохраняют MMP. Пакет, срабатывающий на пороге, завершает исполнение своих ног и останавливает дальнейшее сопоставление; незавершённая FOK-заявка или атомарная замена откатывает кандидата целиком. Заявки reduce-only пропускают аукцион ценового улучшения и проходят допуск через книгу, где каждая итоговая нога должна пройти проверки reduce-only. Активную комбинацию можно отменить по ID родительской заявки или клиентскому ID заявки через существующие эндпоинты отмены.

Замена: PUT /order может атомарно заменить родительскую заявку в рамках того же определения комбинации. При отклонении замены предыдущая заявка остаётся без изменений. Нативные записи в пакетной замене тоже используют одну атомарную команду на каждую родительскую заявку; сам пакет не является единой транзакцией по принципу «всё или ничего». Замена между комбинацией и аутрайт-заявкой или между разными определениями комбинаций отклоняется.

Предотвращение самоторговли: сопоставление останавливается до того, как маршрут исполнит сделку счёта с самим собой, и отменяет активную мейкерскую заявку. Ранее завершённые исполнения сохраняются, а остаток входящей заявки отменяется. Если ранее исполнений не было, входящая заявка отклоняется. FOK-заявки и неудавшиеся атомарные замены сохраняют поведение «всё или ничего», включая откат предварительных отмен мейкерских заявок.

Определение комбинации в первой заявке

Канонизируйте до подписи: объедините повторяющиеся ID инструментов, удалите нулевые соотношения, отсортируйте ID по числовому значению, разделите соотношения на их наибольший общий делитель и сделайте первое соотношение положительным. Если нормализация меняет знаки соотношений, поменяйте сторону заявки на противоположную и смените знак нетто-цены. Если она делит соотношения на множитель, умножьте размер пакета на этот множитель и разделите на него нетто-цену.

ID версии 1 вычисляется как Keccak-256 от следующей конкатенации:

UTF-8("hypercall:combo-definition\0")
|| version as unsigned 16-bit big-endian (1)
|| leg count as unsigned 16-bit big-endian
|| each sorted leg:
     instrument ID as 32 big-endian bytes
     ratio as signed 64-bit two's-complement big-endian

ID инструментов вычисляются как Keccak-256 от UTF-8 "instrument", за которым следует точный канонический символ опциона. Публикуемый ID комбинации представляет собой полный дайджест в виде 0x и 64 шестнадцатеричных символов в нижнем регистре. Символ комбинации использует те же шестнадцатеричные цифры после COMBO-.

Включите combo_definition в обычное подписанное тело POST /order. Определение содержит version, id и legs; каждая нога содержит instrument_id и ratio. Кодируйте ID как 0x и 64 шестнадцатеричные цифры в нижнем регистре, а соотношения как канонические десятичные строки со знаком, например "1" или "-1". Числа JSON, ведущие знаки плюс и ведущие нули в соотношениях отклоняются.

{
  "combo_definition": {
    "version": 1,
    "id": "<canonical content hash as 0x plus 64 hex digits>",
    "legs": [
      {"instrument_id": "<first canonical instrument ID>", "ratio": "1"},
      {"instrument_id": "<second canonical instrument ID>", "ratio": "-1"}
    ]
  }
}

Этот фрагмент добавляется к полному примеру заявки выше. Замените плейсхолдеры реальными ID и используйте соответствующий символ COMBO-. Дополнительной подписи определения и отдельного nonce публикации нет. Сервис проверяет каноническое содержимое и его соответствие подписанному символу; аутрайт-заявки не должны содержать combo_definition.

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

Чтение заявок и исполнений

Запрос	Назначение
GET /experimental/orders	Чтение заявок с явной классификацией инструментов, включая родительские заявки комбинаций
GET /experimental/trades	По умолчанию чтение реальных сделок по ногам, либо сводок по пакетам для одной комбинации с view=packages&symbol=<COMBO symbol>
GET /experimental/fills	По умолчанию чтение исполнений кошелька, либо сводок по пакетам кошелька с view=packages

Поддерживаемые фильтры и курсоры описаны в справочнике REST. Представления по пакетам листаются через limit (от 1 до 1 000, по умолчанию 100) и before_execution_id, а не offset: передайте полученный next_before_execution_id, чтобы получить следующую страницу. Сделки по пакетам требуют канонического symbol вида COMBO-; исполнения по пакетам принимают wallet и необязательный symbol. Сводки по пакетам являются группирующими записями: ID исполнений и ID сделок по ногам позволяют связать их с реальными исполнениями по опционам. Не прибавляйте количество, премию или комиссии пакета к исполнениям по составляющим при расчёте итогов по счёту.

Точность идентификаторов: экспериментальные ID заявок, ID исполнений пакетов, ID сделок и заявок составляющих, ID родительских заявок и курсоры пагинации пакетов передаются десятичными строками. Храните их в клиенте как строки; преобразование в числа JavaScript может привести к потере точности. Ответы устаревшего view=legs сохраняют прежнее представление.

Совместимость: устаревшие эндпоинты поиска инструментов и просмотра заявок сохраняют свой контракт для аутрайт-инструментов. Реальные исполнения по опционным ногам по-прежнему появляются в устаревших лентах сделок и исполнений, а позиции остаются опционными. Родительская заявка комбинации не является набором независимо активных заявок по ногам.

Явная подписка

Экспериментальные приватные каналы требуют существующего шага аутентификации WebSocket и явной подписки. Они публикуют только родительские записи аутентифицированного кошелька.

Канал	Сообщение	Аудитория
experimental_order_updates	ExperimentalOrderUpdate с ID родительской заявки, символом, типом инструмента (option, perp или combo), статусом, количеством, исполненным количеством и нетто-ценой	Аутентифицированный кошелёк
experimental_combo_trades	ComboTrade с ID исполнения, символом, количеством пакетов, нетто-ценой и ID сделок по ногам	Публичный
experimental_combo_fills	ComboFill с ID родительской заявки кошелька, стороной и исполнением пакета	Аутентифицированный кошелёк

{"type":"Subscribe","channel":"experimental_order_updates"}

ExperimentalOrderUpdate.status принимает значения Acked, Open, PartiallyFilled, Filled, Canceled или Rejected, а не значения в верхнем регистре, как в OrderUpdate. ID и количества передаются строками.

Подпишитесь на существующий канал книги заявок, используя найденный символ комбинации:

{"type":"Subscribe","channel":"orderbook","symbols":["<discovered COMBO symbol>"]}

Обновления каталога рынков могут повторять одно и то же неизменяемое определение; дедуплицируйте их по ID комбинации. Они приходят как MarketUpdate в market_updates с action: "ComboCreated", символом комбинации, ID, каноническими ногами и временной меткой. При сверке в клиенте рассматривайте данные каталога, статус родительской заявки, сводки исполнений пакетов и реальные исполнения по ногам как отдельные записи.