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	Значення в реєстрі (ledger), відновлене з проіндексованих подій блокчейну до блоку, зазначеного в 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 і блок, на якому він зафіксований.

Реєстр просувається до певного блоку лише після того, як кожен модуль запису індексації підтвердить цей блок, а його порогова відмітка (watermark) є мінімальною серед усіх них. Найповільніші модулі запису публікують свої відмітки пакетами, тому відставання спочатку стабільно збільшується, а потім різко скорочується — це пилкоподібний графік, а не константа.

Вибірка за 20-хвилинне вікно 6 вересня 2026 року:

	Відставання від актуального блоку (блоків)	Відставання за часом
Найкраще	22	~1 хв
Медіана	44	~2 хв
90-й перцентиль	86	~4 хв
Найгірше спостережуване	121	~6 хв

Розраховуйте на те, що реєстр відстає від блокчейну на кілька хвилин, а не на кілька секунд.

З цього випливає:

• Для неактивної адреси дані точні навіть для стану "зараз". Якщо рухів не було довше за поточне відставання, реєстр наздогнав блокчейн, і balance дорівнює node_balance.
• На адресі, де щойно відбулася транзакція, balance може бути неточним в обидва боки — заниженим, поки вхідний переказ ще не проіндексовано, або завищеним, поки не проіндексовано вихідний.
• live=true скорочує відставання, але не усуває його повністю. Цей параметр на льоту застосовує хвіст подій переказів між as_of_block та верхівкою блокчейну, додаючи до часу запиту 30–80 мс. Він не переміщує значення as_of_block, не враховує комісії та навмисно пропускає токени TRC10, які відстежуються окремим індексом. Приклад вимірювання: адреса, реєстр якої повідомляв про 157.317444 TRX, повернула 766.194807 з live=true, тоді як на ноді було 1698.995472. Це корисно, але node_balance залишається єдиним полем, яке відображає поточне значення блокчейну.
• Історичні відповіді є абсолютно точними. Ендпоінти /at, /at-block, /history, /summary та /statement описують моменти, які реєстр пройшов уже давно. Тут немає відставання, на яке потрібно зважати.

Для бухобліку, звірки та виписок використовуйте історичні ендпоінти й довіряйте їм. Для інтерфейсу гаманця в реальному часі відображайте node_balance там, де він присутній (це охоплює TRX і всі TRC10), і використовуйте як резервний варіант balance поруч із as_of_block, де повернуто null, щоб користувач знав, на якому блоці зафіксоване це число.

/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
• Вебхуки звітів — отримання сповіщення, коли файл буде готовий