Аутентификация HMAC

Все методы, кроме GET /v1/time, требуют HMAC-SHA256. API-секрет никогда не передаётся в запросе: им подписывается каноническая строка.

Обязательные заголовки

Authorization: HMAC-SHA256 {api_key}:{base64_signature}
X-Request-Timestamp: {unix_seconds}

Для запросов с телом также передавайте Content-Type: application/json.

Каноническая строка

{timestamp}\n{METHOD}\n{path}\n{query}\n{bodyHash}

Правила без исключений:

• METHOD — в верхнем регистре;
• path — только путь, например /v1/energy/orders, без домена;
• query — точная строка параметров вместе с ведущим ? либо пустая строка;
• bodyHash — SHA-256 точных UTF-8 байтов тела в hex, строчными буквами, и пустая строка, если тела нет;
• после расчёта подписи JSON нельзя сериализовать повторно.

Запрос без тела подписывает пустой последний сегмент. Не хешируйте пустую строку: SHA-256("") — фиксированный непустой дайджест (e3b0c442…), сервер соберёт каноническую строку иначе, чем вы, и отклонит подпись. Это касается каждого GET и DELETE, а также POST, отправленного без тела.

То есть GET /v1/balance подписывает ровно это — пять сегментов, последний пустой, строка заканчивается переводом строки:

1784376000\nGET\n/v1/balance\n\n

Подпись — base64(HMAC-SHA256(api_secret, canonical_string)).

Реализация на Node.js

import crypto from 'node:crypto';

export function sign(secret, timestamp, method, path, query = '', body = '') {
  const bodyHash = body
    ? crypto.createHash('sha256').update(Buffer.from(body, 'utf8')).digest('hex')
    : '';
  const canonical = `${timestamp}\n${method.toUpperCase()}\n${path}\n${query}\n${bodyHash}`;
  return crypto.createHmac('sha256', secret).update(canonical, 'utf8').digest('base64');
}

Проверочные векторы

Используйте метку времени 1784376000 и секрет rtn_sk_live_0123456789abcdefghijklmnopqrstuvwxyzABCDEFG.

Запрос	Ожидаемая подпись
GET /v1/balance	MAcY78Aad0bL9LGIJGMHR4plQ9jZH3TPUrYEJIMnSFY=
POST /v1/energy/orders с телом ниже	4+nngnu7C6PVGfCs3zPJ34PWylIZdkdNSw8wmoywnTk=

{"client_request_id":"order-1042","address":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8","energy":65000,"duration_minutes":60,"expected_total_trx":"3.200000"}

Если вектор не совпадает, не отправляйте рабочий запрос: сначала исправьте сериализацию, строку параметров или переносы строк.

Ошибки авторизации

Некорректная схема, ключ, подпись, метка времени или список разрешённых IP-адресов возвращают 401 в формате ошибок. Серия неуспешных попыток может вернуть 429; соблюдайте Retry-After.