Аутентификация 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{sha256_hex(body)}

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

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

Подпись — 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 с телом ниже	8yz9fx4ShXCP/yYoVeu5L2veRg4JrTFixB+2ZYMyEQI=

{"client_request_id":"order-1042","address":"TXYZ","energy":65000,"duration_hours":1,"expected_total_trx":"3.200000"}

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

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

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