Захист маркетмейкерів (MMP)

Ліміти у вікні виконань та поведінка автоматичного скасування для маркетмейкерів.

Огляд

MMP захищає маркетмейкерів від швидких несприятливих виконань шляхом:

1. Відстеження кумулятивних метрик виконань у ковзному часовому вікні
2. Скасування ордерів при порушенні лімітів
3. Автоматичного скасування всіх інших ордерів з увімкненим MMP для того самого гаманця + базового активу

Налаштування

Встановити конфігурацію MMP

Ендпоінт: POST /mmp-config

Запит: SetMmpConfigRequest

{
  "wallet": "0x...",
  "currency": "BTC",
  "interval_ms": 60000,
  "frozen_time_ms": 300000,
  "qty_limit": 1000000,
  "delta_limit": 10.0,
  "vega_limit": 5.0,
  "enabled": true,
  "nonce": 1,
  "signature": "0x..."
}

Поля:

• wallet: Адреса гаманця
• currency: Валюта базового активу (наприклад, "BTC", "ETH")
• interval_ms: Довжина ковзного вікна в мілісекундах
• frozen_time_ms: Тривалість заморожування після спрацювання (мілісекунди)
• qty_limit: Необов'язковий ліміт кількості (одиниці контрактів)
• delta_limit: Необов'язковий ліміт дельти
• vega_limit: Необов'язковий ліміт веги
• enabled: Чи ввімкнено MMP для цього гаманця + валюти

Відповідь: ApiResponse<MmpConfigData>

Отримати конфігурацію MMP

Ендпоінт: GET /mmp-config?wallet=...&currency=...

Параметри запиту:

• wallet (обов'язковий)
• currency (необов'язковий фільтр)

Відповідь: MmpConfigResponse

{
  "success": true,
  "data": [
    {
      "wallet_address": "0x...",
      "currency": "BTC",
      "interval_ms": 60000,
      "frozen_time_ms": 300000,
      "qty_limit": 1000000,
      "delta_limit": 10.0,
      "vega_limit": 5.0,
      "enabled": true
    }
  ]
}

Видалити конфігурацію MMP

Ендпоінт: DELETE /mmp-config

Запит: DeleteMmpConfigRequest

{
  "wallet": "0x...",
  "currency": "BTC",
  "nonce": 1,
  "signature": "0x..."
}

Відповідь: ApiResponse<String>

Скинути стан MMP

Ендпоінт: POST /mmp-config/reset

Запит: ResetMmpRequest

{
  "wallet": "0x...",
  "currency": "BTC",
  "nonce": 1,
  "signature": "0x..."
}

Відповідь: ApiResponse<String>

Примітки: Скидає стан вікна виконань MMP (очищає кумулятивні метрики, розморожує валюту).

Поведінка MMP (критично важливо розуміти)

Порядок обробки виконань

Оцінка MMP відбувається ПІСЛЯ ВИКОНАННЯ:

1. Рушій спочатку зіставляє та приймає виконання
2. Потім MMP перевіряє кумулятивні метрики
3. Якщо ліміти порушено:
   • MMP спрацьовує
   • Обробка залишкової кількості активного ордера зупиняється
   • Ордер отримує статус CANCELED з причиною: "MMP triggered during fill processing"
   • Рушій генерує подію MmpTriggered
   • Рушій автоматично скасовує всі інші відкриті ордери з увімкненим MMP для того самого гаманця + базового активу

Наслідок: Ви можете отримати виконання, які виведуть вас за налаштовані порогові значення, до того, як MMP спрацює.

Умови спрацювання

MMP спрацьовує, якщо порушено будь-який з налаштованих лімітів:

• Ліміт кількості: cumulative_qty > qty_limit
• Ліміт дельти: |cumulative_delta| > delta_limit
• Ліміт веги: |cumulative_vega| > vega_limit

Кумулятивні метрики обчислюються в межах ковзного вікна (interval_ms).

Поведінка скасування

Коли MMP спрацьовує:

1. Активний ордер: Обробка залишкової кількості зупиняється, ордер отримує статус CANCELED з причиною "MMP triggered during fill processing"
2. Інші ордери: Усі інші відкриті ордери з увімкненим MMP для того самого гаманця + базового активу автоматично скасовуються з причиною "Order canceled by MMP trigger"

Примітка: Скасовуються лише ордери з увімкненим MMP. Ордери з mmp_enabled=false не зачіпаються.

Поведінка заморожування

Після спрацювання MMP:

• Валюта заморожується на frozen_time_ms мілісекунд
• Під час заморожування нові виконання можуть бути відхилені (залежить від реалізації)

Розрахунок метрик виконань

Кількість

• Джерело: size виконання (одиниці контрактів)
• Кумулятивно: Сума всіх виконань у ковзному вікні

Дельта

• Джерело: Розраховується на основі символу виконання та GreeksCache
• Кумулятивно: Сума дельт усіх виконань у ковзному вікні

Вега

• Джерело: Розраховується на основі символу виконання та GreeksCache
• Кумулятивно: Сума вег усіх виконань у ковзному вікні

Ковзне вікно

Витіснення з вікна

Виконання, старші за interval_ms, автоматично витісняються з вікна:

• Витіснення виконується періодично (фонове завдання)
• Кумулятивні метрики зменшуються в міру видалення старих виконань

Скидання вікна

Скиньте стан MMP через POST /mmp-config/reset:

• Очищає всі виконання у вікні
• Скидає кумулятивні метрики до нуля
• Розморожує валюту

Події MMP

Подія MmpTriggered

Внутрішня подія (наразі не передається WS-клієнтам):

MmpTriggeredMessage {
    wallet: WalletAddress,
    currency: String,
    reason: String,  // "qty_limit" | "delta_limit" | "vega_limit"
}

Найкращі практики

Налаштування

1. Встановлюйте відповідні ліміти: На основі вашої толерантності до ризику та типових розмірів виконань
2. Використовуйте конфігурації для окремих валют: Налаштовуйте для кожного базового активу (BTC, ETH тощо)
3. Моніторте спрацювання MMP: Висока частота спрацювань може вказувати на неправильно налаштовані ліміти або несприятливі ринкові умови

Управління ордерами

1. Вмикайте MMP вибірково: Встановлюйте mmp_enabled=true лише для ордерів, які ви хочете захистити
2. Використовуйте узгоджену валюту: Переконайтеся, що всі ордери для одного базового активу використовують ту саму валюту в конфігурації MMP
3. Обробляйте скасування через MMP: Реалізуйте логіку виявлення скасувань, викликаних MMP, та коригування котирування

Моніторинг

1. Відстежуйте спрацювання MMP: Моніторте причини "MMP triggered during fill processing" та "Order canceled by MMP trigger"
2. Переглядайте вікна виконань: Перевіряйте кумулятивні метрики через конфігурацію MMP (наразі не доступно через API)
3. Коригуйте ліміти: Якщо MMP спрацьовує занадто часто — збільште ліміти; якщо занадто рідко — зменште

Поширені проблеми

MMP спрацьовує занадто часто

Причини:

• Ліміти занадто низькі для типових розмірів виконань
• Несприятливі ринкові умови
• Швидке котирування спричиняє багато виконань

Рішення:

• Збільште qty_limit, delta_limit або vega_limit
• Збільште interval_ms, щоб дозволити більше виконань у вікні
• Зменште частоту котирування

MMP не спрацьовує

Причини:

• Ліміти занадто високі
• MMP не ввімкнено на ордерах (mmp_enabled=false)
• Невідповідність валюти (валюта конфігурації MMP != базовий актив ордера)

Рішення:

• Зменште ліміти
• Перевірте, що на ордерах встановлено mmp_enabled=true
• Перевірте, що валюта конфігурації MMP відповідає базовому активу ордера

Неочікувані скасування

Симптом: Ордери скасовано з причиною "Order canceled by MMP trigger", але ви цього не очікували.

Причина: Інший ордер для того самого гаманця + базового активу спричинив спрацювання MMP.

Рішення: Переглядайте всі ордери з увімкненим MMP для того самого базового активу, коли один із них спрацьовує.