Быстрый старт: первая заявка

Эта инструкция показывает минимальный путь от API-ключа до созданной заявки. Все примеры используют https://example.com/api/v3. Замените домен на домен вашего обменника.

Что должно быть готово

Перед началом у вас должны быть:

Что	Где получить
Домен обменника	У владельца обменника или администратора.
Bearer-токен	Клиент создает в личном кабинете.
HMAC-секрет	Показывается при создании ключа, если HMAC включен.
Scopes	Настраивает администратор.

1. Проверить, что API отвечает

Запрос:

curl -sS https://example.com/api/v3/ping \
  -H "Accept: application/json"

Пример ответа:

{
  "state": 0,
  "message": "OK",
  "result": {
    "status": "ok",
    "time": "2026-06-23T10:00:00+00:00"
  },
  "meta": {
    "request_id": "req_01J...",
    "correlation_id": "cor_01J...",
    "timestamp": "2026-06-23T10:00:00+00:00"
  }
}

Если этот запрос не работает, проблема не в ключе. Проверьте домен, nginx, HTTPS и путь /api/v3.

2. Проверить API-ключ

Запрос:

curl -sS https://example.com/api/v3/private/health/client \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Пример ответа:

{
  "state": 0,
  "message": "OK",
  "result": {
    "client": {
      "status": "active",
      "api_access": true
    },
    "token": {
      "status": "active",
      "hmac_required": false
    }
  }
}

Если ответ 401, проверьте токен. Если 403, проверьте, включил ли администратор API клиенту, scopes и белый список IP.

3. Получить валюты и платежные системы

Сначала получите, что пользователь может отдать:

curl -sS "https://example.com/api/v3/private/exchange/payment-systems?filter[side]=give" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Затем получите, что пользователь может получить:

curl -sS "https://example.com/api/v3/private/exchange/payment-systems?filter[side]=receive" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Пример элемента ответа:

{
  "id": 1,
  "currency_code": "USDT",
  "network": "TRC20",
  "payment": "Tether",
  "side": "give"
}

4. Найти направление обмена

Допустим, пользователь выбрал from_currency_id=1 и to_currency_id=2.

curl -sS "https://example.com/api/v3/private/exchange/routes?filter[from_currency_id]=1&filter[to_currency_id]=2" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

В ответе найдите id направления. В следующих примерах используется route_id = 25.

5. Узнать, какие поля нужны для заявки

curl -sS https://example.com/api/v3/private/exchange/routes/25/capabilities \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Смотрите в ответе:

Поле	Что означает
available	Можно ли сейчас создать заявку по направлению.
amounts.min / amounts.max	Минимальная и максимальная сумма.
fields	Какие поля нужно показать пользователю.
requirements	Нужна ли верификация или файл.
rate_modes	Доступен ли fixed/floating курс.

6. Рассчитать обмен

curl -sS https://example.com/api/v3/private/exchange/quotes \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "route_id": 25,
    "amount": "100",
    "type_rate": "fixed"
  }'

Пример ответа:

{
  "state": 0,
  "message": "OK",
  "result": {
    "quote": {
      "route_id": 25,
      "amount": "100",
      "receive_amount": "0.00102",
      "rate": "0.00001020",
      "type_rate": "fixed"
    }
  }
}

Покажите пользователю расчет, но не считайте это созданной заявкой.

7. Проверить заявку перед созданием

curl -sS https://example.com/api/v3/private/exchange/orders/preflight \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "route_id": 25,
    "amount": "100",
    "income_account": "FROM-REQUISITE",
    "outcome_account": "TO-REQUISITE",
    "type_rate": "fixed"
  }'

Если не хватает данных, API вернет список:

{
  "state": 0,
  "message": "OK",
  "result": {
    "can_create_order": false,
    "missing_fields": [
      {
        "name": "outcome_account",
        "label": "Receive wallet"
      }
    ]
  }
}

Если все хорошо:

{
  "state": 0,
  "message": "OK",
  "result": {
    "can_create_order": true
  }
}

8. Создать заявку

Для создания заявки всегда передавайте Idempotency-Key. Это защитит от дубля, если запрос повторится из-за timeout.

curl -sS https://example.com/api/v3/private/exchange/orders \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: create-order-user-42-001" \
  -d '{
    "route_id": 25,
    "amount": "100",
    "income_account": "FROM-REQUISITE",
    "outcome_account": "TO-REQUISITE",
    "type_rate": "fixed"
  }'

Пример ответа:

{
  "state": 0,
  "message": "OK",
  "result": {
    "order": {
      "id": 913,
      "public_id": "EX-000913",
      "tracking_id": "TRK8K2LQ",
      "status": "created",
      "amount": "100",
      "receive_amount": "0.00102"
    }
  }
}

Сохраните id, public_id, tracking_id и status.

9. Проверить статус заявки

curl -sS https://example.com/api/v3/private/exchange/orders/TRK8K2LQ/status \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Для production лучше получать статусы через webhooks, а status endpoint использовать как fallback.

API Reference

Точные параметры и схемы этих запросов доступны в API Reference:

• Exchange API Reference
• Orders API Reference
• Webhooks API Reference