Wallet contract

A wallet contract is the smart contract that lives at a TON user’s address. It holds the user’s Toncoin and jetton wallets, verifies signatures from external messages, and forwards outgoing transfers. Unlike Ethereum, where a user has an externally-owned account (EOA), every TON wallet is a smart contract.

Why a contract, not an EOA

TON does not have private-key-only accounts at the protocol level. Sending a transaction always involves running a contract that checks a signature against a stored public key. This is more flexible than EOAs:

• The contract can implement multisig, social recovery, or plugin-based subscriptions.
• It can support multiple message styles (single, batched, gasless).
• Versioning is at the contract level — the protocol does not need to ship new transaction types to add features.

The cost is that every wallet must be deployed (a one-time gas fee, often paid by the first incoming transfer) and must keep a tiny TON reserve for storage.

Versions in 2026

• v3R2 — basic single-key wallet, four outgoing messages per transaction. Still in use, mostly legacy.
• v4R2 — adds plugin support (subscriptions, scheduled payments). For a long time the production default.
• v5R1, also called W5 — the current default in Tonkeeper, MyTonWallet, Wallet, and Tonhub. Up to 255 outgoing messages per signed external request, gasless transactions, and plugin support carried over from v4.

Different versions live at different addresses even for the same key — the contract code is part of the address derivation. So a single mnemonic can correspond to a v3 address, a v4 address, and a W5 address simultaneously, each with its own balance.

Seqno and replay protection

Most wallet versions use a seqno (sequence number) for replay protection: each signed external message includes the current expected seqno, and the contract increments it on every successful execution. Replays of the same message fail because the seqno has moved on.

Highload wallets (used by exchanges) replace seqno with a query-id timeout model that allows much higher throughput; see the highload-wallet entry.

Plugins

v4 and W5 support plugins — small auxiliary contracts that can be authorised by the wallet to pull funds on schedule. The two production use cases:

1. Subscriptions — a service plugs into the wallet, withdraws a fixed amount every period.
2. Gasless transfers — a relayer plugin pays gas in TON while the user signs a transfer in jettons (USDT). The relayer is reimbursed in jettons.

Gasless transactions

W5’s headline feature is gasless: the user signs a USDT transfer; a relayer (e.g. Tonkeeper’s service) submits the transaction, pays the TON fees, and takes a share of the USDT as compensation. Net effect — a wallet that holds only USDT can still transact.

Practical notes

• Choose the right version. Most users should be on W5 — Tonkeeper / MyTonWallet upgrade the wallet on first use.
• Check the version on the explorer. If a payment to your address never arrives, you may be checking the wrong version’s balance.
• Bouncable vs non-bounceable. Sending to an uninitialised wallet (one that has never received a transfer) requires a non-bounceable destination flag, otherwise the message bounces back. Wallets do this automatically when needed.