Guides · Wallet ·

How to restore a TON wallet from 24 words or a backup file

There are two ways to bring a wallet back into Gram Wallet: type the 24 words, or open an encrypted backup file exported earlier. With the words, Tongram checks that there are exactly 24 and that they form a valid TON mnemonic, then asks for a new password that encrypts them in this browser.

With a file, the encrypted envelope is written as-is and the wallet opens with the password you set when you exported it; the file is useless without that password. Nothing is sent anywhere; both routes run in the browser.

If both the words and the file are gone, no one, Tongram included, can restore the wallet.

Open Gram Wallet

What this covers

  • Covers the Import and Restore buttons on the Gram Wallet start screen and the Add account flow, which uses the same steps.
  • Assumes a wallet created with a 24-word TON mnemonic. Other word counts and non-TON phrases are rejected.
  • Does not cover hardware wallets or other wallet apps; a phrase from another TON wallet works if it is a standard 24-word TON mnemonic.

Steps in Tongram

  1. Open Tongram, go to Wallet. If a wallet is already here, use Add account from the account menu so the existing one stays in place.
  2. From words: choose Import, paste or type the 24 words in any spacing or case. The button stays disabled until the text is long enough, and the check reports the word count when it is not 24.
  3. Set a password of at least 8 characters and repeat it. This password only protects the copy stored in this browser; it is not tied to the phrase itself.
  4. Decide on Stay unlocked. On, the phrase stays in this tab until it closes or the idle lock fires; off, every reopen asks for the password.
  5. From a file: choose Restore and pick the .json file named gram-wallet-<network>-<key>-<date>.json. It is validated before anything is written; a corrupt or foreign file is refused with the reason.
  6. The restored wallet appears locked. Unlock it with the password that was in force when the backup was exported.
  7. Check the address shown against the one you expect. If the funds sat on a v4r2 address and the imported wallet shows v5r1, switch the contract version in wallet settings and compare again.

What you see and where it comes from

  • Fact: the phrase check is local and uses the TON mnemonic rules; no word list or key leaves the page.
  • Fact: the vault is a PBKDF2-SHA256 (600,000 rounds) plus AES-GCM-256 envelope produced by the browser Web Crypto API and kept in localStorage under a per-account key.
  • Fact: the backup file holds that same envelope plus public key, contract version, network, label and creation time. It never contains the plaintext phrase or the API key.
  • Fact: after restore the balance, history and jettons are read from the public TON API the explorer uses, so the screen fills once the wallet is unlocked and syncs.
  • Interpretation: a password check happens only at unlock, so a restored file with a forgotten password looks installed but cannot be opened.

Freshness and limits

  • Restore refuses a file made on another network (mainnet vs testnet). The reason is shown; there is no override.
  • Restore refuses to overwrite a wallet whose vault already exists in this browser. Remove that account first, having made sure you hold its words or a working backup.
  • A backup file with a version newer than this build is refused. Update the app rather than editing the file.
  • Unknown: whether a phrase from a third-party wallet used a passphrase or a non-standard derivation. If so, the address will not match and Tongram cannot tell you why.
  • Lost words and a lost or password-less file mean the funds stay on-chain but cannot be moved. Transfers on TON are irreversible; there is no recovery service.

Common mistakes

  • Typing 12 or 23 words. The counter tells you how many were read; the phrase must be exactly 24.
  • Expecting the old encryption password to work after importing from words. Import always sets a new one.
  • Sending the backup file or the 24 words to anyone who offers help. Tongram has no support flow that asks for either; whoever holds the words holds the funds.
  • Restoring on a different contract version and reading a zero balance as lost funds. Compare the address first.
  • Relying on Stay unlocked as a backup. sessionStorage is cleared when the tab closes and does not survive a browser reset.

Sources

Related