Адреса TRON

API TRC20-адресов: создание адресов и отслеживание депозитов

TRC20-адрес — это обычный адрес аккаунта TRON: 34 символа в форме Base58Check, начинающиеся с T. Он хранит TRX и все токены TRC-20, например USDT. У того же адреса есть 42-символьная hex-запись, которая начинается с 41. Отправка с него стоит Energy и Bandwidth, а получение бесплатно.

7 дней бесплатно — для начала не нужна карта и KYC Некастодиальный — приватные ключи остаются под вашим контролем Тарифы от 49 €/мес (490 €/год) — посмотреть тарифы и лимиты запросов

Чтобы создать TRC20-адрес через API, вызовите POST /api/v2/tron/addresses. В ответе придёт адрес в формате Base58Check, начинающийся с T. Вебхук, зарегистрированный через POST /api/v2/tron/webhooks, затем сообщает о каждом депозите USDT-TRC20 на этот адрес. Сначала страница объясняет формат, потом создание, отслеживание и отправку, с эндпоинтами и телами запросов.

Все примеры выполняются на https://app.chaingateway.io с Bearer-токеном в заголовке Authorization. Заголовок X-Network: testnet переключает любой вызов на тестовую сеть TRON, так что весь сценарий можно отработать на бесплатных тестовых TRX. Подробнее о формате — в статье блога Что такое TRC20-адрес?

Как выглядит TRC20-адрес?

TRC20-адрес — это адрес аккаунта TRON в форме Base58Check, например TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL. В нём 34 символа, и он начинается с T. Документация TRON об аккаунтах определяет исходное значение как 21 байт: ведущий байт-префикс 0x41 и 20 байт, совпадающих с адресом Ethereum, полученным из того же открытого ключа.

Поэтому у того же адреса есть шестнадцатеричная запись из 42 символов, которая начинается с 41. API нод часто возвращают именно её, а кошельки и обозреватели показывают форму Base58Check. TronWeb переводит одну запись в другую через tronWeb.address.toHex() и fromHex().

«TRC20» называет стандарт токенов, а не адрес. TRC-20 — стандарт взаимозаменяемых токенов TRON, совместимый с ERC-20 из Ethereum на уровне интерфейса. Один адрес TRON хранит TRX и все токены TRC-20.

TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL 418840E6C55B9ADA326D211D818C34A994AECED808 1 2 3 4
  1. Форма Base58Check, которую показывают кошельки и обозреватели: 34 символа, начинается с T.
  2. Байт-префикс 41 показывает, что значение — адрес TRON.
  3. Остальные 20 байт совпадают с адресом Ethereum, полученным из того же открытого ключа.
  4. Hex-форма: всего 42 символа, её возвращают многие API нод.
Один адрес TRON, две записи. Пример взят из документации TRON об аккаунтах.

Совпадает ли TRC20-адрес с адресом контракта TRC20?

Нет. Адрес кошелька — это аккаунт, которым управляет приватный ключ. Адрес контракта принадлежит развёрнутому коду, и ключа от него нет ни у кого. Документация TRON относит оба к типам аккаунтов, и оба записываются строками с T, поэтому по самой строке их не различить.

Адрес контракта указывает, какой токен переводится. Он никогда не бывает получателем перевода. Контракт TRC-20 для USDT — TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t, а токены, отправленные на адрес контракта, почти всегда вернуть нельзя. Разницу подробнее объясняет руководство в блоге.

Почему новый TRC20-адрес не виден в Tronscan?

Потому что TRON признаёт аккаунт только после активации. Согласно документации TRON об аккаунтах, только что сгенерированная пара ключей существует локально, но найти адрес через API или обозреватель блоков нельзя, пока он не активирован.

Активация происходит, когда существующий аккаунт отправляет на новый адрес любую сумму TRX или токен TRC-10, а отправитель платит комиссию за создание аккаунта. На момент написания документация называет эту комиссию равной 1 TRX в мейннете, поэтому проверьте актуальное значение, прежде чем строить на ней схему выплат. Сгенерированный адрес подходит для депозитов и вебхуков, но не ждите, что обозреватель покажет его до первой активации.

Эндпоинты TRC20-адреса: создание, чтение, отслеживание, отправка

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

ЭндпоинтЧто делает
POST /api/v2/tron/addressesСгенерировать новый адрес TRON
POST /api/v2/tron/addresses/importИмпортировать существующий приватный ключ, чтобы API мог подписывать от имени этого адреса
POST /api/v2/tron/addresses/{address}Сменить пароль, которым зашифрован сохранённый ключ
DELETE /api/v2/tron/addresses/{address}Удалить адрес из вашего аккаунта
GET /api/v2/tron/balances/{address}Баланс TRX на адресе
GET /api/v2/tron/balances/{address}/trc20/{contract_address}Баланс одного токена TRC-20, включая USDT
GET /api/v2/tron/balances/{address}/trc10/{token_id}Баланс токена TRC-10
POST /api/v2/tron/webhooksПодписаться на переводы TRX, TRC-10, TRC-20 или TRC-721 для адреса
GET /api/v2/tron/webhooks/notificationsСписок уже доставленных уведомлений для сверки
POST /api/v2/tron/transactions/trc20Отправить токен TRC-20, например USDT, с адреса

Это вся поверхность API, которой касается система приёма депозитов. Полный справочник TRON, все 40 операций, включая стейкинг и самостоятельную подпись, — на странице TRON API. Поле type у вебхука и отдельный маршрут /transactions/trc10 нужны потому, что в TRON два стандарта токенов. Если вы запускаете собственный токен, а не принимаете чужой, сравнение TRC10 и TRC20 подскажет, какой стандарт выбрать.

Как создать TRC20-адрес через REST?

Запрос POST /api/v2/tron/addresses создаёт адрес. В теле одно необязательное поле password, и оно определяет модель хранения ключа. Если передать пароль, приватный ключ хранится в зашифрованном виде, и последующие переводы подтверждаются паролем вместо ключа. Если пароль не передавать, ответ сразу отдаст приватный ключ, и хранить его нужно в собственном хранилище. Справочник прямо указывает, что пароли не сохраняются: потеряете пароль — кошелёк не восстановить, но и никто другой его не откроет.

curl -X POST https://app.chaingateway.io/api/v2/tron/addresses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password": "a-strong-password-per-wallet"}'

Если ваша платформа сама генерирует ключи, лучше подойдёт второй маршрут. POST /api/v2/tron/addresses/import регистрирует адрес, полученный в другом месте, вместе с его приватным ключом и паролем шифрования, и дальше API может подписывать от его имени. Адресам, которые вы только отслеживаете, не нужен ни один из вызовов, потому что подписка на вебхук ссылается на адрес строкой.

К тому же набору относятся два служебных маршрута. POST /api/v2/tron/addresses/{address} меняет пароль шифрования сохранённого ключа. DELETE /api/v2/tron/addresses/{address} удаляет адрес из вашего аккаунта, и, как отмечено в справочнике, это уменьшает и счётчик использованных адресов. Добавьте этот вызов в задачу, которая выводит из оборота просроченные депозитные адреса, если вы близки к лимиту тарифа.

Как отслеживать входящие USDT на TRC20-адресе?

Опрос Tronscan ради депозитов ломается незаметно, а POST /api/v2/tron/webhooks масштабируется. Единственное обязательное поле по справочнику: url. Поле to сужает подписку до депозитов на ваш адрес, from ограничивает её переводами с него, а contractaddress одним токеном. Поле type выбирает класс актива и принимает TRX, TRC10, TRC20 или TRC721. В reference помещается до 255 символов вашего текста: положите туда ID заказа или клиента, и уведомление придёт сразу с вашим ключом поиска.

curl -X POST https://app.chaingateway.io/api/v2/tron/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-backend.example/hooks/tron",
    "to": "TYourDepositAddress",
    "type": "TRC20",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "reference": "customer-4711"
  }'

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

Как отправить USDT-TRC20 с адреса?

POST /api/v2/tron/transactions/trc20 требует четыре поля: from, to, contractaddress и amount. Сумма задаётся обычным числом в единицах токена, так что 25 USDT — это 25, а не значение, умноженное на шесть знаков после запятой контракта. Вместе с ними передают либо password, если API хранит ключ в зашифрованном виде, либо privatekey, если ключ хранили вы сами.

В поле contractaddress различие между адресом кошелька и адресом контракта токена превращается в конкретное правило интеграции: адрес контракта указывает, какой токен переводится, и никогда не бывает получателем. Адрес USDT: TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t, и он должен стоять в contractaddress, но не в to. Токены, отправленные на адрес контракта, почти всегда вернуть нельзя. Руководство в блоге объясняет, почему эти два адреса выглядят одинаково: оба — строки с T, и по самой строке их не отличить.

Отправка стоит Energy и Bandwidth, а приём бесплатен, поэтому система приёма депозитов платит при сборе средств, а не при самом депозите. Калькулятор комиссий TRON считает стоимость конкретного перевода. Запрос GET /api/v2/tron/chainparameters возвращает актуальные цены ресурсов, чтобы в коде не было константы, которую обесценит голосование в сети.

Как проверить TRC20-адрес перед отправкой?

Проверяйте получателя в момент ввода, а не после трансляции. Адрес TRC-20 состоит из 34 символов, начинается с T и содержит контрольную сумму Base58Check, которую ломает любой неверный символ. Поэтому корректную строку можно отличить от опечатки, не обращаясь к сети. Валидатор адресов выполняет эту проверку для TRC-20, ERC-20 и BEP-20 прямо в браузере, если нужно проверить один адрес вручную.

Случайно перепутать адрес TRON с адресом EVM трудно, потому что форматы заметно различаются: строка с T не проходит проверку Ethereum, а строка с 0x — проверку TRON. TVM в TRON запускает значительную часть кода Solidity, написанного для EVM, но это отдельная среда выполнения. У неё свой учёт ресурсов, Energy и Bandwidth вместо газа, и своя кодировка адресов. Принимать «TRON EVM» буквально значит закладывать ошибки с адресами между сетями.

Строите бэкенд кассы или биржи, которому нужны TRC20-адреса в больших количествах? Создайте бесплатный аккаунт и сгенерируйте партию в testnet. 7-дневный пробный период, без карты и без KYC.

FAQ: API TRC20-адресов

Запрос POST /api/v2/tron/addresses создаёт адрес. Передайте в теле пароль, и приватный ключ будет храниться зашифрованным под ним. Без пароля ответ вернёт ключ, который вы храните сами. Добавьте заголовок X-Network: testnet, чтобы сначала сгенерировать адрес в тестовой сети TRON.

Зарегистрируйте вебхук через POST /api/v2/tron/webhooks. В url укажите свой эндпоинт, в to — депозитный адрес, в type — TRC20, в contractaddress — токен. Каждая доставка несёт заголовок X-Signature, который нужно проверить, прежде чем что-либо зачислять.

Нет. GET /api/v2/tron/webhooks/notifications/failed показывает доставки, которые не дошли, а POST /api/v2/tron/webhooks/notifications/{id}/retry отправляет одну из них заново по вашему вызову. Путь восстановления продумайте сами и сделайте зачисление идемпотентным, потому что повтор доставляет то же событие снова.

Нет. Подписка на вебхук ссылается на адрес строкой. Ключ нужен только для отправки с адреса: его импортируют через POST /api/v2/tron/addresses/import или передают как privatekey в вызове перевода.

В поле contractaddress, но не в to. Оно указывает, какой токен TRC-20 переводится; у USDT это TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t. Токены, отправленные на адрес контракта, почти всегда вернуть нельзя.

GET /api/v2/tron/balances/{address}/trc20/{contract_address} возвращает баланс одного токена TRC-20. GET /api/v2/tron/balances/{address} возвращает баланс TRX, который адресу нужен для Energy и Bandwidth при отправке.

34 символа, начинающиеся с T, в форме Base58Check, которую видят пользователи. Тот же адрес в hex-записи начинается с 41. Формат, контрольная сумма и преобразование между двумя записями разобраны в руководстве «Что такое TRC20-адрес?»

Готовы создать первый TRC20-адрес?

Создайте аккаунт и сгенерируйте тестовый TRC20-адрес уже сегодня. 7-дневный пробный период, без карты и без KYC. Полный справочник эндпоинтов — на странице TRON API, вопрос о формате разобран в статье Что такое TRC20-адрес?, а все семь сетей работают по одной схеме в мультичейн blockchain API.

Проверил(а) Maurice Sobiera Как мы пишем эти страницы