HMAC doğrulaması

GET /v1/time dışındaki tüm uç noktalar HMAC-SHA256 ister. API sırrı isteğe hiç eklenmez; kanonik istek verisini imzalamak için kullanılır.

Zorunlu başlıklar

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

Gövdesi olan isteklerde Content-Type: application/json da gönderin.

Kanonik istek verisi

{timestamp}\n{METHOD}\n{path}\n{query}\n{sha256_hex(body)}

Kurallar:

• METHOD büyük harftir;
• path yalnızca /v1/energy/orders gibi istek yolunu içerir;
• query, başındaki ? ile birlikte iletilen tam sorgu dizgesidir ya da boştur;
• gövde özeti, tam UTF-8 gövde baytlarının küçük harfli SHA-256 değeridir; gövde yoksa boştur;
• imzaladıktan sonra JSON'u yeniden seri hale getirmeyin.

İmza: base64(HMAC-SHA256(api_secret, canonical_payload)).

Node.js örneği

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

Sabit test vektörleri

1784376000 zaman damgasını ve rtn_sk_live_0123456789abcdefghijklmnopqrstuvwxyzABCDEFG sırrını kullanın.

İstek	Beklenen imza
GET /v1/balance	MAcY78Aad0bL9LGIJGMHR4plQ9jZH3TPUrYEJIMnSFY=
Aşağıdaki gövdeli POST /v1/energy/orders	8yz9fx4ShXCP/yYoVeu5L2veRg4JrTFixB+2ZYMyEQI=

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

Vektör eşleşmiyorsa canlı istek göndermeden önce seri hale getirmeyi, sorgu işlemesini veya satır sonlarını düzeltin.

Doğrulama hataları

Geçersiz şema, anahtar, imza, zaman damgası veya IP izin listesi hata biçiminde 401 döndürür. Tekrarlanan hatalarda 429 gelebilir; Retry-After değerine uyun.