Hello World on TON Blockchain

·

The TON (The Open Network) blockchain is powered by TON Coin, a native cryptocurrency used to pay transaction fees—commonly referred to as gas—similar to how ETH functions on Ethereum. If you're engaging with the TON ecosystem, you've likely already interacted with a wallet and may hold some TON.

This step-by-step guide will walk you through creating a TON wallet using a mobile app and then accessing it programmatically. Whether you're planning to deploy smart contracts, build automated bots that send or receive TON, or simply want to understand how wallets work under the hood, this tutorial lays the foundation.

Mainnet vs Testnet: Which Should You Use?

TON offers two network variants: the mainnet and the testnet.

While testnet seems appealing for beginners due to zero cost, the mainnet often proves more efficient. TON transaction fees are extremely low—around **$0.01 per transaction**. A small $5 investment can cover hundreds of transactions, saving you time and frustration from testnet inconsistencies.

👉 Get started with secure, low-cost blockchain transactions today.

Step 1: Create a Wallet Using a Mobile App

The easiest way to create a TON wallet is by visiting ton.org/wallets and selecting a non-custodial wallet app like Tonkeeper.

Non-custodial wallets give you full control—you own your private keys. This aligns with blockchain’s core principle: self-sovereignty over your assets.

Install Tonkeeper on your mobile device. By default, it operates on the mainnet. To switch to testnet:

  1. Go to Settings
  2. Tap the Tonkeeper logo five times to enable Developer Mode
  3. Toggle to Testnet

If you're setting up a new wallet, tap "Set up wallet" and proceed. Within seconds, you’ll be shown a 24-word recovery phrase—a critical component of your wallet's security.

Step 2: Secure Your 24-Word Recovery Phrase

This recovery phrase—also known as a mnemonic phrase—is the master key to your wallet. Lose it, and your funds are irretrievable. Share it, and your funds are at risk.

Why 24 words? Early crypto systems used raw hexadecimal keys, which were error-prone due to typos. Mnemonics convert complex keys into human-readable words using a standardized dictionary (BIP-39), reducing mistakes and improving usability.

🔐 Store your phrase offline—on paper or a hardware device. Never screenshot it or store it in cloud apps.

Step 3: View Your Wallet on a Blockchain Explorer

In Tonkeeper, tap the top-left corner or the "Receive" button to reveal your wallet address—typically a string like:

kQCJRglfvsQzAIF0UAhkYH6zkdGPFxVNYMH1nPTN_UpDqEFK

This address is safe to share. It’s pseudonymous: while it doesn’t reveal your identity directly, linking it to your real-world identity compromises privacy.

To inspect your wallet, use a blockchain explorer like Tonscan:

Paste your address. A new wallet will show:

Why? Because TON wallets are smart contracts. An inactive status means the contract hasn’t been deployed yet.

You might notice the explorer displays a different address format. TON supports multiple encoding schemes (user-friendly, raw, bounceable), but they all map to the same public key.

Step 4: Fund and Deploy Your Wallet Contract

Even un-deployed wallets can receive funds. The TON blockchain tracks balances by address, so you can receive TON before deploying the contract.

To fund your wallet:

After funding, refresh Tonscan. The balance will update, but status remains Inactive.

Deployment happens automatically when you send your first transaction—this triggers contract initialization.

👉 Learn how to interact with blockchain smart contracts in real time.

Send 0.01 TON via Tonkeeper. Once confirmed:

Step 5: Understanding Wallet Versions

Your wallet runs a specific version of smart contract code—like wallet v4 r2. Older versions (v1–v3) exist; even the official TON Foundation wallet uses v3 r2.

Can one mnemonic deploy multiple versions? Yes! The same seed can generate different wallet addresses based on version and workchain settings.

This can cause confusion: restoring a mnemonic might show an empty wallet. Don’t panic—you likely selected a different version. Always verify the contract version in your wallet app.

Step 6: Set Up Your Development Environment

To interact with TON programmatically, you’ll need:

Initialize a project and install required packages:

npm install @ton/ton @ton/crypto @ton/core

We’ll use TypeScript for better type safety and developer experience.

Step 7: Programmatically Derive Your Wallet Address

Create step7.ts:

import { mnemonicToWalletKey } from "@ton/crypto";
import { WalletContractV4 } from "@ton/ton";

async function main() {
  const mnemonic = "unfold sugar water ..."; // Replace with your 24 words
  const key = await mnemonicToWalletKey(mnemonic.split(" "));
  const wallet = WalletContractV4.create({ publicKey: key.publicKey, workchain: 0 });
  
  console.log("Address:", wallet.address.toString());
  console.log("Workchain:", wallet.address.workChain);
}

main();

Run it:

npx ts-node step7.ts

The output should match your Tonkeeper address. The workchain (usually 0) defines which parallel chain the wallet operates on.

💡 If your wallet uses v3 or another version, replace WalletContractV4 with the correct class (e.g., WalletContractV3R2).

Step 8: Read Real-Time Wallet Data from the Blockchain

Now, let’s fetch live data: balance and transaction sequence number (seqno).

Install @orbs-network/ton-access for RPC connectivity:

npm install @orbs-network/ton-access

Create step8.ts:

import { getHttpEndpoint } from "@orbs-network/ton-access";
import { mnemonicToWalletKey } from "@ton/crypto";
import { WalletContractV4, TonClient, fromNano } from "@ton/ton";

async function main() {
  const mnemonic = "unfold sugar water ...";
  const key = await mnemonicToWalletKey(mnemonic.split(" "));
  const wallet = WalletContractV4.create({ publicKey: key.publicKey, workchain: 0 });

  const endpoint = await getHttpEndpoint({ network: "testnet" });
  const client = new TonClient({ endpoint });

  const balance = await client.getBalance(wallet.address);
  console.log("Balance:", fromNano(balance));

  const walletContract = client.open(wallet);
  const seqno = await walletContract.getSeqno();
  console.log("Seqno:", seqno);
}

main();

This script connects to the testnet and retrieves live data—no private key needed for read operations.

Step 9: Send a Transaction Programmatically

Now for a write operation: sending TON. This requires your private key.

Create step9.ts:

import { getHttpEndpoint } from "@orbs-network/ton-access";
import { mnemonicToWalletKey } from "@ton/crypto";
import { TonClient, WalletContractV4, internal } from "@ton/ton";

async function main() {
  const mnemonic = "unfold sugar water ...";
  const key = await mnemonicToWalletKey(mnemonic.split(" "));
  const wallet = WalletContractV4.create({ publicKey: key.publicKey, workchain: 0 });

  const endpoint = await getHttpEndpoint({ network: "testnet" });
  const client = new TonClient({ endpoint });

  if (!await client.isContractDeployed(wallet.address)) {
    return console.log("Wallet not deployed");
  }

  const walletContract = client.open(wallet);
  const seqno = await walletContract.getSeqno();

  await walletContract.sendTransfer({
    secretKey: key.secretKey,
    seqno,
    messages: [
      internal({
        to: "EQA4V9tF4lY2S_J-sEQR7aUj9IwW-Ou2vJQlCn--2DLOLR5e",
        value: "0.05",
        body: "Hello",
        bounce: false,
      })
    ]
  });

  let currentSeqno = seqno;
  while (currentSeqno === seqno) {
    console.log("Waiting for confirmation...");
    await sleep(1500);
    currentSeqno = await walletContract.getSeqno();
  }
  console.log("Transaction confirmed!");
}

function sleep(ms: number) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

main();

This sends 0.05 TON to mint a secret NFT from the TON Masters collection on testnet.

Transactions take 5–10 seconds to confirm due to TON’s fast block time (~5 seconds).

Frequently Asked Questions

What is a TON wallet?

A TON wallet is a smart contract on The Open Network that manages your TON Coin balance and enables transactions using a private key derived from a 24-word mnemonic.

How do I recover my wallet?

Use your 24-word recovery phrase in any compatible non-custodial wallet app like Tonkeeper. Ensure you select the correct network and version.

Why is my wallet “Inactive”?

An inactive status means the wallet contract hasn’t been deployed. It becomes active after your first outgoing transaction.

Can I use the same seed for multiple wallets?

Yes. The same mnemonic can generate different addresses based on wallet version (v3, v4) and workchain settings.

Is TON blockchain secure?

Yes. The mainnet is secured by decentralized validators and offers high throughput with low fees—making it both secure and cost-effective for developers.

How much does a TON transaction cost?

Typically around $0.01, making it highly affordable for frequent interactions and dApp development.

With this foundation, you're ready to build on TON—whether deploying contracts, creating dApps, or exploring DeFi and NFTs.

👉 Start building on a high-performance blockchain platform today.