HMAC-Authentifizierung

Jeder Endpunkt außer GET /v1/time verlangt HMAC-SHA256. Das API-Secret wird nie übertragen; es signiert eine kanonische Nutzlast der Anfrage.

Erforderliche Header

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

Anfragen mit Body brauchen zusätzlich Content-Type: application/json.

Kanonische Nutzlast

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

Regeln:

• METHOD in Großbuchstaben;
• path enthält nur den Pfad der Anfrage, etwa /v1/energy/orders;
• query ist exakt die übertragene Query-Zeichenkette samt führendem ? oder leer;
• bodyHash ist der SHA-256 der exakten UTF-8-Bytes des Bodys in Kleinbuchstaben — und die leere Zeichenkette, wenn die Anfrage keinen Body hat;
• serialisieren Sie JSON nach dem Signieren niemals erneut.

Eine Anfrage ohne Body signiert ein leeres letztes Segment. Hashen Sie die leere Zeichenkette nicht: SHA-256("") ist ein fester, nicht leerer Digest (e3b0c442…), also baut der Server eine andere kanonische Nutzlast als Sie und weist die Signatur ab. Das gilt für jedes GET und DELETE und für ein POST ohne Body.

GET /v1/balance signiert also genau dies — fünf Segmente, das letzte leer, und die Zeichenkette endet mit einem Zeilenumbruch:

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

Die Signatur lautet base64(HMAC-SHA256(api_secret, canonical_payload)).

Umsetzung in 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');
}

Stabile Testvektoren

Verwenden Sie den Zeitstempel 1784376000 und das Secret rtn_sk_live_0123456789abcdefghijklmnopqrstuvwxyzABCDEFG.

Anfrage	Erwartete Signatur
GET /v1/balance	MAcY78Aad0bL9LGIJGMHR4plQ9jZH3TPUrYEJIMnSFY=
POST /v1/energy/orders mit dem Body unten	4+nngnu7C6PVGfCs3zPJ34PWylIZdkdNSw8wmoywnTk=

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

Stimmt ein Vektor nicht, korrigieren Sie Serialisierung, Query-Behandlung oder Zeilenumbrüche, bevor Sie produktiven Verkehr senden.

Fehlgeschlagene Authentifizierung

Ein falsches Schema, ein falscher Schlüssel, eine falsche Signatur, ein abweichender Zeitstempel oder eine gesperrte IP liefern 401 als Problem Details. Wiederholte Fehlversuche können 429 auslösen; halten Sie sich an Retry-After.