TypeScript SDK
Библиотека @tenergy/sdk представляет собой типизированный клиент к нативному API: по одному методу на каждый operationId, схемы параметров и ответов генерируются напрямую из openapi.yaml, а каждый вызов автоматически подписывается в строгом соответствии со стандартами платформы.
Если вам требуется легкая прямая интеграция без дополнительных зависимостей, ознакомьтесь с компактной функцией tenergy() в быстром старте.
Перед началом работы
| Что делает SDK | Почему это важно |
|---|---|
| Генерирует свежую метку времени и подпись для каждого вызова, включая ретраи | Подписи одноразовые: повторный вызов вернет ошибку 1009 replayed_signature |
| Сериализует тело запроса один раз и подписывает именно эти байты | Повторная сериализация может изменить форматирование и нарушить подпись (1002) |
Повторяет GET и DELETE при ошибках 429, 5xx с учетом Retry-After | Эти методы идемпотентны и безопасны для повторного выполнения |
Запросы POST и PATCH отправляются строго один раз | Запрос на создание с сетевым тайм-аутом мог успеть выполниться; повторите его сами с тем же client_order_id |
Требует apiKey и apiSecret для всех методов, кроме публичных | Для чтения цен без ключа вызывайте GET /v1/prices или /v1/estimate стандартным fetch |
Шаг 1 — Инициализация клиента
import { TenergyClient } from "@tenergy/sdk";
const tenergy = new TenergyClient({
baseUrl: "https://api-nile.tenergy.me/v1", // https://api.tenergy.me/v1 для основной сети
apiKey: process.env.TENERGY_KEY!, // ak_test_… в Nile
apiSecret: process.env.TENERGY_SECRET!, // секрет, сохраненный при создании ключа
});
| Параметр | По умолчанию | Описание |
|---|---|---|
baseUrl | — (обязательный) | Базовый URL с префиксом /v1. Слэш на конце удаляется автоматически. |
apiKey, apiSecret | — | Обязательны для всех закрытых методов. |
timeoutMs | 15000 | Тайм-аут одиночного запроса в миллисекундах. |
retry | { maxRetries: 2, baseDelayMs: 200, maxDelayMs: 5000 } | Только для идемпотентных операций. |
fetch | globalThis.fetch | Любая совместимая реализация fetch. |
Шаг 2 — Котировка, заказ и ожидание
const quote = await tenergy.createQuote({
resource: "energy",
amount: 65_000,
tier: "1h",
receiver: "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
});
const order = await tenergy.createOrder({ quote_id: quote.id, client_order_id: "payout-8821" });
const settled = await tenergy.waitForOrder(order.id, { timeoutMs: 30_000 });
if (settled.partial) console.log("делегировано", settled.delivered_amount, "из", settled.amount);
Метод waitForOrder выполняет опрос GET /v1/orders/{id} каждую секунду до перехода заказа в статус active, expired, reclaimed, failed или refunded. При превышении таймаута выбрасывается исключение TenergyTimeoutError с последним известным состоянием заказа — сам заказ в системе при этом не отменяется.
Шаг 3 — Обработка ошибок
import { TenergyApiError, TenergyTransportError } from "@tenergy/sdk";
try {
await tenergy.createOrder({ quote_id: quote.id, client_order_id: "payout-8821" });
} catch (error) {
if (error instanceof TenergyApiError && error.slug === "insufficient_funds") {
// пополните баланс и повторите вызов с тем же client_order_id (двойного списания не будет)
} else if (error instanceof TenergyTransportError) {
// API не ответил: повторите запрос с тем же client_order_id
} else {
throw error;
}
}
| Класс исключения | Причина | Доступные поля |
|---|---|---|
TenergyApiError | API вернул стандартный конверт с ошибкой | code, slug, httpStatus, field, retryable, details, requestId, retryAfterSeconds |
TenergyTransportError | Сетевой сбой или ответ вне контракта (например, 502 Bad Gateway) | httpStatus, bodyExcerpt |
TenergyTimeoutError | Истекло время ожидания в waitForOrder | waitedMs, last |
Опирайтесь в проверках на свойство slug, а не на английский текст message.
Шаг 4 — Проверка подписи вебхука
import { verifyWebhookSignature } from "@tenergy/sdk";
// rawBody: тело запроса в исходном виде, до парсинга JSON
const valid = verifyWebhookSignature(
process.env.TENERGY_WEBHOOK_SECRET!,
request.headers["x-api-timestamp"],
rawBody,
request.headers["x-api-sign"],
);
Функция проверяет криптографическую подпись; дополнительно сверяйте заголовок X-API-TIMESTAMP с текущим временем (в пределах ±300 с), как описано в разделе Webhooks.
Доступные методы
| Модуль | Методы |
|---|---|
| Регистрация | createAccountChallenge, verifyAccountChallenge, createAccount, getSignupDepositAddress, bootstrap |
| Аккаунт | getAccount, getBalance, listDepositAddresses |
| Тарифы и цены | getPrices, estimateOrder, getOrderBook, createQuote, getQuote |
| Заказы | createOrder, listOrders, getOrder (по ID или cid:<client_order_id>), reclaimOrder, waitForOrder |
| Пакетные заказы | createBatch, listBatches, getBatch, cancelBatch |
| Подписки | createSubscription, listSubscriptions, getSubscription, updateSubscription, cancelSubscription |
| Webhooks | createWebhook, listWebhooks, getWebhook, updateWebhook, deleteWebhook, rotateWebhookSecret, testWebhook |
| Сеть TRON | getAddressResources, estimateTransferEnergy |
| API-ключи | listApiKeys, createApiKey, updateApiKey, deleteApiKey |
| Подписание | signRequest, canonicalString, apiTimestamp, webhookSignature, verifyWebhookSignature |