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{bodyHash}

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;
• bodyHash, tam UTF-8 gövde baytlarının küçük harfli onaltılık SHA-256 değeridir — gövdesi olmayan isteklerde ise boş dizgedir;
• imzaladıktan sonra JSON'u yeniden seri hale getirmeyin.

Gövdesi olmayan bir istek, son bölümü boş olarak imzalar. Boş dizgeyi hash'lemeyin: SHA-256("") sabit ve boş olmayan bir özettir (e3b0c442…); sunucu sizinkinden farklı bir kanonik veri oluşturur ve imzayı reddeder. Bu, her GET ve DELETE için ve gövdesiz gönderilen bir POST için geçerlidir.

Yani GET /v1/balance tam olarak şunu imzalar — beş bölüm, sonuncusu boş ve dizge bir satır sonuyla biter:

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

İ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	4+nngnu7C6PVGfCs3zPJ34PWylIZdkdNSw8wmoywnTk=

{"client_request_id":"order-1042","address":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8","energy":65000,"duration_minutes":60,"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.