Покупка энергии Tron через API

Node.js SDK от TronZap.com

English | Español | Português | Русский

Официальный Node.js SDK для API TronZap. Данный SDK позволяет легко интегрировать сервисы TronZap для аренды энергии TRON.

TronZap.com позволяет покупать энергию TRON, существенно снижая комиссии при переводах USDT (TRC20).

👉 Зарегистрируйтесь для получения API ключа, чтобы начать использовать TronZap API.

Установка

npm install tronzap-sdk
# или
yarn add tronzap-sdk
# или
pnpm add tronzap-sdk

Поддержка платформ

Этот SDK разработан для работы на различных платформах JavaScript/TypeScript:

• Node.js: 20 или выше
• Bun: 1.x
• Deno: 2.x

Тесты запускаются на всех трёх в CI. У SDK нет зависимостей во время выполнения, он использует встроенный fetch.

Быстрый старт

import { TronZapClient } from 'tronzap-sdk';

// Инициализация клиента
const client = new TronZapClient({
  apiToken: 'ваш_api_токен',
  apiSecret: 'ваш_api_секрет',
  // Опционально: базовый URL, таймаут в миллисекундах (по умолчанию 30000) и собственный fetch
  // baseUrl: 'https://api.tronzap.com',
  // timeout: 30_000,
  // fetch: myFetch,
});

// Получение доступных сервисов
const services = await client.getServices();
console.log(services);

// Получение баланса аккаунта
const balance = await client.getBalance();
console.log(balance);

// Получение информации об адресе (ресурсы и балансы)
const addressInfo = await client.getAddressInfo('TRX_ADDRESS');
console.log(addressInfo);

// Оценка количества энергии для перевода USDT (TRC20); для другого токена передайте адрес контракта третьим аргументом
const estimate = await client.estimateEnergy(
  'АДРЕС_ОТПРАВИТЕЛЯ_TRX',
  'АДРЕС_ПОЛУЧАТЕЛЯ_TRX'
);
console.log(estimate);

// Расчет стоимости энергии
const calculation = await client.calculate(
  'АДРЕС_КОШЕЛЬКА_TRON',
  65000  // Количество энергии
);
console.log(calculation);

// Создание транзакции энергии
const transaction = await client.createEnergyTransaction(
  'АДРЕС_КОШЕЛЬКА_TRON',
  65000, // Количество энергии
  1, // Длительность (часы): одна из длительностей, которые возвращает getServices()
  'мой-trx-id',  // Опциональный внешний ID
  true        // Опционально: активировать адрес если нужно
);
console.log(transaction);

// Покупка bandwidth
const bandwidth = await client.createBandwidthTransaction(
  'АДРЕС_КОШЕЛЬКА_TRON',
  345,
  'bandwidth-1'
);
console.log(bandwidth);

// Покупка пакета ресурсов (energy + bandwidth одной транзакцией)
const bundle = await client.createResourceBundleTransaction(
  'АДРЕС_КОШЕЛЬКА_TRON',
  65000, // количество energy
  345,   // количество bandwidth
  1,     // длительность (часы)
  'bundle-1', // внешний ID (опционально)
  true        // опционально: активация адреса
);
console.log(bundle);

// Проверка статуса транзакции
const status = await client.checkTransaction(transaction.id);
console.log(status);

// Создание AML-проверки
const amlCheck = await client.createAmlCheck(
  'address',
  'TRX',
  'АДРЕС_КОШЕЛЬКА_TRON'
);
console.log(amlCheck);

// Проверка статуса AML
const amlStatus = await client.checkAmlStatus(amlCheck.id);
console.log(amlStatus);

// Получение информации о прямой подзарядке
const rechargeInfo = await client.getDirectRechargeInfo();
console.log(rechargeInfo);

// Каждый метод принимает параметры запроса последним аргументом: таймаут или AbortSignal
// При отмене через controller.abort() вызов завершается с причиной сигнала
const controller = new AbortController();
const quickBalance = await client.getBalance({ timeout: 5_000, signal: controller.signal });

Возможности

• Полная поддержка TypeScript
• Кросс-платформенная совместимость (Node.js, Bun, Deno)
• Таймауты и отмена запросов через AbortSignal
• Получение доступных сервисов
• Получение AML-сервисов
• Получение баланса аккаунта
• Получение информации об адресе (ресурсы и балансы)
• Расчет стоимости энергии
• Создание транзакций активации адреса
• Создание транзакций покупки энергии
• Создание транзакций покупки bandwidth
• Создание транзакций пакета ресурсов (energy + bandwidth)
• Создание и отслеживание AML-проверок
• Проверка статуса транзакций
• Получение информации о прямой подзарядке
• Список планов подписок, запуск, проверка и остановка подписок, история подписок

Требования

• Node.js 20 или выше, Bun 1.x или Deno 2.x

AML-проверки

const addressCheck = await client.createAmlCheck('address', 'TRX', 'АДРЕС_КОШЕЛЬКА_TRON');

// или hash транзакции: сеть, адрес получателя, hash и direction
const hashCheck = await client.createAmlCheck('hash', 'BTC', 'АДРЕС_ПОЛУЧАТЕЛЯ_BTC', 'HASH_ТРАНЗАКЦИИ', 'withdrawal');

Для проверки по hash address — это адрес получателя средств в транзакции, а direction указывает, на какой стороне транзакции вы: 'deposit', если средства пришли на ваш адрес (address — ваш адрес), 'withdrawal', если их отправили вы (address — адрес внешнего получателя). Риск оценивается для контрагента: для deposit — для отправителя, для withdrawal — для получателя. Если direction не указан, SDK отправляет 'deposit'.

Подписки

Подписка обеспечивает адрес энергией для каждой транзакции, пока её не остановят или не закончатся её дни или транзакции. Выберите план из getSubscriptions() — объекта с планами по ключам в порядке API — и передайте его ключ, например 'unlimited_energy', а не числовой id плана. Запуск подписки списывает начальную цену плана.

const plans = await client.getSubscriptions();
for (const [subscriptionId, plan] of Object.entries(plans)) {
  console.log(subscriptionId, plan.initial_price, plan.price);
}

const subscription = await client.startSubscription(
  'unlimited_energy',
  'TRON_WALLET_ADDRESS',
  30, // 0 — без ограничения по времени
  0,  // 0 — без ограничения
  'subscription-42' // внешний ID (опционально)
);

await client.checkSubscription(undefined, 'subscription-42');
await client.stopSubscription(subscription.id);

const history = await client.getSubscriptionHistory(1, 10, 'active');

durationDays (в днях, в отличие от часов у транзакций) и transactionsLimit по умолчанию равны 0, что означает отсутствие ограничения. checkSubscription и stopSubscription принимают id подписки, её externalId или оба, как checkTransaction. Пагинация истории по умолчанию — страница 1 по 10 элементов.

Запуск, проверка и остановка возвращают подписку с её params, а элементы истории вместо них содержат счётчики использования transactions_used, energy_used и total_price. Подписку с лимитом транзакций остановить нельзя (ErrorCode.CANNOT_STOP_SUBSCRIPTION).

Обработка ошибок

SDK использует иерархию классов ошибок для точной обработки:

TronZapError
├── ApiError             — ошибки API (code != 0 в ответе)
├── InvalidRequestError  — неверные аргументы, отклонены до отправки
├── NetworkError         — сетевые ошибки
│   ├── ConnectionError  — невозможно подключиться к серверу
│   ├── TimeoutError     — превышено время ожидания
│   └── SslError         — ошибки SSL/TLS
└── HttpError            — HTTP-ответы с кодом не 2xx
    ├── RateLimitError   — HTTP 429 Too Many Requests
    ├── UnauthorizedError — HTTP 401/403
    └── ServerError      — HTTP 5xx

Пример

import {
  TronZapClient,
  ApiError,
  HttpError,
  InvalidRequestError,
  NetworkError,
  RateLimitError,
  ServerError,
  SslError,
  TimeoutError,
  TronZapError,
  UnauthorizedError,
  ErrorCode,
} from 'tronzap-sdk';

const client = new TronZapClient({
  apiToken: 'ваш_api_токен',
  apiSecret: 'ваш_api_секрет',
});

try {
  const transaction = await client.createEnergyTransaction('TRX_ADDRESS', 65000, 1);
} catch (error) {
  if (error instanceof ApiError) {
    // Ошибка API (неверные параметры, недостаточно средств и т.д.)
    console.error(`Ошибка API [${error.code}]: ${error.message}`);

    // Ключ-алиас ошибки, например "invalid_tron_address" или "invalid_tron_address.from_address"
    if (error.errorKey) {
      console.error(`Ключ ошибки: ${error.errorKey}`);
    }

    // Укажите его при обращении в поддержку
    console.error(`ID запроса: ${error.requestId ?? '-'}`);

    if (error.code === ErrorCode.INVALID_TRON_ADDRESS) {
      console.error('Проверьте формат адреса TRON.');
    }
  } else if (error instanceof InvalidRequestError) {
    console.error(`Неверные аргументы: ${error.message}`);
  } else if (error instanceof RateLimitError) {
    console.error('Слишком много запросов. Замедлите частоту обращений.');
  } else if (error instanceof UnauthorizedError) {
    console.error('Неверный API-токен или подпись.');
  } else if (error instanceof ServerError) {
    console.error(`Ошибка сервера TronZap [${error.statusCode}].`);
  } else if (error instanceof HttpError) {
    console.error(`HTTP-ошибка [${error.statusCode}]: ${error.message}`);
  } else if (error instanceof TimeoutError) {
    console.error('Превышено время ожидания запроса.');
  } else if (error instanceof SslError) {
    console.error(`Ошибка SSL: ${error.message}`);
  } else if (error instanceof NetworkError) {
    console.error(`Сетевая ошибка: ${error.message}`);
  } else if (error instanceof TronZapError) {
    console.error(`Ошибка [${error.code}]: ${error.message}`);
  } else {
    console.error('Неожиданная ошибка:', error);
  }
}

Коды ошибок API

| Код | Константа | Описание | |-----|--------------------------------|----------| | 1 | AUTH_ERROR | Ошибка аутентификации — неверный API-токен или подпись | | 2 | INVALID_SERVICE_OR_PARAMS | Неверный сервис или параметры | | 5 | WALLET_NOT_FOUND | Внутренний кошелёк не найден. Обратитесь в поддержку. | | 6 | INSUFFICIENT_FUNDS | Недостаточно средств | | 10 | INVALID_TRON_ADDRESS | Неверный адрес TRON, или у адреса уже есть активная подписка | | 11 | INVALID_ENERGY_AMOUNT | Неверное количество энергии | | 12 | INVALID_DURATION | Неверная длительность | | 20 | TRANSACTION_NOT_FOUND | Транзакция/подписка не найдена | | 21 | CANNOT_STOP_SUBSCRIPTION | Невозможно остановить подписку, например, у неё есть лимит транзакций | | 24 | ADDRESS_NOT_ACTIVATED | Адрес не активирован | | 25 | ADDRESS_ALREADY_ACTIVATED | Адрес уже активирован | | 30 | AML_CHECK_NOT_FOUND | AML-проверка не найдена | | 35 | SERVICE_NOT_AVAILABLE | Сервис недоступен | | 50 | INVALID_BANDWIDTH_AMOUNT | Неверное количество bandwidth | | 500 | INTERNAL_SERVER_ERROR | Внутренняя ошибка сервера — обратитесь в поддержку |

Разработка

# Установка зависимостей
npm ci

# Запуск тестов
npm test

# Проверка кода
npm run lint

# Те же тесты в Bun и Deno, если они установлены
npm run test:bun
npm run test:deno

Тесты работают с локальным HTTP/TLS-сервером и никогда не обращаются к реальному API. examples/basic-usage.ts — smoke-тест против реального окружения (npm run example); инструкции в начале файла.

Поддержка

Для поддержки свяжитесь с нами в Telegram: @tronzap_bot

Лицензия

Этот проект лицензирован под лицензией MIT - см. файл LICENSE для более подробной информации.