tonconnection

You open your TON wallet, head to STON.fi, tap "Connect wallet", pick a pair of tokens, and approve a swap. It takes about a minute and feels like using any other app.
Underneath, a lot more is happening. Cryptographic keys, a smart contract on the blockchain, and a messaging protocol between the website and your wallet all take part. Understanding them makes you safer, because you'll know what you are agreeing to at each step.
So here is the central question: what actually happens when a TON wallet connects to a decentralized application and approves a transaction?
A quick note on names: TON's native currency, formerly called Toncoin, is now Gram (GRAM). The blockchain is still called TON. Some documentation and wallets still use the older name for the same asset.
A TON wallet is a smart contract
There are two things people call "a wallet," and it helps to separate them.
The wallet app is the software on your phone or computer. It shows balances, builds transactions, and asks for your approval.
The wallet contract is a smart contract living on the TON blockchain. TON's documentation explains that wallets are often the entry point of transactions, and that the contract receives signed requests and checks them before acting. Different wallet contract versions (V4 and V5, for example) have different code, so some details vary by version.
A loose analogy is a bank's mobile app versus the account system behind it. The app is the interface, and the account system decides what is allowed. Blockchains don't work exactly like banks, though, and not every smart contract on TON is a standard user wallet.
Your address identifies the on-chain account. TON's docs note that the address is derived from the contract's initial code and data, and that it is not the same thing as your public key.
Keys, signatures and authorization
Many seqno-based TON wallet contracts store a public key. TON's docs explain that wallet contracts use the Ed25519 signature scheme.
Your private key is a secret. It is used to create signatures.Your public key can be shared. It is used to check that a signature is genuine.
When you approve something, your wallet app signs a request with the private key. The wallet contract then checks that signature against the stored public key. If it matches, the contract treats the request as authorized.
Two cautions matter here. First, a valid signature proves control of the key, not that the action is wise. A scam transaction signed by you is still a valid signature. Second, your seed phrase is the source of your private key, so no website, support agent or app should ever ask for it.
Replay protection
Imagine you send a friend a payment and they copy your signed request and send it again. Without protection, the wallet might accept it twice. Replay protection prevents that.
TON's docs describe the common approach for seqno-based wallets: each signed request carries a sequence number, seqno. The contract compares it to its stored value, and once a request has been accepted, the old one fails the check. Requests can also carry a valid_until timestamp, so expired ones are rejected.
Another field, the subwallet or wallet ID, ties a signed request to a specific wallet instance. In Wallet V5 the ID also encodes network information, which helps prevent mixing up networks. The exact checks depend on the wallet contract and version, so don't assume every wallet works identically.
Balance vs. contract state
These are easy to mix up.
Balance. TON's docs state that an account's balance is not stored in the contract's persistent data. It is part of the protocol-level account state, updated as value moves and fees are paid. Your wallet holds GRAM, which pays network fees.
Contract state. This is the data a contract keeps in its own storage. For a wallet, that includes things like the public key and seqno, plus other fields depending on the version.
Jettons. Tokens such as USDT are jettons. The docs explain that regular wallets are designed to store only the native currency. Token balances live in separate jetton wallet contracts, one per owner, which are linked to a jetton master contract. Jetton wallets accept only specific internal messages: from the master, another jetton wallet, or the owner's regular wallet.
This is why a wallet can show 200 USDT and still be unable to do anything without GRAM. The USDT sits in a jetton wallet, while the fees are paid in GRAM from your main wallet. It's also why your wallet app is a presentation layer. It gathers data from several contracts and database indexes, and the on-chain contracts are the real source of truth. Use a blockchain explorer when you need to verify.
How TON Connect works
TON Connect is the protocol that lets a dApp (a decentralized application, like a website that talks to a blockchain) communicate with your wallet. TON's docs describe three roles:
The app (the dApp) runs in your browser or inside your wallet's browser.The wallet holds your keys and signs on your behalf.The bridge relays messages between them. Over the HTTP bridge, messages are end-to-end encrypted, so the bridge sees only ciphertext.
The flow looks like this:
You visit the dApp and choose to connect a wallet.The dApp provides a connection request, via a QR code or a link. Before your wallet shows its prompt, it fetches the dApp's manifest, a small file with the app's name and icon.You approve the connection in your wallet.The dApp receives the account details it needs, such as your address and public key. It does not receive your private key.Later, when you want to do something on-chain, the dApp sends a transaction request.Your wallet shows the details, and you approve or reject.If you approve, the wallet signs and broadcasts it.The blockchain processes the result. Signing and broadcasting do not guarantee success, because contracts can still fail or bounce.
The key principle is that connecting is not signing. A connection lets the dApp see your address and send requests. Every transaction still needs your explicit approval.
Behavior can differ between wallets. TON's docs note that wallets advertise different supported features, and TON Connect's security model has limits: it does not protect against a compromised device, phishing sites on look-alike domains, or bugs in smart contracts.
A practical example: connecting to STON.fi and swapping
STON.fi is a decentralized exchange on TON. It is a good case study because it uses everything above. Two phases, kept clearly apart:
Phase A: Connect.
According to STON.fi's guide, you open the app and click Connect wallet. On mobile, a QR code appears for your wallet's scanner. On desktop, you choose your wallet from a list, as a browser extension or desktop app. Your wallet then asks you to confirm the connection.
STON.fi's guide says this lets the app see your wallet address and request transaction signatures, and that no funds move during connection.
Phase B: Sign.
You go to the swap screen, pick the token you're paying with and the token you want, and enter an amount. A confirmation window shows the tokens, the rate, your slippage tolerance, and the fee reservation. When you click Confirm swap, the dApp sends a transaction request through TON Connect, and your wallet shows its own prompt. You review it and approve or reject.
If you approve, the wallet signs and broadcasts the request, and TON's validators process the resulting messages. Sending USDT, for example, means a message to your jetton wallet with some GRAM attached to cover processing. TON's jetton documentation says that leftover GRAM can be returned via an excess message.
Who does what:
Wallet: holds the keys and signs.TON Connect: carries the messages between dApp and wallet.STON.fi: builds the swap request.TON blockchain: executes the swap and decides the outcome.
One more point: a swap isn't guaranteed to be a single message. TON's docs note that transactions with several messages can have parts that succeed or fail independently. After approving, check the result in your wallet or an explorer. STON.fi's guide mentions an explorer link shown after the swap.
Security checklist
Never share your seed phrase or private key with a dApp, support agent or website.Check that you are on the official site you meant to visit. TON Connect can't protect against phishing domains.Read every transaction prompt before approving.Verify the tokens and amounts in the swapReject unexpected requests.Remember that connecting a wallet doesn't make a dApp trustworthy.Keep a small GRAM balance for network fees.Check the transaction result on-chain when it matters.
FAQ
Is a TON wallet an app or a smart contract?
Both. The app is the interface, and the wallet contract on the blockchain checks signed requests.
Does connecting give a dApp permission to spend my tokens?
No. Connecting shares account details and allows requests. Each transaction still needs your approval.
What's the difference between a public and a private key?
The private key creates signatures and must stay secret. The public key verifies them and can be shared.
Why does my wallet need GRAM when I hold USDT?
Network fees are paid in GRAM, and USDT lives in a separate jetton wallet contract.
What is replay protection?
A safeguard so a signed request can't be reused. Many wallets use a sequence number and an expiry time, though details vary by version.
What does TON Connect do during a STON.fi swap?
It carries the connection and the signing request between the website and your wallet. It doesn't hold your funds or authorize spending itself.
Does approving guarantee success?
No. A swap can still fail, for example because of slippage or low GRAM for fees, so check the outcome.
The takeaway
A TON wallet combines three things: an interface, cryptographic authorization, and contract behavior on the blockchain. The safe sequence is connect, review, explicitly authorize, verify. A swap on STON.fi is a practical place to see all of it work together, and now you know what each step is actually doing.
Sources
TON docs: How TON wallets work, Wallet V5TON docs: Jetton: how it worksTON docs: TON Connect core concepts, Send a transaction with TON ConnectSTON.fi guides: Connect your TON wallet, Swap tokens
#TON #USDT #STONFI #TONwallet #TONconnection