How to create TON wallet

In this article we will overview how to create wallet programmatically, how to match it with wallets created from mnemonic in user applications (e.g. TonKeeper, TonWallet) and how to deploy it, if it has state uninit

Wallet address

Wallets in TON are smart contracts. That means that wallet address is derived using the same rules as for any other account on the blockchain - address is derived from State Init.

In case of a wallet contract, two fields determine its address:

• public_key, dependent on mnemonic
• wallet_id, special salt-like field, dependent on wallet contract type and network

Sometimes wallet_id is also called subwallet_id in some of the libraries and documentation. They mean the same thing.

This means that if you have correct mnemonic, you will need to match wallet_id to get the expected wallet address.

Matching wallet applications

The most common use-case for wallet addresses is to match wallet created from the wallet application (e.g. TonKeeper, TonWallet) and the one you get in your source code for programming. The first obvious thing is to use the same mnemonic/public key - you can’t match wallet address without it. Read here to learn more about mnemonics.

Next, you will need to match wallet_id. It is different between wallet versions and network (mainnet and testnet).

Default wallet_id values

Network	Wallet V4R2	Wallet V5
Mainnet	0x29a9a317 (698983191)	0x7FFFFF11 (2147483409)
Testnet	0x29a9a317 (698983191)	0x7FFFFFFD (2147483645)

Explanation:

For Wallet V4R2 wallet_id is defined as first 4 bytes from TON mainnet blockchain initial state hash. There is no specific logic why this number was chosen, community needed some default value and this one works well enough.

For Wallet V5, as you can see above, wallet_id is different between Mainnet and Testnet. This is implemented for security reasons, so that you will get different wallet addresses for different networks with same mnemonic and it will save some developers and users from fund loss.

This value is obtained from 4 parameters:

• network_id: -239 for mainnet, -3 for testnet
• wallet_version: for now always 0
• subwallet_number: 0 by default
• workchain: 0 for Basechain

Algorithm for generating wallet_id from this parameters:

Algorithm here is presented for education purpose, in most cases you won’t need to implement it yourself, instead use existing implementation from libraries.

type WalletIdV5 = {
    // always 0 for now
    readonly walletVersion: number;

    /**
     * -239 is mainnet, -3 is testnet
     */
    readonly networkGlobalId: number;

    // 0 for Basechain
    readonly workchain: number;

    // 0 for the first wallet with this mnemonic
    readonly subwalletNumber: number;
}

export function storeWalletIdV5(walletId: WalletIdV5) {
    return (builder: Builder) => {
        builder.storeInt(walletId.networkGlobalId, 32);
        builder.storeInt(walletId.workchain, 8);
        builder.storeUint(walletId.walletVersion, 8);
        builder.storeUint(walletId.subwalletNumber, 32);
    }
}

Examples

We will use @ton/ton Typescript library for wallet wrappers.

Wallet V4R2

import { mnemonicToPrivateKey } from '@ton/crypto';
import { WalletContractV4 } from '@ton/ton';

// this magic number is default wallet_id for V4R2 wallet contract;
const walletIdV4R2 = 0x29a9a317;

// your 12‑ or 24‑word mnemonic (space‑separated)
const mnemonicV4 = 'bread table ...';

// async function for await
const main = async () => {
  const keyPairV4 = await mnemonicToPrivateKey(mnemonicV4.split(' '));

  const walletContractV4 = WalletContractV4.create({
        workchain: 0,
        publicKey: keyPairV4.publicKey,
        walletId: walletIdV4R2,
    });

  console.log(walletContractV4.address);
}

main();

Wallet V5

import { mnemonicToPrivateKey } from '@ton/crypto';
import { WalletContractV5R1 } from '@ton/ton';

// your 12‑ or 24‑word mnemonic (space‑separated).
const mnemonicV5 = 'bread table ...';

// async function for await
const main = async () => {
  const keyPairV5 = await mnemonicToPrivateKey(mnemonicV5.split(' '));

  // testnet
  const testnetV5Wallet = WalletContractV5R1.create({
        walletId: {
            networkGlobalId: -3,
        },
        publicKey: keyPairV5.publicKey,
        workchain: 0,
    });

  console.log(testnetV5Wallet.address);

  // mainnet
  const mainnetV5Wallet = WalletContractV5R1.create({
        walletId: {
            networkGlobalId: -239,
        },
        publicKey: keyPairV5.publicKey,
        workchain: 0,
    });

  console.log(mainnetV5Wallet.address);
}

main();

After creating wallet contract instance, you can use it to send messages to the blockchain.