GET /apiv2/balances/

Получение балансов любого TRON-адреса: на текущий момент, в прошлом, в динамике по дням или суммарно за период. Шесть эндпоинтов, все синхронные — ответ возвращается сразу в теле ответа, без очередей и необходимости повторных опросов.

Базовый URL эндпоинта

https://netts.io/apiv2/balances/{address}

{address} — это TRON-адрес в формате base58, ровно 34 символа.

Заголовки запроса

Заголовок	Обязательный	Описание
X-API-KEY	да	API-ключ из личного кабинета
X-Real-IP	да	Адрес из белого списка ключа

Баланс вашего аккаунта должен составлять не менее 4 TRX. Если на счете недостаточно средств, возвращается ошибка 402 еще до того, как запрос дойдет до данных.

Шесть эндпоинтов

Эндпоинт	Что возвращает
GET /apiv2/balances/{address}	все токены на адресе прямо сейчас
GET /apiv2/balances/{address}/at?on=YYYY-MM-DD	балансы на конец указанной даты, UTC
GET /apiv2/balances/{address}/at-block?block=N	балансы на конкретном блоке или на момент ts=YYYY-MM-DD HH:MM:SS
GET /apiv2/balances/{address}/history?token_id=TRX&days=90	движение конкретного токена по дням
GET /apiv2/balances/{address}/summary?date_from=&date_to=	начальный баланс, приход, расход, комиссии и конечный баланс по каждому токену
GET /apiv2/balances/{address}/statement?date_from=&date_to=	предварительный просмотр выписки с детализацией по операциям

Пример

curl -s 'https://netts.io/apiv2/balances/TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10'

{
  "status": "success",
  "code": 0,
  "msg": "",
  "data": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "as_of_block": 86012345,
    "live": false,
    "hide_spam": false,
    "total_value_usd": "385.25",
    "balances": [
      {
        "token_id": "TRX",
        "symbol": "TRON",
        "token_type": "TRX",
        "decimals": 6,
        "balance": "1141.899000",
        "price_usd": "0.334968",
        "value_usd": "382.50",
        "is_verified": true,
        "is_spam": false,
        "balance_source": "events",
        "node_balance": "1141.899000"
      }
    ]
  }
}

Важные нюансы перед интеграцией

Суммы передаются строками, а не числами. "1141.899000" — это десятичное число, сериализованное как текст, чтобы избежать потери точности при преобразованиях с плавающей точкой. Обрабатывайте его с помощью типа для точных десятичных вычислений (decimal), а не float.

В ответах за прошлые периоды актуальным значением является balance, а не node_balance. Поле balance содержит сумму на запрашиваемый момент времени. Поле node_balance во всех ответах отражает то, что находится в блокчейне прямо сейчас — то есть в ответе за прошлый месяц оно все равно будет содержать сегодняшнее значение. Ни в коем случае не отображайте его как исторический баланс. Для запросов «на текущий момент» роли меняются; подробнее об этом в следующем разделе.

Дата указывает на конец дня. Параметр ?on=2026-09-01 возвращает данные на 2026-09-01 23:59:59Z. Если вам нужно начало дня, запрашивайте конец предыдущего дня или используйте /at-block с явным указанием ts.

Два баланса, и почему запросы «на сейчас» требуют внимания

В ответе приходят два разных значения, и на активном адресе они не совпадают:

Поле	Что означает	Когда является точным
balance	Значение из реестра, восстановленное по проиндексированным событиям сети вплоть до блока as_of_block	Точно для указанного блока — который не является самым свежим блоком в сети
node_balance	Состояние на ноде TRON прямо сейчас	Всегда актуальное, никогда не бывает историческим

balance — это не «баланс в блокчейне прямо сейчас». Это баланс по состоянию на блок as_of_block. Если вам нужно актуальное состояние сети в реальном времени, используйте node_balance — это значение запрашивается с ноды TRON в момент выполнения запроса и для TRX рассчитывается по полной формуле: доступный баланс плюс застейканный frozenV2 плюс делегированные средства. На адресе с 41,7 млн застейканных TRX значение составило 42035672.226020, что в точности равно 237799.226020 + 41760434 + 36816 + 623. Если бы с ноды читалось только стандартное поле balance, отобразилось бы 237 тысяч, что расходится с реальностью на два порядка.

Однако node_balance заполняется не для каждой строки. Значения TRX и всех токенов TRC10 возвращаются одним вызовом getaccount, поэтому они присутствуют всегда. С токенами TRC20 ситуация иная: у ноды нет способа получить список всех TRC20-токенов на адресе, поэтому запрос balanceOf отправляется только для основных из них. При проверке кошелька с 504 строками TRC20 в 494 случаях вернулось значение null. Такое значение null обусловлено логикой работы сервиса, а не сбоем; такое же значение null возвращается, если нода временно недоступна. Таким образом, для TRX и TRC10 текущее состояние блокчейна доступно всегда, а для редких токенов TRC20 доступны только balance и блок, на котором он зафиксирован.

Реестр переходит к новому блоку только после того, как каждый процесс индексации подтвердит этот блок, а его граница определяется минимальным значением среди них. Наиболее медленные индексаторы отправляют отметки пакетами, поэтому отставание непрерывно растет, а затем резко сокращается — по пилообразному графику, а не с постоянной скоростью.

Замеры за 20-минутный интервал 6 сентября 2026 года:

	Отставание в блоках от вершины сети	Отставание по времени
Лучший результат	22	~1 мин
Медиана	44	~2 мин
90-й перцентиль	86	~4 мин
Худший результат	121	~6 мин

Учитывайте, что реестр отстает от актуального состояния блокчейна на несколько минут, а не на несколько секунд.

Из этого следует:

• На неактивном адресе данные точны даже для запросов «на сейчас». Если по адресу не было движений дольше текущего отставания, реестр успевает синхронизироваться, и balance становится равен node_balance.
• На адресе, где только что прошла транзакция, balance может быть неточным в любую сторону — заниженным, пока входящий перевод еще не проиндексирован, или завышенным, пока не учтен исходящий.
• Параметр live=true сокращает разрыв, но не устраняет его полностью. Он «на лету» (за 30–80 мс) применяет хвост событий переводов между as_of_block и вершиной сети. При этом значение as_of_block не смещается, комиссии не учитываются, а токены TRC10 намеренно пропускаются, так как отслеживаются отдельным индексом. Пример из замеров: на адресе, где по реестру числилось 157.317444 TRX, с параметром live=true вернулось 766.194807, тогда как на ноде фактически находилось 1698.995472. Это полезная опция, но единственным полем с текущим состоянием сети остается node_balance.
• Исторические данные абсолютно точны. Эндпоинты /at, /at-block, /history, /summary и /statement описывают моменты, которые реестр прошел давно. Здесь нет фактора отставания.

Для учета, сверки и выписок используйте исторические эндпоинты — их данным можно полностью доверять. Для отображения баланса кошелька в реальном времени показывайте node_balance, если он доступен (что верно для TRX и всех TRC10), а если он равен null, переключайтесь на balance с указанием блока as_of_block рядом, чтобы пользователь видел, на какой момент актуальна сумма.

Эндпоинт /history возвращает только дни с активностью. Если запросить days=7 для адреса, по которому операции совершались только в течение трех дней, вернется три точки, а не семь. Каждая точка содержит конечный balance за день и разницу delta по сравнению с предыдущей точкой.

Эндпоинт /summary сходится математически. Для каждого токена выполняется равенство opening_balance + period_in − period_out − period_fees = closing_balance, и сервис возвращает этот расчет в готовом виде в поле control_formula, например: 76493.940406 + 141490.950160 - 216763.731366 - 79.260200 = 1141.899000. Комиссии детализируются по полям period_fees_energy и period_fees_bandwidth. Обратите внимание: эндпоинт /summary может отображать небольшой отрицательный баланс для токена, который в эндпоинте текущих балансов вообще не показывается.

Эндпоинт /statement ограничен параметром ops_limit. Допускается значение от 10 до 5000 операций; любое другое вернет ошибку 422. Поле operations_total содержит фактическое количество операций за период, а operations_truncated указывает, был ли список усечен. Если параметр token_id не передан, по умолчанию используется TRX. Если вам требуется полная выписка объемом более 5000 операций, сформируйте отчет в виде файла — см. Файлы выписок.

Порядок токенов строго определен. Сначала идут TRX и основные стейблкоины, затем верифицированные токены с известной ценой, после чего все остальные. Не сортируйте список повторно по сумме: спам-токены из аирдропов часто имеют огромные номинальные балансы и окажутся вверху списка.

Спам помечается, но не удаляется. Поле is_spam отмечает токены, признанные мошенническими. Передайте hide_spam=true, чтобы скрыть их из ответа; TRX и USDT не скрываются никогда.

Лимиты запросов

Каждый эндпоинт обрабатывает до 10 запросов в секунду, лимит общий для всех клиентов данного эндпоинта. Лимит действует раздельно для каждого эндпоинта, поэтому /history и /summary не конкурируют друг с другом.

При превышении лимита возвращается ошибка 429 с заголовком Retry-After: 1, а также заголовками RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset. Повторите запрос через указанное время.

Второй, более широкий лимит в 100 запросов в секунду на исходный IP-адрес применяется ко всему API в целом. Лимиты различаются по тексту сообщения: при превышении лимита конкретного эндпоинта возвращается Endpoint rate limit exceeded (10 req/s shared), а при превышении общего лимита аккаунта — API rate limit exceeded.

Ошибки

HTTP	Значение
400	адрес состоит из 34 символов, но не проходит проверку контрольной суммы base58
401	ключ отсутствует или недействителен, либо IP-адрес источника не добавлен в белый список
402	баланс аккаунта ниже минимального порога в 4 TRX
403	API-ключ заблокирован; обратитесь в поддержку
422	параметр отсутствует или выходит за допустимые пределы — неверная длина адреса или значение ops_limit вне диапазона 10–5000
429	превышен лимит запросов
503	сервис балансов не ответил; запрос не был учтен в расходе, повторите попытку

Тела ошибок могут возвращаться в трех форматах в зависимости от того, на каком уровне был отклонен запрос. Проверяйте код HTTP-статуса, а не содержимое ответа.

// 401, 402, 403 — шлюз, до передачи запроса в сервис
{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}

// 400, 422 — сервис, после обработки параметров
{"status": "error", "code": -4, "msg": "address must be base58 (T...)", "data": {"code": -4, "msg": "address must be base58 (T...)"}}

// 429 — ограничитель частоты запросов
{"message": "Endpoint rate limit exceeded (10 req/s shared), retry shortly", "request_id": "e5dbf25437d2eb215c764617d50b8d3b"}

См. также

• Файлы выписок — полная выписка в формате CSV или PDF
• Вебхуки отчетов — уведомления о готовности файла