API TRC20-адресов: создание адресов и отслеживание депозитов
TRC20-адрес — это обычный адрес аккаунта TRON: 34 символа в форме Base58Check, начинающиеся с T. Он хранит TRX и все токены TRC-20, например USDT. У того же адреса есть 42-символьная hex-запись, которая начинается с 41. Отправка с него стоит Energy и Bandwidth, а получение бесплатно.
Чтобы создать 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.
- Форма Base58Check, которую показывают кошельки и обозреватели: 34 символа, начинается с T.
- Байт-префикс 41 показывает, что значение — адрес TRON.
- Остальные 20 байт совпадают с адресом Ethereum, полученным из того же открытого ключа.
- Hex-форма: всего 42 символа, её возвращают многие API нод.
Совпадает ли 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-адресов
Готовы создать первый TRC20-адрес?
Создайте аккаунт и сгенерируйте тестовый TRC20-адрес уже сегодня. 7-дневный пробный период, без карты и без KYC. Полный справочник эндпоинтов — на странице TRON API, вопрос о формате разобран в статье Что такое TRC20-адрес?, а все семь сетей работают по одной схеме в мультичейн blockchain API.
Проверил(а) Maurice Sobiera Как мы пишем эти страницы