The TON blockchain operates on TON cryptocurrency (formerly known as TonCoin), a digital asset used to pay transaction fees—commonly referred to as gas—just like ETH on Ethereum. If you're engaging with the TON ecosystem, chances are you already hold some TON and may even have a wallet set up.
In this step-by-step guide, we’ll walk through creating a new TON wallet using a mobile application and then explore how to interact with it programmatically. This is especially valuable if you plan to deploy smart contracts via code or build bots that send and receive TON. Along the way, you’ll gain a deeper understanding of how wallets function on TON and how to manage them effectively.
Mainnet vs Testnet
There are two versions of the TON blockchain: the mainnet and the testnet. The mainnet is the live network where real TON coins are used for transactions. Validators secure the network, ensuring high reliability and enabling wallets to handle significant funds safely.
The testnet, on the other hand, is a sandbox environment where TON coins have no real value and are freely distributed. It’s ideal for testing your code without financial risk. However, while the testnet appeals to new developers due to its zero cost, it often comes with drawbacks—special wallet configurations, instability, and unexpected errors due to simulation differences.
👉 Discover how low-cost blockchain transactions can boost your development speed.
Given that TON transaction fees are extremely low—around $0.01 per transaction—a $5 investment can fund hundreds of operations. Working on the mainnet often proves more efficient and time-saving than troubleshooting testnet quirks.
Step 1: Create a Wallet Using an App
The easiest way to create a TON wallet is by visiting Get a Wallet and selecting a wallet app. This page outlines the difference between custodial and non-custodial wallets. With custodial wallets, a third party holds your private keys. Non-custodial wallets give you full control—your keys, your funds.
For true blockchain autonomy, non-custodial is the way to go. We’ll use Tonkeeper, one of the most popular options. Install the Tonkeeper app on your smartphone and launch it.
By default, Tonkeeper runs on the mainnet. To switch to testnet, go to Settings and tap the Tonkeeper logo five times rapidly to enable Developer Mode. Then select “Switch to Testnet.” You can toggle back anytime.
If you haven’t set up a wallet yet, tap “Set up wallet” and choose “Create new.” Within seconds, your wallet is generated. You’ll be shown a 24-word recovery phrase—this is critical for future access.
Step 2: Secure Your 24-Word Recovery Phrase
Your recovery phrase is the master key to your wallet. Lose it, and your funds are inaccessible. Share it, and your funds are at risk. Store it securely—offline—and never share it.
Why 24 words? Early crypto wallets used complex alphanumeric keys prone to typos. A single mistake meant losing access. The 24-word mnemonic system was introduced to reduce human error. These phrases act as mnemonics, making private keys easier to record and remember.
Step 3: View Your Wallet Address in a Browser
Tap the top-left corner in Tonkeeper to copy your wallet address, or use the “Receive” button. It looks like this:
kQCJRglfvsQzAIF0UAhkYH6zkdGPFxVNYMH1nPTN_UpDqEFKThis address is public. Share it freely to receive TON. However, note that TON addresses are pseudonymous—they don’t reveal your identity directly, but if someone links your address to your real identity, privacy is compromised.
To inspect your wallet, use a blockchain explorer. Popular options include Tonscan. Remember: mainnet and testnet have separate explorers.
Open testnet.tonscan.org, paste your address, and search. A brand-new wallet will show as “Inactive” with zero balance. Under the “Contract” tab, you’ll see: “This address does not contain any data in the blockchain — it has never been used or contract was deleted.”
That’s because TON wallets are smart contracts. Until the first transaction, the contract isn’t deployed.
You might notice that the explorer shows a different address format than what you entered. That’s normal—TON supports multiple address encodings. Use TON Address to verify they all map to the same public key.
Step 4: Fund and Deploy Your Wallet Contract
Your wallet balance starts at zero. To fund it, someone must send TON to your address. But here’s a puzzle: How can you receive funds before deploying the contract?
TON solves this elegantly. The blockchain tracks balances by address—even before contract deployment. So yes, you can receive funds into an undeployed wallet.
On testnet, get free TON via Telegram: message @testgiver_ton_bot with your address.
After receiving funds, refresh Tonscan. You’ll see a balance (e.g., 2 TON), but status remains “Inactive.” The contract still isn’t deployed.
Deployment happens automatically on your first outgoing transaction—usually a transfer. That transaction consumes gas, so funding is essential.
👉 Learn how smart contract deployment works across blockchains with real-time tools.
Use Tonkeeper to send 0.01 TON to any address. After confirmation, refresh Tonscan. The status now reads “Active,” and the contract type shows “wallet v4 r2” (version may vary). You’ve successfully deployed!
Check the balance: after sending 0.01 TON and paying fees, you might have 1.9764 TON left—totaling ~0.0136 TON in gas costs.
Step 5: Wallet Versions Matter
Your wallet’s contract type—like “wallet v4 r2”—indicates its code version. Earlier versions (v1–v3) exist; for example, the official TON Foundation wallet uses v3.
Can one recovery phrase generate multiple wallet versions? Yes—each version produces a unique address. If you restore using an old version, you might see a different address with zero balance. Don’t panic—your funds are safe in the correct version.
Step 6: Set Up Your Coding Environment
To interact programmatically, we’ll use JavaScript/TypeScript with Node.js (v16+). Verify with node -v.
Use an IDE like Visual Studio Code for best TypeScript support.
Create a project directory and run:
npm init -y
npm install @ton/ton @ton/crypto @ton/coreStep 7: Programmatically Retrieve 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(wallet.address.toString({ testOnly: true }));
console.log("workchain:", wallet.address.workChain);
}
main();Run with node step7.js. The output should match your app’s address.
Note: Use WalletContractV3R2 if your wallet uses v3.
Step 8: Read Live Wallet Data
Now query real-time data—balance and seqno (transaction counter).
Install a RPC provider:
npm install @orbs-network/ton-accessCreate 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();Run it to see live data.
Step 9: Send a Transaction Programmatically
Now perform a write operation—sending TON.
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 is 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 transaction to confirm...");
await sleep(1500);
currentSeqno = await walletContract.getSeqno();
}
console.log("transaction confirmed!");
}
function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
main();Run it. The transaction should confirm in 5–10 seconds. Check Tonscan for the transfer and a potential NFT reward.
Frequently Asked Questions
Q: Can I lose my TON if I lose my phone?
A: No—as long as you have your 24-word recovery phrase, you can restore your wallet on any device.
Q: Is it safe to use the mainnet for learning?
A: Yes. With minimal gas fees (~$0.01), small investments pose little risk while offering a smoother experience than testnet.
Q: Why does my wallet show “Inactive” even after receiving funds?
A: The wallet contract deploys only after your first outgoing transaction.
Q: Can one recovery phrase control multiple wallets?
A: Yes—different versions (v3, v4) generate different addresses from the same phrase.
Q: What is seqno?
A: It’s a sequence number that increments with each outgoing transaction, preventing replay attacks.
Q: How do I check my transaction history?
A: Use explorers like Tonscan—enter your address to view all activity.
👉 Start building on high-performance blockchains with developer-friendly tools today.
All code from this tutorial is available on GitHub at ton-community/tutorials. Contributions and PRs are welcome to improve accuracy and clarity.
Happy coding on the TON blockchain!