Запрос баланса токена TRC-20 через API на TRON

Чтение балансов TRC-20 является основой для платежных панелей, интеграции бирж и приложений кошельков на TRON. В отличие от TRX (родного), балансы токенов хранятся внутри смарт-контракта каждого токена — вы запрашиваете balanceOf(address) в контракте.

В этом руководстве показаны TronWeb, TronGrid REST, а также аспекты производства для USDT и произвольных токенов TRC-20.

USDT ссылка на контракт

Официальный представитель основной сети USDT:

TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

Десятичные дроби: 6 (1 USDT = 1_000_000 базовых единиц).

Способ 1: TronWeb

⟦Т1⟧

Примечание. Поведение .call() может возвращать объекты типа BigNumber — тщательно нормализуйте их в рабочей среде.

Способ 2: конечная точка учетной записи TronGrid

⟦Т2⟧

Ответ включает в себя массив trc20 с балансами токенов, привязанными к адресу контракта.

Пример парсинга (структура может отличаться):

⟦Т3⟧

Подходит для перечисления всех токенов одновременно; менее точны для крайних случаев платежей в реальном времени.

Способ 3: триггерконстантконтракт {#константа}

Низкоуровневый HTTP для каждого триггерного смарт-контракта:

• function_selector: balanceOf(address)
• parameter: адрес держателя в кодировке ABI.
• contract_address: контракт токена

Используйте, когда TronWeb недоступен (стеки не JS).

Обработка десятичных дробей

Никогда не принимайте 18 десятичных знаков. Всегда вызывайте decimals() или используйте известные константы:

Используйте целочисленную математику (BigInt) для финансовой точности — избегайте ошибок JavaScript с плавающей запятой на больших балансах.

TRX баланс вместе с токенами

⟦Т4⟧

Пользователям необходимо TRX для оплаты комиссий, даже если у них есть только USDT.

Модели производства

Опрос платежей

Для принятия платежей USDT:

1. Создайте уникальный адрес депозита для каждого пользователя или отслеживайте по сумме + шаблону заметки.
2. Опрос balanceOf после ожидаемого окна оплаты.
3. Лучше: прослушиватели событий на событиях USDT Transfer

Кэширование

• Балансы кэша с коротким TTL (10–30 с) для пользовательского интерфейса.
• Недействителен при обнаружении входящего события Transfer

Ограничения скорости

Соблюдайте TronGrid ограничения — пакетные запросы адресов в непиковое время.

Поддержка нескольких токенов

Абстрактный помощник:

⟦Т5⟧

Пакетные запросы баланса

Для многих адресов избегайте постоянных вызовов N+1. Используйте конечную точку токенов учетной записи TronGrid v1 или параллелизируйте с учетом ограничения скорости. Индексируйте адреса депозитов в своей базе данных и опрашивайте только активные счета, чтобы снизить нагрузку на API.

Ошибки обработки десятичных дробей

USDT использует 6 десятичных знаков; во многих токенах TRC-20 используется 18. Никогда не отображайте необработанный balanceOf без деления на 10**decimals. Сохраняйте суммы в виде строк или BigInt в JavaScript, чтобы избежать ошибок с плавающей запятой. Ошибки с точностью до одной десятичной точки привели к тому, что платежные системы зачислили в 1e12 раз запланированную сумму в производственных инцидентах в других цепочках — тот же риск применим к TRON.

Контрольный список устранения неполадок

Если что-то пойдет не так на TRON, отнеситесь к этому как к проблеме структурированной отладки: подтвердите точный txid в цепочке, проверьте адрес целевого контракта и только затем решите, можно ли устранить сбой. В TRON многие «загадочные» проблемы — это просто одна из следующих: неправильная сеть (основная сеть или тестовая сеть), неправильный контракт токена (поддельный USDT / токены с одинаковым названием), недостаточность ресурсов (OUT_OF_ENERGY / пропускная способность) или задержка пользовательского интерфейса/индексатора между кошельком и проводником.

Начните с этих цепочек проверок:

• Всегда копируйте полный txid/хэш из своего кошелька или проводника.
• Подтвердите статус результата передачи на TronScan (SUCCESS, REVERT, OUT_OF_ENERGY или все еще в ожидании).
• Проверьте, соответствует ли адрес получателя/договора тому, что вы намеревались отправить.
• Если это вызов контракта, убедитесь, что селектор функций и параметры соответствуют стандарту токена, который, по вашему мнению, вы используете (TRC-20 vs TRC-10 vs BEP-20 на BSC).

Затем примените путь исправления для вашей категории:

• Подтвердите статус и параметры транзакции.
• Проверка адресов (контракт токена, получатель, маршрутизатор/отправитель).
• Добавляйте или делегируйте ресурсы (энергию/пропускную способность), если сбой связан с ресурсами.

Распространенные ошибки

Эти шаблоны вызывают большинство сбоев на уровне пользователя:

• Использование адресов основной сети в тестовой сети (или наоборот).
• Копирование символа токена вместо фактического адреса контракта TRC-20.
• Подписание неправильного адреса одобрения/платежа, поскольку ссылка пользовательского интерфейса является вредоносной или устаревшей.
• Повторная попытка без изменения ошибочного ввода (например, REVERT продолжает возвращаться до тех пор, пока вы не исправите параметр).

Если вы не уверены, не «просто отправьте еще раз». Внесите одно контролируемое изменение, проверьте на TronScan, затем продолжайте.

Часто задаваемые вопросы

Как узнать, действительно ли транзакция подтверждена?Используйте TronScan и проверьте статус результата передачи. Ярлыки кошелька «ожидающие» могут отставать; Статус цепочки является источником истины. Скопируйте txid и проверьте SUCCESS/REVERT/OUT_OF_ENERGY, а не только текст пользовательского интерфейса.

Почему пользовательский интерфейс отличается от TronScan?

Некоторые кошельки и децентрализованные приложения используют разные индексаторы или уровни кэша. Короткая задержка между трансляцией и индексированием является нормальной; сравните txid и подождите, пока цепочка стабилизируется, прежде чем сделать вывод об ошибке.

Что мне делать после REVERT?

Остановитесь и декодируйте неудачный вызов. Большинство ошибок REVERT вызвано недопустимыми параметрами, неправильным адресом контракта, отсутствием утверждений или несоответствием между стандартом токена и методом. Устраните причину и подпишите заново.

Безопасно ли подписывать неограниченное разрешение?

Неограниченное одобрение безопасно только для проверенных вами адресов доверенных отправителей (проверенный источник, правильный маршрутизатор и ожидаемый контракт токена). Для тестирования отдавайте предпочтение ограниченному утверждению и отзыву после завершения.

Какие ресурсы требуются TRON для вызовов по контракту?

Выполнение смарт-контракта в основном потребляет энергию, а байты транзакций потребляют пропускную способность. Если вы получили OUT_OF_ENERGY, добавьте/заморозьте/делегируйте Энергию. Если пропускная способность исчерпана, сосредоточьтесь на сохранении достаточного количества TRX для байтов и распределения ресурсов.

Как я могу уменьшить количество обращений в службу поддержки?

Покажите пользователям четкое сообщение «что произошло» на основе статуса цепочки и дайте прямую ссылку на соответствующее руководство (ожидание, сбой, отсутствие энергии или проверка). Сохраните txid, чтобы можно было быстро выполнить согласование.

Похожие руководства {#связанные}

• API приема платежей USDT
• TronGrid Руководство по API
• Отправить USDT программно
• TRON Справочник по HTTP API

Часто задаваемые вопросы

Каков адрес контракта USDT в основной сети TRON?

TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t — всегда проверяйте TronScan перед использованием в производстве.

Требуется ли для BalanceOf закрытый ключ?

Нет. BalanceOf — это вызов контракта только для чтения, который может выполнить любой полный узел или TronGrid.

Почему баланс API отличается от TronLink?

Время, неподтвержденная передача или неверный адрес контракта. Подтвердите последнюю блокировку и контракт.

Могу ли я запросить исторический баланс?

Требуется архивный узел/индексатор, а не стандартная конечная точка учетной записи TronGrid. Используйте API TronScan или индексируйте события Transfer самостоятельно.

Как быстро обновляется баланс после перевода?

После подтверждения транзакции (~3 с). Опросите getTransaction до SUCCESS, затем прочитайте баланс.