# Dzengi API Endpoint Research — marketData.subscribe

## Контроль документа

| Свойство | Значение |
|----------|----------|
| Документ | Dzengi API Endpoint Research — marketData.subscribe |
| Тип документа | Endpoint Research |
| Версия | 1.0 |
| Статус | Draft |
| Степень верификации | Runtime Research |
| Проект | Dzentra |
| Подсистема | Market Intelligence |
| Источник | Dzengi API |
| Endpoint | `marketData.subscribe` |
| Транспорт | WebSocket Stream |
| Язык | Русский |

---

## Статус документа

Настоящий документ содержит результаты исследования endpoint `marketData.subscribe`, выполненного посредством анализа официальной документации Dzengi и фактических сообщений, полученных от биржи.

Документ предназначен для определения информационных сущностей, передаваемых данным endpoint, без интерпретации состояния рынка.

---

## Цель исследования

Цель настоящего исследования — определить:

- назначение endpoint;
- структуру протокола обмена сообщениями;
- типы сообщений;
- семантику сообщений;
- информационные сущности, содержащиеся в сообщениях;
- особенности поведения потока данных;
- взаимосвязь с другими endpoint API Dzengi.

---

## Основной вопрос исследования

> **Какую информацию о состоянии рынка предоставляет поток `marketData.subscribe`?**

---

## Источники исследования

Исследование основано на:

- официальной документации Dzengi;
- OpenAPI (Swagger);
- официальных примерах сообщений;
- фактических сообщениях, полученных посредством Dzengi API Probe.

---

# 1. Назначение endpoint

## Описание документации

Согласно документации Dzengi, endpoint `marketData.subscribe` предназначен для получения потока рыночных котировок выбранных торговых инструментов.

---

## Назначение по результатам исследования

Исследование подтверждает, что `marketData.subscribe` является командой подписки на поток рыночных котировок.

После успешного выполнения подписки биржа начинает передавать поток сообщений с актуальными котировками выбранных инструментов.

Сам endpoint не является типом рыночного сообщения.

---

# 2. Способ получения данных

| Свойство | Значение |
|----------|----------|
| Транспорт | WebSocket Stream |
| Тип взаимодействия | Подписка |
| Endpoint | `marketData.subscribe` |
| Формат сообщений | JSON |

---

# 3. Параметры подписки

| Параметр | Тип | Обязательный | Назначение |
|----------|-----|--------------|------------|
| symbols | array | Да | Список торговых инструментов |

---

# 4. Протокол взаимодействия

Исследование показало, что взаимодействие состоит из двух независимых этапов.

```text
Клиент
      │
      │  marketData.subscribe
      ▼
Биржа
      │
      │  Subscription confirmation
      ▼
Биржа
      │
      │  internal.quote
      │  internal.quote
      │  internal.quote
      ▼
Клиент
```

Команда `marketData.subscribe` используется исключительно для оформления подписки.

Информация о состоянии рынка передается сообщениями другого типа — `internal.quote`.

---

# 5. Типы сообщений

## 5.1 Subscription confirmation

### Назначение

Подтверждение успешного оформления подписки.

### Пример сообщения

```json
{
    "correlationId": "probe-market-data-subscribe",
    "destination": "marketData.subscribe",
    "payload": {
        "subscriptions": {
            "BTC/USD_LEVERAGE": "PROCESSED"
        }
    },
    "status": "OK"
}
```

### Семантика

Сообщение подтверждает регистрацию подписки.

Рыночной информации не содержит.

---

## 5.2 Quote update (`internal.quote`)

### Назначение

Передача актуальных рыночных котировок.

### Пример сообщения

```json
{
    "destination": "internal.quote",
    "payload": {
        "bid": 62055.80,
        "bidQty": 5.0,
        "ofr": 62055.90,
        "ofrQty": 5.0,
        "symbolName": "BTC/USD_LEVERAGE",
        "timestamp": 1783537924352
    },
    "status": "OK"
}
```

---

# 6. Анализ структуры сообщения

| Поле | Тип | Изменяется | Назначение | Статус |
|------|-----|------------|------------|--------|
| bid | Number | Да | Лучшая цена покупки | Подтверждено |
| bidQty | Number | Да | Объем на лучшей цене покупки | Предварительно подтверждено |
| ofr | Number | Да | Лучшая цена продажи | Подтверждено |
| ofrQty | Number | Да | Объем на лучшей цене продажи | Предварительно подтверждено |
| symbolName | String | Нет | Торговый инструмент | Подтверждено |
| timestamp | Long | Да | Время формирования сообщения биржей | Подтверждено |

---

# 7. Информационные сущности, извлекаемые из сообщений

| Information ID | Источник (JSON Path) | Статус |
|----------------|----------------------|--------|
| best_bid_price | `payload.bid` | Подтверждено |
| best_bid_quantity | `payload.bidQty` | Предварительно подтверждено |
| best_ask_price | `payload.ofr` | Подтверждено |
| best_ask_quantity | `payload.ofrQty` | Предварительно подтверждено |
| instrument_symbol | `payload.symbolName` | Подтверждено |
| quote_timestamp | `payload.timestamp` | Подтверждено |

---

# 8. Поведение потока

## Подтвержденные наблюдения

- Подписка выполняется один раз.
- После подтверждения подписки биржа начинает передавать поток сообщений `internal.quote`.
- Каждое сообщение содержит полный набор исследованных полей.
- Сообщения поступают только при изменении котировки.
- Каждое сообщение относится к одному торговому инструменту.

---

## Требует дополнительного исследования

- Всегда ли `bidQty` соответствует объему первого уровня стакана.
- Всегда ли `ofrQty` соответствует объему первого уровня стакана.
- Возможны ли сообщения без изменения цены.
- Возможны ли сообщения с одинаковым `timestamp`.

---

# 9. Связь с другими endpoint

| Потенциальная информационная сущность | Endpoint | Поле | Статус |
|--------------------------------------|----------|------|--------|
| best_bid_price | REST `/api/v1/depth` | `bids[0][0]` | Подтверждено |
| best_bid_price | WSS `/api/v1/depth` | `payload.bids[0][0]` | Подтверждено |
| best_bid_price | `marketData.subscribe` | `payload.bid` | Подтверждено |
| best_ask_price | REST `/api/v1/depth` | `asks[0][0]` | Подтверждено |
| best_ask_price | WSS `/api/v1/depth` | `payload.asks[0][0]` | Подтверждено |
| best_ask_price | `marketData.subscribe` | `payload.ofr` | Подтверждено |
| best_bid_price | REST `/api/v1/ticker/24hr` | `bidPrice` | Требует исследования |
| best_ask_price | REST `/api/v1/ticker/24hr` | `askPrice` | Требует исследования |

---

# 10. Итоги исследования

По результатам исследования подтверждено, что endpoint `marketData.subscribe` не является источником отдельных запросов к бирже, а представляет собой механизм подписки на поток рыночных котировок.

Фактическая рыночная информация передается сообщениями типа `internal.quote`.

Исследование также подтвердило эквивалентность информационных сущностей `best_bid_price` и `best_ask_price`, получаемых посредством `marketData.subscribe`, REST `/api/v1/depth` и WSS `/api/v1/depth`.

Эквивалентность соответствующих полей endpoint `/api/v1/ticker/24hr` на момент подготовки настоящей редакции документа не подтверждена.

---

# 11. Связь с архитектурой Dzentra

Результаты настоящего исследования используются при формировании:

- Dzengi Market Intelligence Information Mapping;
- Dzentra Market Intelligence Information Model;
- Dzentra Market Knowledge Catalogue.

Настоящий документ не определяет:

- знания о рынке;
- интерпретацию состояния рынка;
- алгоритмы анализа;
- торговые стратегии;
- архитектуру Engine.