Сценарии использования

1) Интеграция обменника на сайт

Цель

добавить на сайт форму обмена с выбором валют/сетей, проверкой адреса и созданием заказа.

Эндпоинты

• v2: POST /api/v2/instruments/public/validate-address, POST /api/v2/instruments/public/one, GET /api/v2/instruments/public, POST /api/v2/orders/public/create, POST /api/v2/orders/public/set-email
• v1 (дополнительно при необходимости статусов/витрины): GET /api/v1/instruments/public, GET /api/v1/instruments/public/one, POST /api/v1/instruments/public/validate-address

Поток

1. Загрузить справочник активных инструментов (валюта+сеть) для построения списка «Отдаю/Получаю».
2. По выбору пользователя запросить детали инструмента «получаю» (точность, memo/tag, ограничения).
3. Провалидировать адрес назначения: validate-address.
4. Создать заказ: POST /api/v2/orders/public/create (рекомендуется v2). Сохранить orderId и показанный depositAddress пользователю.
5. (Опционально) добавить email к заказу: POST /api/v2/orders/public/set-email — для уведомлений пользователю.
6. Отобразить экран с инструкциями по оплате на depositAddress и таймером.

2) Получение и отображение курсов

Цель

показывать пользователю актуальные курсы для выбранной пары.

Эндпоинты

• v1: GET /api/v1/rates/public/one — публичный курс в JSON.

Поток

1. При выборе пары пользователем — запросить публичный курс через rates/public/one.
2. Отобразить курс, минимальную/максимальную суммы (если возвращаются), время актуальности.
3. (Опционально) применить визуальный «markup» к отображаемому курсу на витрине (см. сценарий 4), но не используйте скорректированный курс для фактического создания заказа в другой версии API.

3) Создание и отслеживание ордеров

Цель

создать заказ и предоставить пользователю понятный статус выполнения.

Эндпоинты

• v2: POST /api/v2/orders/public/create, POST /api/v2/orders/public/set-email
• v1: POST /api/v1/orders/public/create, GET /api/v1/orders/public-info, GET /api/v1/orders/public/latest, POST /api/v1/orders/public/accept-rate-mode-change, POST /api/v1/orders/public/request-refund, GET /api/v1/orders/order-refund-info

Поток (v2 — рекомендуемый для создания)

1. Провалидировать ввод и адрес назначения.
2. Создать заказ: v2/orders/public/create → получить orderId, depositAddress.
3. Предложить «Добавить email»: v2/orders/public/set-email.
4. Показать пользователю инструкции по внесению депозита.

Отслеживание статуса (витрина и кабинет пользователя)

• Витрина «последние обмены»: GET /api/v1/orders/public/latest.
• Детали конкретного заказа: GET /api/v1/orders/public-info?orderId=...&destinationAddress=... — массивы deposits/withdrawals, confirmations, txId, networkFee.
• Изменение режима курса по требованию: POST /api/v1/orders/public/accept-rate-mode-change.
• Возвраты: POST /api/v1/orders/public/request-refund → детали через GET /api/v1/orders/order-refund-info.

4) Проверка статуса транзакций

Цель

дать пользователю прозрачность по прогрессу депозита и вывода.

Эндпоинты

• v1: GET /api/v1/orders/public-info, GET /api/v1/orders/order-refund-info

Поток

1. Периодически опрашивать public-info по orderId и destinationAddress.
2. В блоке deposits[0] анализировать isPending, confirmations, txId, depositAddress.
3. Когда депозит подтверждён — отобразить информацию о выводе из массива withdrawals (сумма, networkFee, txId).
4. В случае возврата — получать детали через order-refund-info и показывать статус «Возврат в процессе/завершён».