Autenticación HMAC

Todos los endpoints salvo GET /v1/time requieren HMAC-SHA256. El secreto de API nunca se transmite: firma una carga canónica de la petición.

Cabeceras obligatorias

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

Las peticiones con cuerpo requieren además Content-Type: application/json.

Carga canónica

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

Reglas:

• METHOD en mayúsculas;
• path contiene solo la ruta de la petición, por ejemplo /v1/energy/orders;
• query es la cadena de consulta exacta que se transmite, incluida la ? inicial, o vacía;
• bodyHash es el SHA-256 en hexadecimal minúscula de los bytes UTF-8 exactos del cuerpo — y la cadena vacía cuando la petición no tiene cuerpo;
• nunca vuelvas a serializar el JSON después de firmarlo.

Una petición sin cuerpo firma un último segmento vacío. No calcules el hash de la cadena vacía: SHA-256("") es un resumen fijo y no vacío (e3b0c442…), así que el servidor construye una carga canónica distinta de la tuya y rechaza la firma. Esto vale para cada GET y DELETE, y para un POST enviado sin cuerpo.

Así que GET /v1/balance firma exactamente esto: cinco segmentos, el último vacío, y la cadena termina en un salto de línea:

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

La firma es base64(HMAC-SHA256(api_secret, canonical_payload)).

Implementación en 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');
}

Vectores de prueba estables

Usa la marca de tiempo 1784376000 y el secreto rtn_sk_live_0123456789abcdefghijklmnopqrstuvwxyzABCDEFG.

Petición	Firma esperada
GET /v1/balance	MAcY78Aad0bL9LGIJGMHR4plQ9jZH3TPUrYEJIMnSFY=
POST /v1/energy/orders con el cuerpo de abajo	4+nngnu7C6PVGfCs3zPJ34PWylIZdkdNSw8wmoywnTk=

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

Si un vector no coincide, corrige la serialización, el tratamiento de la cadena de consulta o los saltos de línea antes de enviar tráfico de producción.

Fallos de autenticación

Un esquema, una clave, una firma, una marca de tiempo o una lista de IP no válidos devuelven 401 como Problem Details. Los fallos repetidos pueden devolver 429; respeta Retry-After.