Аутентификация

Каждый аутентифицированный запрос подписывается секретом вашего API-ключа. Сам секрет никогда не передается по сети: сервер заново вычисляет подпись из тех же байтов запроса и сверяет результат.

Перед началом работы

API-ключ предназначен исключительно для машинного взаимодействия: никогда не используйте его в коде веб-страниц. Ключ можно создать до внесения первого депозита, чтобы ваш сервис мог получить адрес пополнения (GET /v1/deposit-addresses) и пополнить баланс самостоятельно; до поступления средств заказы будут отклоняться с ошибкой 4001 insufficient_funds. Секрет ключа отображается ровно один раз при создании — сохраните его в надежном месте.

Три заголовка запроса

Каноническая строка (Canonical string)

canonical_string = timestamp + METHOD + path + query + body

Никаких разделителей между частями нет. Сериализуйте тело запроса один раз и отправляйте именно эти байты: подписание форматированного JSON с отступами и отправка компактного JSON — самая частая причина ошибки 1002 invalid_signature.

Шаг 1 — Сформируйте и подпишите строку

Пример подписания запроса GET /v1/balance с секретом sk_test_example во время 2026-09-11T18:04:05.123Z:

2026-09-11T18:04:05.123ZGET/v1/balance

TS=2026-09-11T18:04:05.123Z
printf '%s' "${TS}GET/v1/balance" | openssl dgst -sha256 -hmac "sk_test_example" -binary | base64

import { createHmac } from "node:crypto";

const ts = "2026-09-11T18:04:05.123Z";
const sign = createHmac("sha256", "sk_test_example").update(`${ts}GET/v1/balance`).digest("base64");
console.log(sign);

import base64, hashlib, hmac

ts = "2026-09-11T18:04:05.123Z"
digest = hmac.new(b"sk_test_example", f"{ts}GET/v1/balance".encode(), hashlib.sha256).digest()
print(base64.b64encode(digest).decode())

Во всех трех случаях вывод будет идентичен: zqttXJ133TRJ7aj14dJ3jamfeCG2mDj+TbNPrrBJl2g=. Сверьтесь с этим значением перед отладкой других параметров.

Шаг 2 — Отправьте запрос

TS=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
SIGN=$(printf '%s' "${TS}GET/v1/balance" | openssl dgst -sha256 -hmac "$TENERGY_SECRET" -binary | base64)
curl -s https://api-nile.tenergy.me/v1/balance \
  -H "X-API-KEY: $TENERGY_KEY" -H "X-API-TIMESTAMP: $TS" -H "X-API-SIGN: $SIGN"

import { createHmac } from "node:crypto";

const ts = new Date().toISOString();
const sign = createHmac("sha256", process.env.TENERGY_SECRET!)
  .update(`${ts}GET/v1/balance`)
  .digest("base64");
const res = await fetch("https://api-nile.tenergy.me/v1/balance", {
  headers: { "X-API-KEY": process.env.TENERGY_KEY!, "X-API-TIMESTAMP": ts, "X-API-SIGN": sign },
});
console.log(res.status, await res.json());

import base64, hashlib, hmac, json, os, urllib.error, urllib.request
from datetime import datetime, timezone

ts = datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
sign = base64.b64encode(hmac.new(os.environ["TENERGY_SECRET"].encode(),
                                 f"{ts}GET/v1/balance".encode(), hashlib.sha256).digest()).decode()
req = urllib.request.Request("https://api-nile.tenergy.me/v1/balance", headers={
    "X-API-KEY": os.environ["TENERGY_KEY"], "X-API-TIMESTAMP": ts, "X-API-SIGN": sign})
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:
    print(err.code, json.load(err))

В руководстве быстрого старта эта логика обернута в удобную функцию-хелпер tenergy(method, path, body).

Смещение часов, защита от повторов и правила IP

Области видимости ключей (Scopes)

API-ключ получает только те разрешения, которые были явно указаны при его создании: поле scopes обязательно, и система не имеет предустановленных наборов разрешений. Названия прав соответствуют формату area.action (тип ApiKeyScope в openapi.yaml); в справочнике по API-ключам подробно описано назначение каждого скоупа. Вызов операции вне прав ключа вернет статус 403 с кодом 1005 insufficient_scope и указанием недостающего скоупа в поле details.required_scope. Запрашивайте только минимально необходимые для интеграции права.

Идемпотентность

История идемпотентности хранится 24 часа. Отправка того же ключа с другим телом запроса отклоняется с ошибкой 3010 idempotency_conflict.

Следующие шаги

• Быстрый стартпрактическое использование функции подписания: от расчета стоимости до подтверждения заказа.
• Коды ошибок и лимитыкоды серии 1xxx и рекомендации по их устранению.
• Окружениясоответствие хостов и типов API-ключей.