# Dzengi Market Intelligence Information Mapping

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

| Свойство | Значение |
|----------|----------|
| Документ | Dzengi Market Intelligence Information Mapping |
| Тип документа | Information Mapping |
| Версия | 1.0 |
| Статус | Draft |
| Степень верификации | Documentation Based |
| Проект | Dzentra |
| Подсистема | Market Intelligence |
| Источник | Dzengi API |
| Язык | Русский |

---

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

Настоящий документ определяет соответствие между техническими данными, предоставляемыми API Dzengi, и информационными сущностями подсистемы Market Intelligence.

Документ построен на основании **Dzengi Market Data Inventory** и не содержит интерпретации состояния рынка.

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

---

## Степень верификации

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

- Dzengi Market Data Inventory;
- официальной документации Dzengi;
- OpenAPI (Swagger);
- официальных примеров запросов;
- официальных примеров ответов.

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

По этой причине:

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

Настоящий документ имеет статус **Documentation Verified**.

После проверки информационных сущностей посредством выполнения реальных запросов и анализа фактических ответов API документ получит статус **Runtime Verified**.

Все расхождения между документацией и фактическим поведением API должны фиксироваться в последующих редакциях настоящего документа.

---

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

Настоящий документ предназначен для формирования единого слоя информационных сущностей Market Intelligence на основании возможностей API Dzengi.

Документ определяет:

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

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

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

---

## Цель

Цель настоящего документа — сформировать полный каталог информационных сущностей, потенциально доступных подсистеме Market Intelligence при использовании API Dzengi.

---

## Основной вопрос документа

Настоящий документ отвечает исключительно на следующий вопрос.

> **Какие информационные сущности Market Intelligence могут быть получены или автоматически вычислены на основании данных Dzengi API?**

---

## Источник информации

Настоящий документ построен на основании следующих источников.

- Dzengi Market Data Inventory;
- REST API Documentation;
- WebSocket Request API Documentation;
- WebSocket Stream API Documentation;
- OpenAPI (Swagger) Specification;
- официальных примеров запросов;
- официальных примеров ответов.

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

---

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

Настоящий документ является вторым уровнем архитектуры знаний подсистемы Market Intelligence.

```text
Dzengi API
        │
        ▼
Dzengi Market Data Inventory
        │
        ▼
Dzengi Market Intelligence Information Mapping
        │
        ▼
Dzentra Market Intelligence Information Model
        │
        ▼
Dzentra Market Knowledge Catalogue
```

---

## Границы документа

Настоящий документ описывает исключительно информационные сущности, относящиеся к подсистеме Market Intelligence.

Документ не содержит:

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

---

## Термины и определения

*Derived* — информация, автоматически вычисляемая на основании одной или нескольких информационных сущностей.

*Endpoint* — операция API, предоставляющая доступ к данным или сервису.

*Information ID* — канонический идентификатор информационной сущности, используемый во всей платформе Dzentra.

*JSON Path* — путь к полю внутри JSON-ответа API.

*Observed* — информация, непосредственно получаемая из внешнего источника данных без дополнительных вычислений.

---

## Правила Mapping

---

## Стандарт спецификации информационной сущности

Все информационные сущности настоящего документа описываются по единому шаблону.

```text
### <information_id>

#### Определение

...

#### Тип информации

Observed | Derived

#### Источники информации

| Endpoint | Поле ответа (JSON Path) | Контекст получения |
|----------|-------------------------|--------------------|

#### Зависимости

...

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

...

#### Примечания

...
```

---

## Содержание

---

## Информационные сущности

### best_ask_price

#### Определение

Лучшая доступная цена продажи (Ask) финансового инструмента в текущем состоянии рынка.

#### Тип информации

Observed

#### Статус исследования

🟡 Частично подтверждено.

#### Подтвержденные источники

| Транспорт | Endpoint | Поле ответа (JSON Path) |
|-----------|----------|-------------------------|
| REST | `/api/v1/depth` | `asks[0][0]` |
| WSS Request | `/api/v1/depth` | `payload.asks[0][0]` |
| WSS Stream | `marketData.subscribe` | `payload.ofr` |

#### Исследуемые источники

| Транспорт | Endpoint | Поле ответа (JSON Path) | Статус |
|-----------|----------|-------------------------|--------|
| REST | `/api/v1/ticker/24hr` | `askPrice` | Требует подтверждения эквивалентности |

#### Зависимости

Отсутствуют.

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

> **Не определяется настоящим документом.**

#### Примечания

Настоящая информационная сущность формируется по результатам исследования фактических ответов API Dzengi.

Подтверждено, что REST `/api/v1/depth`, WSS Request `/api/v1/depth` и WSS Stream `marketData.subscribe` предоставляют одну и ту же информацию о лучшей цене продажи, отличаясь только способом получения данных.

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