TRON API: платежи USDT-TRC20 через REST

К апрелю 2026 года Tether выпустил около 190 миллиардов долларов USDT. TRON нёс примерно 45% этого объёма, около 85 миллиардов долларов, а Ethereum немного отставал, примерно с 40%; эти две сети не раз менялись лидерством с конца 2025 года. В самом TRON картина однозначна: USDT составил 98,6% стейблкоин-стоимости сети в первом квартале 2026 года. Кто бы ни говорил, что TRC-20 означает USDT, для всех практических целей это так.

Объём эмиссии — только половина истории. Объём переводов показывает, для чего используется сеть, и объём USDT в TRON приблизился к 2 триллионам долларов в первом квартале 2026 года. USDT в Ethereum склоняется к DeFi-обеспечению и институциональным расчётам. USDT в TRON — это версия, которую люди реально перемещают: депозиты на биржи, денежные переводы, выплаты подрядчикам в странах, где долларовый баланс лучше местного банковского счёта.

Для решения об интеграции последствие очевидно. Если ваши пользователи выбирают сеть депозита из выпадающего списка, TRC-20 будет самым выбираемым пунктом, и обращения в поддержку по неправильной сети сокращаются, когда ваша сеть по умолчанию совпадает с ожиданиями пользователей. Постройте TRON первым; общая схема запроса позволяет добавить другие сети позже без нового кода.

TRON измеряет два ресурса. Bandwidth покрывает обычные переводы и бесплатен до 600 пунктов в день. У Energy нет бесплатной квоты, и она применяется всякий раз, когда выполняется смарт-контракт, поэтому перевод USDT, вызов контракта TRC-20, всегда стоит дороже, чем отправка обычного TRX.

У TRON нет единой цены gas. Сеть измеряет два отдельных ресурса, и знание того, какой из них потребляет ваша транзакция, — это разница между предсказуемыми комиссиями и неожиданными обращениями в поддержку.

Bandwidth взимается с каждой транзакции и зависит от размера в байтах. Каждый аккаунт получает 600 бесплатных пунктов в день; обычный перевод TRX весит от 250 до 300 байт, поэтому редкие переводы TRX вообще ничего не стоят. Сверх бесплатной квоты сеть сжигает 0,001 TRX за пункт, примерно 0,35 TRX за типичный перевод TRC-20.

Energy применяется только когда выполняется смарт-контракт, и у неё нет бесплатной дневной квоты. Перевод USDT — это вызов контракта, контракт TRC-20 обновляет свою внутреннюю таблицу балансов, поэтому ему нужна Energy сверх Bandwidth. После вступления в силу Proposal #104 в августе 2025 года одна единица Energy стоит 100 Sun, вдвое меньше прежних 210. Перевод на адрес, уже владеющий USDT, занимает около 64 000 Energy, что составляет 6,4 TRX. Перевод на адрес, никогда не владевший USDT, записывает новую запись хранения, а новое состояние стоит примерно вдвое больше Energy, чем обновление: примерно 134 000 единиц, или 13,4 TRX.

Перед отправкой два инструмента делают цифры конкретными. Калькулятор комиссий TRON вычисляет Bandwidth, Energy и итог в TRX для одной конкретной транзакции, а GET /api/v2/tron/chainparameters возвращает текущие цены единиц, чтобы ваш код никогда не зашивал константу, которую изменит следующее голосование управления. Руководство по комиссиям подробно раскрывает механику.

Каждому переводу TRC-20 нужна Energy, и она должна откуда-то взяться. Для большинства отправителей источник — их собственный баланс TRX. Это допущение ломается в двух распространённых ситуациях, и обе создают операционную боль, пока вы их не устраните структурно.

Ваш собственный парк депозитных кошельков

Каждый кошелёк, пересылающий средства в горячий кошелёк, нуждается в собственном балансе TRX для выборки, и при нескольких тысячах кошельков пополнение становится отдельной работой со своими комиссионными затратами на переводы пополнения. Спонсируемые комиссии убирают эту работу. Рекомендуемый сегодня способ настроить это — TronFuel, который арендует Energy, полученную оптом от стейкеров, — тот же механизм, который руководство по комиссиям описывает как сокращающий затраты на комиссии до 60% по сравнению со сжиганием TRX по рыночной цене. Устаревшие эндпоинты Paymaster у Chaingateway делают то же самое и остаются доступными для существующих интеграций.

Ваши конечные клиенты

Пользователь держит 200 USDT в кошельке самостоятельного хранения и ноль TRX; USDT пришли с биржи или от другого человека, и никто не сказал ему, что для их перемещения нужна вторая валюта. Когда он пытается заплатить вам или вывести средства, перевод не проходит. С точки зрения пользователя деньги застряли. С точки зрения вашей очереди поддержки это повторяющееся обращение, которое ни одна запись в FAQ не убивает полностью, потому что решение — «сначала купите TRX на бирже» — это именно то трение, которого клиент хотел избежать, используя стейблкоины. Спонсируемый перевод кладёт этому конец: вы отправляете перевод, спонсор покрывает Energy и Bandwidth, стоимость ложится на ваш аккаунт, и клиент никогда не узнаёт, что такое TRX. Для потоков кассы и вывода средств это одно изменение убирает самый распространённый сценарий сбоя платежей TRC-20.

Оценка и создание спонсируемого перевода

Сначала оцените спонсируемую транзакцию, затем создайте её:

# 1. Оценить комиссию
curl -X POST https://app.chaingateway.io/api/v2/tron/paymaster/estimate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TDepositWallet", "to": "THotWallet", "amount": "500"}'

# 2. Создать запрос Paymaster
curl -X POST https://app.chaingateway.io/api/v2/tron/paymaster \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TDepositWallet", "to": "THotWallet", "amount": "500", "password": "YourWalletPassword"}'

GET /api/v2/tron/paymaster перечисляет каждый созданный вами запрос и сообщает его статус от pending до completed или failed, а GET /api/v2/tron/paymaster/balance показывает оставшийся у вас кредит на спонсорство — вместе они покрывают сверку.

Импорт приватного ключа — самый быстрый путь в продакшен, но некоторые команды в принципе не могут передавать ключевой материал третьей стороне. Причиной может быть внутренняя политика, регулятор или аппаратный модуль безопасности, ключи которого физически невозможно экспортировать. У API TRON есть второй режим, созданный именно для этого ограничения.

Поток состоит из трёх шагов. Вызовите POST /api/v2/tron/transactions/trc20/build, или /api/v2/tron/transactions/build для обычного TRX, с теми же полями, что вы использовали бы для обычной отправки. API возвращает неподписанную сырую транзакцию. Подпишите этот payload там, где живут ваши ключи: в HSM, на изолированной машине, в службе подписи за вашим собственным брандмауэром. Затем отправьте подписанный результат через POST /api/v2/tron/transactions/broadcast, который отправляет его в сеть и возвращает хэш транзакции.

# 1. Построить неподписанную транзакцию
curl -X POST https://app.chaingateway.io/api/v2/tron/transactions/trc20/build \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TColdWallet", "to": "TRecipient", "amount": 1000}'

# 2. Подписать локально своим инструментарием, затем транслировать
curl -X POST https://app.chaingateway.io/api/v2/tron/transactions/broadcast \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signed_transaction": "<подписанная транзакция в виде строки JSON>"}'

Две вещи стоит знать перед выбором этого режима. Построенная транзакция TRON истекает после короткого окна, поэтому шаг подписи и трансляции нужно выполнять быстро, а не оставлять лежать в очереди на ночь. И операционная ответственность смещается: ваша сторона владеет библиотекой подписи и её обновлениями. Взамен вы получаете то, что Chaingateway никогда не видит секрет. Мониторинг депозитов не затрагивается в любом случае, поскольку отслеживание адреса не требует ключа. Многие продакшн-настройки смешивают оба режима: импортированные ключи для операционных кошельков с низкой стоимостью, самостоятельная подпись для казначейского пути.

Опрос обозревателя на предмет входящих переводов тратит запросы и всё равно даёт неверное время. Chaingateway вместо этого отправляет данные сам. Зарегистрируйте вебхук, и ваш бэкенд получит POST со статусом транзакции, подтверждениями и изменениями баланса. Задайте личный секрет в вашем аккаунте, и каждая доставка будет нести заголовок X-Signature — base64-кодированный HMAC-SHA256 от txid payload, — чтобы вы могли проверить отправителя. Доставки, завершившиеся неудачей, попадают в список неудачных уведомлений, и POST /api/v2/tron/webhooks/notifications/{id}/retry отправляет любую из них повторно.

GET /api/v2/tron/webhooks/notifications возвращает прошлые уведомления, полезные, когда нужно воспроизвести события после неудачного деплоя. Настройка занимает несколько минут с руководством по вебхукам.

Отправителям с высоким объёмом не следует сжигать TRX вечно. Заморозьте TRX через POST /api/v2/tron/freeze, и сеть предоставит в обмен Bandwidth или Energy; направьте эти ресурсы на ваш горячий кошелёк через POST /api/v2/tron/delegate. Разморозка и отмена делегирования отменяют оба шага, когда вы хотите вернуть капитал.

Текущие цены ресурсов приходят из GET /api/v2/tron/chainparameters. После Proposal #104 цена единицы Energy составляет 100 Sun, снизившись с 210, что изменило точку безубыточности между стейкингом и сжиганием. Проверьте актуальное значение, прежде чем рассчитывать размер стейка.

С ростом объёма арифметика склоняется в пользу стейкинга, потому что сожжённый TRX исчезает, тогда как застейканный TRX просто припаркован. По грубым данным середины 2026 года стейк порядка 5000 TRX генерировал примерно объём Energy для одного перевода USDT в день. Бизнесу, отправляющему 50 переводов в день, потребовался бы стейк в диапазоне нескольких сотен тысяч TRX, чтобы полностью покрывать Energy стейкингом. Относитесь к этому как к порядку величины, а не к котировке: ваша дневная доходность зависит от того, сколько TRX застейковано всей сетью, а это соотношение меняется. Калькулятор комиссий и эндпоинт параметров сети дают сегодняшние вводные для этого расчёта.

Делегирование — вот что делает стейкинг операционно чистым. Держите стейк на казначейском адресе, который никогда не соприкасается с клиентским трафиком, затем через delegate направляйте его Energy на горячие кошельки, выполняющие фактические отправки. Когда кошелёк выводится из эксплуатации, отмените делегирование и направьте ресурсы его преемнику; сам застейканный TRX никогда не двигается. Одна оговорка для планирования казначейства: после разморозки TRX остаётся заблокированным на период ожидания около двух недель, прежде чем его снова можно потратить, поэтому стейк — это не резерв с мгновенным доступом. Рассчитывайте его на устойчивый объём, а всплески покрывайте арендованной Energy.

Chaingateway поддерживает стандартные типы токенов в TRON. USDT, USDC и DAI работают из коробки с автоматической обработкой десятичных знаков. Для токена, который вы запустили сами, передайте адрес его контракта, и API будет обращаться с ним как с любым другим TRC-20. Схема запроса общая для всех сетей, поэтому вызов ERC-20 в Ethereum, BNB Smart Chain, Polygon или Arbitrum выглядит точно так же, как ваш вызов TRC-20, только с другим сегментом пути.

Сеть рассчитана примерно на 2000 транзакций в секунду, что подходит для платёжных нагрузок из множества мелких переводов. Комиссии остаются достаточно низкими, чтобы микроплатежи оставались жизнеспособными, — несколько TRX за перевод токена, а не комиссия, съедающая платёж. TRON держит бо́льшую долю обращающегося USDT, чем любая другая сеть, поэтому контрагенты, с которыми имеют дело ваши пользователи, уже там, а экосистема кошельков вокруг TRC-20 достаточно зрела, чтобы инструментарий редко мешал.

Типичные интеграции выглядят так: касса, принимающая USDT и зачисляющая заказ после подтверждения; бэкенд биржи, отслеживающий тысячи депозитных адресов и обрабатывающий выводы с горячего кошелька; системы выплат, выполняющие airdrop или графики вестинга; биллинг по подписке, взимающий плату в стейблкоинах каждый месяц; сервисы денежных переводов, перемещающие стоимость через границы за минуты. Один и тот же API покрывает каждый паттерн. Меняется лишь то, какие эндпоинты вы комбинируете.

Каждый эндпоинт на этой странице принимает заголовок X-Network: testnet. С ним идентичный запрос выполняется против testnet TRON: те же пути, те же payload, те же формы ответов. Тестовый TRX бесплатно приходит из публичных кранов, поэтому полная репетиция ничего не стоит — создайте депозитный адрес, отправьте на него перевод TRC-20, получите вебхук, проверьте HMAC-подпись, сметите в горячий кошелёк.

Прогоните путь вебхука хотя бы раз от начала до конца. Классические ошибки интеграции — проверка подписи против неверной кодировки payload или брандмауэр, молча отбрасывающий доставку, — проявляются в testnet точно так же, как проявились бы в продакшене, где они стоили бы реальных депозитов вместо тестовых токенов. Последующий запуск в продакшен означает удаление одного заголовка; быстрый старт показывает весь цикл.

Два класса сбоев требуют противоположной обработки. Ответ 4xx означает, что сам запрос неверен: отсутствующий или истёкший Bearer-токен, некорректный адрес, сумма, которую отправляющий кошелёк не может покрыть. Логируйте и исправляйте причину, но не повторяйте без изменений, потому что идентичный ввод даёт идентичный отказ. Ответ 5xx или сетевой таймаут ничего не говорят о ваших входных данных; повторяйте их с экспоненциальной задержкой и ограничением.

Граничный случай, для которого стоит спроектировать код, — это таймаут после отправки. Ваш HTTP-клиент сдался, но транзакция, возможно, всё же была транслирована. Повторная отправка идентичного перевода на автомате — вот как случаются двойные выплаты. Сначала проверьте, что на самом деле ушло: GET /api/v2/tron/transactions перечисляет переводы, созданные через ваш аккаунт. Повторяйте отправку только если первая попытка доказуемо не удалась. Для сбоев, связанных с комиссией, есть ещё более дешёвый паттерн: проверьте GET /api/v2/tron/chainparameters и ресурсы кошелька перед отправкой, превращая ошибку времени выполнения в предварительную проверку.