EQ, UQ і raw: формати адрес TON і чому депозит «відскакує»

Розробник генерує новий гаманець, копіює адресу, кидає туди перші 5 GRAM на газ — і за хвилину монети повертаються на гаманець відправника. Баланс новоствореної адреси: нуль. Жодної помилки, жодного «reverted», транзакція пройшла успішно. Просто гроші… відскочили. У чатах TON це класика: «надіслав на власну адресу — не дійшло». І майже завжди причина одна — переплутані формати адреси та прапорець bounceable.

Розберімо предметно, що таке формати адрес TON — EQ, UQ і raw, чим bounceable відрізняється від non-bounceable і чому перший депозит на новий гаманець повертається відправнику. А заразом покажу, як перевірити все це одним викликом інструмента з ШІ-агента, не піднімаючи ні SDK, ні ноди.

Три формати адреси TON: raw, EQ і UQ — у чому різниця

У будь-якої адреси в TON під капотом лежить те саме: номер воркчейну плюс 256-бітний хеш стейт-ініту контракту. Це і є raw-формат:

0:83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8

Ліворуч від двокрапки — воркчейн (зазвичай 0 — базовий, -1 — мастерчейн), праворуч — 256-бітний хеш у hex. Формат чесний і однозначний, але в нього немає контрольної суми: помилилися в одному символі — отримали іншу адресу, валідну на вигляд. Саме raw зазвичай очікують get-методи контрактів і низькорівневі інструменти, а людям його майже не показують.

Друге подання — user-friendly: ті самі 48 символів base64url, які ви бачите в гаманцях та експлорерах:

EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N     (bounceable)
UQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqEBI     (non-bounceable)

У ньому зашита та сама пара «воркчейн + хеш», плюс байт прапорців і контрольна сума CRC16 наприкінці. CRC ловить помилки набору: пошкоджена адреса просто не пройде валідацію ще до відправлення. І саме з цього байта прапорців народжуються префікси EQ та UQ.

Ключове, що варто засвоїти одразу:

• raw і user-friendly — це два способи записати ту саму адресу.
• EQ і UQ — це два варіанти однієї user-friendly адреси, які відрізняються рівно одним прапорцем.

Тобто EQ… і UQ… для одного гаманця вказують на той самий raw-хеш, той самий контракт, той самий баланс. Це не два різні гаманці й не два різні рахунки. Різниця — лише в одному біті наміру відправника.

Bounceable (EQ) проти non-bounceable (UQ): що означає прапорець

Той самий байт прапорців усередині user-friendly адреси й визначає префікс:

Прапорець	Тег	Префікс (mainnet)	Префікс (testnet)
bounceable	0x11	EQ	kQ
non-bounceable	0x51	UQ	0Q

Для тестнету до тега додається 0x80 — звідси екзотичні kQ та 0Q. Але нас цікавить сенс прапорця, а не арифметика тегів.

Bounceable (EQ) означає буквально: «якщо на боці отримувача щось піде не так — поверни монети мені». Це захист для смарт-контрактів. Якщо ви надсилаєте гроші контракту, який має їх обробити, а він падає з помилкою, ще не задеплоєний або газу не вистачило, — ви не хочете, щоб монети просто зависли в порожнечі. Bounce-механізм поверне їх відправнику за вирахуванням комісії.

Non-bounceable (UQ) означає протилежне: «достав і залиш, хай там що». Жодного повернення — монети просто лягають на адресу.

Для повсякденних переказів між людьми різниця непомітна — до одного конкретного випадку.

Чому перший депозит на нерозгорнутий гаманець «відскакує»

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

Тепер дивіться, що відбувається з bounceable-переказом:

1. Ви надсилаєте на цю uninit-адресу переказ у форматі EQ (bounceable).
2. Мережа намагається доставити монети й «викликати» контракт-отримувач. Приймати їх нікому — контракту на адресі немає.
3. Спрацьовує bounce: раз доставити не вдалося, монети повертаються відправнику за вирахуванням комісії.

Підсумок — той самий «відскік». Транзакція пройшла успішно, але баланс нового гаманця залишився нульовим, а гроші повернулися туди, звідки прийшли. Ніхто нічого не вкрав, мережа відпрацювала рівно так, як задумано, — просто ви використали bounceable-формат там, де не мали б.

А якщо той самий переказ надіслати у форматі UQ (non-bounceable)?

1. Мережа намагається доставити монети на uninit-адресу.
2. Bounce вимкнено прапорцем — повертати не потрібно.
3. Монети залишаються на адресі, навіть попри те, що контракт ще не розгорнуто.

Гаманець поповнено. Пізніше, коли ви надішлете з нього першу вихідну транзакцію, разом із нею задеплоїться код контракту — і акаунт стане active. Відтоді він спокійно приймає будь-які перекази, включно з bounceable. Правило UQ критичне лише для найпершого поповнення ще не розгорнутого гаманця.

Хороша новина: екосистема поступово закриває цю діру за користувача. Гаманці v5r1 і низка клієнтів за замовчуванням показують адресу саме в non-bounceable (UQ) вигляді — якраз щоб новачок не втратив перший депозит. Але щойно ви працюєте з адресами програмно — з бекенда, зі скрипта, із ШІ-агента — відповідальність за прапорець знову на вас.

Як правильно надсилати перший переказ: UQ замість EQ

Практичне правило вміщається в один рядок:

Перший депозит на новий (uninit) гаманець — завжди на UQ. Далі можна як завгодно.

Розгорнута логіка для будь-якого сервісу, що надсилає користувачеві кошти:

• Адреса отримувача в стані uninit → шліть на UQ (non-bounceable).
• Адреса active → можна на EQ (bounceable).
• Надсилаєте на смарт-контракт (DEX, джетон-мінтер, ескроу) → EQ, щоб у разі помилки гроші повернулися.

Проблема в тому, що «на око» EQ від UQ відрізняється одним символом префікса, а стан uninit/active з адреси взагалі не видно. Обидві перевірки треба робити програмно. І ось тут не обов’язково тягнути в проєкт @ton/ton, піднімати провайдера й парсити комірки — обидва питання закривають два інструменти MCP-сервера, які ШІ-агент викликає сам.

Якщо тема генерації та першого поповнення гаманця для вас нова — є окремий розбір у гайді про створення TON-гаманця.

parse_address: конвертація та перевірка адрес офлайн одним викликом

parse_address — це офлайн-інструмент із TONNode, hosted MCP-сервера для TON. Він розкодовує адресу, перераховує формати й перевіряє CRC16, не звертаючись до мережі: йому не потрібні ні нода, ні ключ — це чиста математика над рядком, тому все миттєво й без витрати лімітів.

Що він уміє:

• сконвертувати EQ ⇄ UQ ⇄ raw у будь-який бік;
• перевірити валідність адреси (чи зійдеться контрольна сума);
• показати прапорець bounceable і номер воркчейну.

MCP (Model Context Protocol) — стандарт, за яким ШІ-агенти (Claude, Cursor, ChatGPT/Codex і будь-який MCP-клієнт) викликають інструменти. Підключається MCP-сервер одним записом у конфіг клієнта. Локальний безкоштовний варіант із повним набором інструментів читання:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

Далі агенту достатньо звичайного промпту:

Візьми адресу EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N і покажи її в non-bounceable (UQ) та raw форматах. Перевір, що контрольна сума валідна.

Агент викличе parse_address і поверне UQ-версію того самого гаманця, raw-хеш і статус валідності. Жодного ручного base64url-жонглювання й ризику помилитися в 48 символах.

get_account_state: як зрозуміти, чи розгорнуто гаманець, до відправлення

Але формат — це лише половина справи: треба ще дізнатися, у якому стані адреса — active чи uninit. Це вже он-чейн питання, і на нього відповідає get_account_state. Інструмент повертає статус акаунта, прапорці й дані про останню транзакцію.

Логіка перед відправленням першого переказу:

• get_account_state повернув uninit → адресу ще не задеплоєно → шлемо на UQ.
• повернув active → гаманець розгорнуто → можна спокійно слати на EQ.

Промпт агенту:

Перевір через get_account_state, чи розгорнуто адресу UQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqEBI. Якщо стан uninit — нагадай, що перший депозит треба слати в UQ-форматі.

Зв’язка виходить така: generate_wallet створює гаманець (версії v3r2/v4/v5r1/highload_v3) і віддає адресу, яка на момент створення гарантовано uninit — мережа про неї ще не знає. Отже, перший депозит на неї йде строго на UQ. Перед відправленням get_account_state підтверджує, що адреса справді uninit, а parse_address гарантує, що ви взяли саме non-bounceable подання. Після поповнення зручно викликати get_balance і переконатися, що монети лягли на адресу, а не відскочили.

Важливий момент про генерацію: generate_wallet повертає мнемоніку, ключі й адресу користувачеві — сервер їх не зберігає й нічого не підписує за вас. Це некастодіальна механіка, і вона поширюється на всі інструменти свопу, кросчейну та гаманця.

Невелике термінологічне уточнення: GRAM — це перейменований Toncoin (перейменовано в червні 2026), сама мережа, як і раніше, називається TON.

Чек-лист: як не втратити перший депозит на TON

Короткий алгоритм на кожен перший переказ новому гаманцю:

1. Згенерували адресу (generate_wallet або власний SDK) — вважайте її uninit за замовчуванням.
2. Перевірте стан через get_account_state: uninit чи active.
3. Якщо uninit — приведіть адресу отримувача до UQ через parse_address і шліть перший депозит тільки на неї.
4. Якщо active — можна EQ, для контрактів це навіть краще.
5. На смарт-контракти завжди шліть bounceable (EQ), щоб у разі збою гроші повернулися.
6. Після поповнення перевірте get_balance — монети мають лягти на адресу, а не відскочити.
7. Пам’ятайте: EQ і UQ — той самий гаманець (один raw-хеш); ви обираєте не адресу, а поведінку в разі невдалої доставки.

Обидві ключові перевірки — parse_address (офлайн) і get_account_state (он-чейн) — доступні одразу, без власної інфраструктури. Візьміть безкоштовний ключ Hobby (60 запитів/хв, без картки) і викликайте обидва інструменти прямо з ШІ-агента: https://tonnode.io/dashboard?plan=hobby.

А далі за тією ж схемою зручно розв’язувати суміжні задачі: ловити вхідні USDT-платежі на TON, читати баланс USDT одним викликом або викликати get-метод контракту без SDK. Формати адрес — це фундамент, на якому стоїть усе інше: розберетеся з EQ/UQ один раз — і депозит, що «відскочив», більше не застане вас зненацька.