Як програмно створити TON-гаманець (v4, v5, highload)

Ви запустили генерацію 500 промокодів, і під кожну виплату потрібен окремий TON-гаманець. Або пишете ШІ-агента, який на льоту створює «гарячий» гаманець, приймає депозит і щось із ним робить. Перше, що видає пошук, — купа SDK-прикладів: підключи @ton/ton, розберися, чим WalletContractV4 відрізняється від WalletContractV5R1, вручну виклич mnemonicNew(), виведи ключі, обчисли адресу, не забудь про subwallet_id у highload. Пів дня йде на інфраструктурний код, який не має стосунку до вашого завдання. А якщо гаманці створює ШІ-агент, він має вміти це сам — без того, щоб ви зашивали в нього криптографію.

Нижче — як створити TON-гаманець програмно (generate wallet / створення гаманця в TON) одним викликом інструмента generate_wallet, розібратися з версіями v3r2, v4, v5r1 і highload_v3 та не втратити перший депозит на типовій помилці з bounceable-адресою.

Навіщо створювати TON-гаманець програмно (і чому не через SDK)

Ручне створення через SDK — це нормально рівно до першого продакшену. На масштабі починаються проблеми:

• Версії. У TON не один «гаманець», а кілька контрактів: v3r2, v4, v5r1, highload. У кожного своя логіка і своя адреса для одного й того самого ключа. Помилитеся з версією — отримаєте не ту адресу.
• Формати адреси. Той самий гаманець має форму EQ і UQ. Переплутаєте їх, видаючи адресу для депозиту, — гроші «відскочать» назад (про це нижче).
• ШІ-агент. Агентові (Claude, Cursor, ChatGPT/Codex) не можна «дати бібліотеку» — йому потрібен інструмент, який він викличе за описом. Через MCP (Model Context Protocol) агент викликає generate_wallet як звичайну функцію й отримує готову структуровану відповідь. Логіка версій, ключів і форматів живе на боці MCP-сервера.
• Поліглот-стек. Не хочете тримати TON-SDK на Go, Python і Node одночасно — MCP дає один інтерфейс для всіх.

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

generate_wallet за один виклик: що саме повертається

generate_wallet створює новий TON-гаманець і повертає повний набір для володіння ним і відновлення:

• мнемоніку (seed-фразу) — людиночитаний набір слів, з якого детерміновано виводиться все інше;
• приватний ключ — для підписання транзакцій;
• публічний ключ;
• адресу гаманця — у стандартних TON-форматах.

Промпт агентові має буквально такий вигляд:

Створи новий TON-гаманець версії v5r1 через generate_wallet
і покажи адресу та мнемоніку.

Агент викликає інструмент із параметром версії та повертає структуру приблизно такого вигляду (значення умовні; ключі Ed25519 у TON — це звичайний hex, без Ethereum-префікса 0x):

{
  "version": "v5r1",
  "mnemonic": ["word1", "word2", "...", "word24"],
  "public_key": "e3f1a2…",
  "private_key": "9b7c4d…",
  "address": {
    "bounceable": "EQ…",
    "non_bounceable": "UQ…",
    "raw": "0:abcd…"
  }
}

Жодного SDK і ручної деривації. Далі ви самі вирішуєте, де це зберігати. Ключовий момент: сервер цю мнемоніку та ключі в себе не залишає — про це нижче в розділі про некастодіальність.

Версії гаманців v3r2, v4, v5r1 та highload_v3 — яку обрати

generate_wallet підтримує чотири версії контракту гаманця. Це не «новіше — отже, краще»: у кожної своя ніша.

v5r1 (W5) — за замовчуванням для нових проєктів

Найновіша версія. Підтримує розширення та gasless-сценарії — коли комісію за користувача може сплатити сторонній релеєр. Це властивість самого контракту v5, а не послуга TONNode: сервер лише створює такий гаманець, жодного gasless-релеєра він не надає. Якщо будуєте сучасного агента з нуля і вам не потрібен саме highload — беріть v5r1.

v4 — версія з плагінами

Попереднє масове покоління. Підтримує плагіни: до гаманця можна прикріплювати контракти-розширення (наприклад, для підписок і відкладених платежів). Довго була де-факто стандартом, її широко підтримують гаманці та сервіси. Беріть, якщо у вас є залежність від плагінної моделі v4.

v3r2 — простий базовий гаманець

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

highload_v3 — для масових виплат

Окремий клас. Гаманець під високу пропускну здатність: одне зовнішнє повідомлення може нести багато переказів. Це те, що ви берете під батч-виплати, дропи, роздачі нагород, платіжні шлюзи, біржові виводи. За ефективність він платить особливою моделлю обліку повідомлень (query_id / expiration), тому вимагає обережного поводження — див. розділ про зберігання параметрів.

Версія	Коли брати
v5r1	Нові проєкти, розширення, gasless
v4	Потрібні плагіни (підписки тощо), максимальна сумісність
v3r2	Простий службовий гаманець без зайвого
highload_v3	Масові/пакетні виплати, високий throughput

Приклад промпта під виплати:

Згенеруй highload_v3 гаманець для пакетних виплат і поверни
мнемоніку, ключі та адресу.

Перший депозит: чому надсилати на non-bounceable UQ-адресу

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

У TON адреса має прапорець «bounceable»:

• EQ (bounceable) — якщо за адресою немає живого контракту, мережа відбиває («bounce») переказ назад відправнику. Для нового гаманця це саме ваш випадок.
• UQ (non-bounceable) — переказ «прилипає» до адреси, навіть якщо контракт ще не розгорнутий. Рівно те, що потрібно для першого депозиту.

Правило просте: перше поповнення нового гаманця надсилайте на UQ-адресу. З EQ-адреси переказ повернеться, і ви гадатимете, чому баланс порожній. Після того як гаманець зробить першу вихідну транзакцію і задеплоїться, можна спокійно користуватися bounceable-формою.

Як надійно отримати UQ-форму? Офлайн-інструментом parse_address — він конвертує та перевіряє формати EQ/UQ/raw без звернення до мережі:

Через parse_address переведи цю адресу в non-bounceable
UQ-форму для першого депозиту

Після поповнення перевірте стан через get_account_state — він покаже статус акаунта (uninitialized / active), прапорці та останню транзакцію:

Перевір get_account_state для UQ… — чи задеплоєний гаманець
і який баланс

Доки контракт не активний, стан підкаже, що депозит ще не «підняв» гаманець. Докладний розбір форматів — у статті про адресні формати EQ/UQ/raw.

Highload-гаманець: зафіксуйте subwallet_id і timeout самі

Окреме попередження для тих, хто взяв highload_v3. Самої мнемоніки тут недостатньо, щоб коректно відтворити робочий гаманець і повторити його поведінку. У highload-контракту, крім ключа, є ще два параметри, які задаються під час створення і входять у його initial data (state init):

• subwallet_id — ідентифікатор підгаманця (дозволяє з однієї seed-фрази отримати кілька різних адрес);
• timeout — вікно життя зовнішніх повідомлень, на якому побудована логіка query_id і спливання терміну дії.

Важливо: generate_wallet повертає мнемоніку, ключі й адресу — а subwallet_id і timeout ви обираєте та фіксуєте самі як параметри конструкції highload-гаманця. Саме ви відповідаєте за те, щоб записати ті значення, з якими гаманець було створено.

Highload-гаманець відстежує, які повідомлення ще «живі», на основі timeout. Якщо відновите гаманець лише за seed-фразою, без subwallet_id і timeout, то:

• отримаєте не ту адресу — і subwallet_id, і timeout входять у state init, тому зміна будь-якого з них змінює initial data контракту, а отже, і його адресу;
• не відтворите коректну логіку спливання терміну дії та дедуплікації повідомлень — і ризикуєте зламати облік вихідних переказів.

Практичне правило: для highload_v3 кладіть subwallet_id і timeout у сховище поруч із мнемонікою, як частину одного запису про гаманець. Це не опційні метадані — це частина ідентичності гаманця.

# псевдозапис секрету
mnemonic:      "word1 word2 … word24"
version:       "highload_v3"
subwallet_id:  <значення, яке ви задали під час створення>
timeout:       <значення, яке ви задали під час створення>

Для v3r2/v4/v5r1 такої вимоги немає — там достатньо мнемоніки та знання версії.

Некастодіально: сервер не зберігає й не підписує ключі

Головне питання, коли гаманець створюється «десь на сервері»: хто зрештою володіє ключами? Відповідь тут однозначна.

generate_wallet строго некастодіальний:

• сервер ніколи не зберігає приватні ключі, мнемоніку та кошти;
• сервер ніколи не підписує транзакції за вас;
• згенерований гаманець — мнемоніка, ключі, адреса — цілком віддається вам у відповіді й на боці сервера не зберігається.

Немає бази з чужими seed-фразами, немає operator-ключа, який щось підписує за вас. По суті generate_wallet — це зручна обгортка над детермінованою генерацією: криптографія відбувається, результат отримуєте ви, а в сервера не лишається нічого. Це принципова відмінність від кастодіальних агент-гаманців, де сервіс тримає ключ (або його частину) і підписує транзакції сам. Різницю розбираємо окремо: кастодіальний проти некастодіального MCP.

Практичний висновок: збережіть відповідь generate_wallet у своє безпечне сховище одразу. Вдруге той самий гаманець сервер вам не «дістане» — він його не пам'ятає, і відновити «через підтримку» буде неможливо. Це фіча, а не баг.

Як підключити і створити перший гаманець

Підключення — хвилинна справа. Локально й безкоштовно піднімаєте пакет @tonnode/mcp через npx; повний набір читання доступний без ключа.

Конфіг MCP-клієнта (Claude Desktop, Cursor, будь-який MCP-клієнт):

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

Пакет @tonnode/mcp — open source (MIT), лежить на npm і GitHub (tonnode/mcp) і працює через нативний ADNL-протокол TON, без HTTP-прошарків між вашим агентом і мережею. Перезапустіть клієнт — і всі 16 інструментів, включно з generate_wallet, parse_address та get_account_state, стануть доступні агентові. Як прикрутити його до конкретного клієнта — в інструкції підключення Claude і Cursor до TON.

generate_wallet входить до всіх 16 інструментів і доступний на всіх тарифах, включно з безкоштовним Hobby — 60 запитів на хвилину, без картки. Безкоштовний ключ ви отримуєте одразу після входу. Платите ви лише за пропускну здатність, а не за доступ до інструментів.

Далі — три інструменти, які закривають весь сценарій «створити й безпечно поповнити»:

1. generate_wallet — створити гаманець потрібної версії, забрати мнемоніку, ключі, адресу.
2. parse_address — отримати UQ-форму адреси для першого депозиту (офлайн).
3. get_account_state — переконатися, що депозит розгорнув контракт.

Приклад повного промпта агентові:

Створи v5r1 гаманець через generate_wallet. Потім через
parse_address дай мені його UQ-адресу для першого поповнення.
Після того як я закину монети, перевір get_account_state,
що гаманець задеплоєний.

Коли потрібен hosted-ключ

Локальний npx-запуск використовує публічний конфіг і чудово підходить для розробки. Якщо потрібна гарантована пропускна здатність під навантаженням (ті самі масові виплати з highload), підключіть hosted-ендпоінт зі своїм ключем:

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": { "Authorization": "Bearer tn_live_…" }
    }
  }
}

Підсумок

• generate_wallet створює TON-гаманець одним викликом і повертає мнемоніку, приватний/публічний ключі та адресу — це один виклик із вибором версії, а не ручна збірка на SDK.
• Версія за замовчуванням для нового проєкту — v5r1; для масових виплат — highload_v3; v4 — заради плагінів; v3r2 — коли потрібен простий гаманець.
• Перший депозит надсилайте на non-bounceable UQ-адресу, інакше він відскочить; UQ-форму дає parse_address, а стан перевіряє get_account_state.
• Для highload самі зафіксуйте subwallet_id і timeout та зберігайте їх разом із мнемонікою — обидва входять у state init і впливають на адресу.
• Сервер некастодіальний: ключі та кошти не зберігає й не підписує — ключі ваші.

Візьміть безкоштовний ключ Hobby і створіть перший гаманець через generate_wallet за кілька хвилин — tonnode.io/dashboard?plan=hobby.