🔑 Авторизация

Все приватные endpoints требуют подписи запроса и передачи публичного ключа.

📌 Заголовки для запроса

Каждый защищённый запрос должен содержать:

Заголовок	Описание
X-M-APIKEY	Публичный API ключ клиента
X-M-PAYLOAD	Payload запроса, закодированный в Base64
X-M-SIGNATURE	HMAC-SHA512 подпись payload приватным ключом

⚠️ Важно: payload всегда содержит nonce и request. Тело запроса (body) добавляется только для запросов с телом (POST, PUT, PATCH).

---

⚙️ Формирование payload

Структура payload

{
  "nonce": 1699981234567,
  "request": "v1/units/withdraw",
  "amount": 100, // body
  "currency": "USDT" // body
}

• nonce — уникальный идентификатор запроса. Обычно Date.now().

• request — путь эндпоинта без ведущего слеша (v1/units/withdraw).

• Остальные поля — параметры запроса (для POST, PUT, PATCH).

🔹 Для GET-запросов достаточно только nonce и request.

---

Канонизация полей

Перед отправкой payload на клиенте обязательно сортировать поля:

function preparePayload(payload: Record<string, any>) {
  const sorted: Record<string, any> = {};
  Object.keys(payload)
    .sort()
    .forEach((k) => (sorted[k] = payload[k]));
  return sorted;
}

Сервер проверяет порядок полей. Чтобы тело запроса не было перехвачено и не было изменено. Несоответствие приводит к ошибке 403 Invalid payload parameters.

---

Пример генерации заголовков

import crypto from 'crypto';

function signPayload(payload: string, secret: string): string {
  return crypto.createHmac('sha512', secret).update(payload).digest('hex');
}

function generateNonce(): string {
  return Date.now().toString();
}

function generateHeaders(apiKey: string, secret: string, body: Record<any, unknow>) {
  const payloadObj = {
    request: 'v1/units/withdraw',
    nonce: generateNonce(),
    ...body,
  };

  const canonicalPayload = preparePayload(payloadObj); // сортируем ключи
  const payloadStr = JSON.stringify(canonicalPayload);
  const payloadB64 = Buffer.from(payloadStr).toString('base64');
  const signature = signPayload(payloadB64, secret);

  return {
    headers: {
      'Content-Type': 'application/json',
      'X-M-APIKEY': apiKey,
      'X-M-PAYLOAD': payloadB64,
      'X-M-SIGNATURE': signature
    },
    payload: canonicalPayload
  };
}

---

⏱ Nonce

• nonce предотвращает повторные запросы (replay attack).

• Сервер проверяет уникальность и допустимое время запроса.

• Допустимое отклонение: ±5 минут.

• Ошибки при нарушении:

  • 403 Nonce not provided

  • 403 Replay detected

  • 403 Your nonce is more than X seconds greater or less than the current nonce

---

⚡ Рейтлимит

• Ограничение количества запросов за интервал времени.

• Идентификация пользователя через X-M-APIKEY или IP.

• Ошибка при превышении лимита: 429 Too Many Requests

{
  "statusCode": 429,
  "message": "Request limit exceeded. Please try again later."
}

---

❌ Возможные ошибки

Код	Ошибка	Описание
400	Invalid payload	Payload невалиден (не Base64 или некорректный JSON)
400	Request not provided	Поле request отсутствует в payload
401	Required headers not provided	Отсутствует один из заголовков (X-M-APIKEY, X-M-PAYLOAD, X-M-SIGNATURE)
401	Invalid API key	Недействительный апи-ключ
401	Invalid signature	HMAC-подпись не совпадает с payload
403	Request does not match the endpoint	Поле request не соответствует фактическому пути запроса
403	Invalid payload parameters	Параметры запроса или порядок ключей нарушен
403	Nonce not provided	Отсутствует nonce
403	Replay detected	Повторное использование nonce
403	Your nonce is more than X seconds greater or less than the current nonce	Время запроса слишком далеко от текущего времени сервера
403	You don’t have permission to use this endpoint	Недостаточно прав для выполнения операции
429	Request limit exceeded. Please try again later.	Превышен рейтлимит

---

🔗 Примеры запросов

GET

const payload = preparePayload({
  nonce: Date.now(),
  request: "v1/units"
});

const { data } = await axios.get("https://api.example.com/v1/units", {
  headers: generateHeaders(payload, API_KEY, SECRET_KEY);
});

POST