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 是实际发送的完整查询字符串，包含开头的 ?；没有查询时为空；
• 请求体哈希是对原始 UTF-8 字节计算出的 SHA-256 摘要的小写十六进制值；没有请求体时为空；
• 签名完成后不要重新序列化 JSON。

签名为 base64(HMAC-SHA256(api_secret, canonical_payload))。

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。