Експериментальний 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"	Зіставити доступну пряму та підтримувану імпліковану ліквідність, потім застосувати time in force
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 версії один є 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, канонічними ногами та часовою міткою. Під час звірки у клієнті розглядайте пошук, статус батьківської заявки, зведення виконань пакетів і фактичні виконання ніг як окремі записи.