ton

How STONfi Handles Bounceable and Non-Bounceable Addresses on TON
TON addresses can look different while still pointing to the exact same on-chain account.
A common example is the difference between an address beginning with EQ... and one beginning with UQ.... The first is the familiar bounceable user-friendly representation, while the second is the non-bounceable representation. Despite the different prefixes, both can identify the same underlying TON account because the account itself is determined by its workchain and 256-bit account identifier. The bounceable or non-bounceable distinction is encoded as metadata in the user-friendly representation rather than creating a different account.
This distinction becomes especially important when interacting with DeFi protocols such as STONfi, where a single swap can involve several TON addresses and multiple layers of contract messages.
Understanding what the address prefix actually means makes it much easier to understand why STONfi can work with different address representations without treating them as different destinations.
The First Important Distinction: Address Identity vs. Message Behavior
The easiest way to understand TON addresses is to separate who the destination is from how a message should behave when it is sent there.
A TON user-friendly address contains several pieces of information. Among them are the workchain identifier, the account identifier, and flags describing how the address is intended to be handled. In particular, the flags encode whether a message should be sent as bounceable or non-bounceable.
That means the visible prefix is not simply an alternative account identifier.
For example:
EQ... → bounceable user friendly representation
UQ... → non-bounceable user friendly representation
When the underlying workchain and account ID are identical, these are two representations of the same account.
TON's own address utilities can convert an address into its raw, bounceable, and non bounceable forms, which is another way of demonstrating that these are different representations of the same underlying destination rather than separate wallets.
This is one of the most important concepts for developers building on TON:
Do not compare the visual prefix when you are trying to determine whether two addresses identify the same account. Parse the address and compare the underlying address components.
What Does “Bounceable” Actually Mean?
Bounceability is fundamentally about message handling.
TON internal messages contain a bounce flag. When a bounceable message is delivered to a destination and processing fails under the conditions where bouncing is supported, the remaining value can be returned toward the sender. TON's smart contract guidelines recommend bounceable messages for most interactions because they provide protection against certain destination or execution failures.
The important point is that an account does not permanently become a “bounceable account” or a “non bounceable account.”
Instead, the user-friendly address representation contains a flag that software can use when constructing the outgoing message.
TON documents the mainnet friendly formats as:
E... for bounceable addressesU... for non-bounceable addresses
The same account can therefore be represented in either form.
So when someone changes an address from EQ... to UQ..., they have not moved funds, created a second wallet, or changed the account itself.
They have changed the friendly representation and associated bounce preference.
Why Does TON Need Non-Bounceable Addresses?
The answer becomes clearer when we consider account initialization.
TON supports contract accounts whose addresses can be determined before the corresponding contract is deployed. A wallet contract, for example, can have a deterministic address derived from its initialization parameters even before the account has been activated on-chain. TON documentation explicitly describes cases where an address exists as a deterministic value while the account itself is still in the nonexist state.
This creates an important funding problem.
Suppose you want to send TON to a wallet whose address is known but whose account has not yet been initialized. A non bounceable message can be used to fund that destination without the value being bounced back simply because the account has not yet been initialized.
This is why non-bounceable representations are especially associated with funding or initializing wallets.
TON's documentation recommends non-bounceable addresses for wallet contracts in situations where the destination may be uninitialized, while bounceable messages are generally preferred for smart contract interactions where failed execution should result in the value being returned.
Wallets on TON Are Smart Contracts
Another concept that sometimes causes confusion is the word “wallet.”
On TON, a wallet is not merely an account label in the same sense as a traditional centralized exchange account. Wallet implementations are smart contracts, and their address can be derived before deployment.
That is why it is possible to know where a wallet will exist before the wallet contract has actually been initialized on chain.
TON's address workflow reflects this distinction. When a wallet application prepares a transfer, it can inspect the destination's account state. TON documentation notes that when a destination is still uninitialized, wallet software can force the outgoing message's bounce field to false, effectively preferring non-bounceable delivery for initialization scenarios. For already initialized destinations, the wallet can use the bounce preference represented by the address.
So the practical behavior is more sophisticated than simply saying:
“EQ always bounces.”
or
“UQ never bounces.”
The prefix provides a message-handling preference, while the wallet application and destination state can also influence how the transaction is constructed.
Where STONfi Fits Into This Model
A STONfi swap is not simply a single transfer from one wallet to another.
A typical swap can involve several addresses and several messages:
Your wallet → STONfi contract/router → token contracts or pools → recipient/refund/excess destinations
Depending on the operation, the transaction can involve addresses for:
Your connected walletJetton master contractsJetton wallet contractsSTONfi routersPool contractsReceiver addressesRefund addressesExcess-address destinations
Each address may appear at a different layer of the transaction.
This matters because the address used as the initial transaction target is not necessarily the same thing as every address carried inside the contract payload.
When a wallet sends a TON Connect transaction, for example, the message itself has a destination address and may contain an arbitrary payload. Contract interaction can then encode additional MsgAddress values inside that payload. TON's own examples show this pattern for token and NFT interactions, where a contract message can contain addresses such as a new owner or an excess destination.
That is the architecture that makes address handling inside a STONfi swap more interesting than a simple “send from A to B” transfer.
The Initial Target Is Only One Part of the Transaction
Consider the beginning of a swap.
Your wallet creates an outbound message whose initial destination is the STONfi contract that should receive and process the request.
The wallet therefore needs a valid destination address for that contract.
Inside the request payload, however, the protocol may also need to know where resulting assets should be delivered, where excess value should be returned, or where a refund should go if a particular operation requires it.
Those addresses are represented as normal TON address values in the contract data.
They are not necessarily interpreted according to the visual prefix that a human happens to see in a wallet interface.
At the protocol level, the important information is the parsed TON address itself and the message semantics associated with how that address is used.
Why STONfi Can Treat EQ... and UQ... as the Same Destination
Imagine the following simplified scenario:
EQxxxxxxxx... and UQxxxxxxxx...
may look like two different strings.
A naïve application might compare them as raw text and conclude that they represent different wallets.
A TON-aware application should instead parse them into their underlying address structure.
Once parsed, the application can identify the common workchain and account identifier.
That is why the correct mental model is:
Different friendly representation ≠ different account.
This principle is particularly important for STONfi because a DeFi application may receive addresses from different wallets, SDKs, exchanges, explorers, or developers. Different tools may display the same account using different friendly representations.
TON even provides official utilities for detecting and unpacking these forms into their underlying components.
What Happens With STONfi's to Parameters?
According to the behavior described for STONfi's SDK starting with v0.5.0, generated to parameters use bounceable representations because these protocol destinations are expected to be initialized contracts that are intended to receive and execute logic.
That design is consistent with TON's broader smart-contract guidance.
TON recommends bounceable messages for smart-contract interactions because, when appropriate, a failed contract interaction can cause the remaining message value to return instead of simply disappearing into an unusable destination.
This does not mean every address involved in a STONfi transaction must visually begin with EQ.
It means that the message and contract interaction should use the appropriate bounce behavior for the role that address plays.
That distinction is crucial.
A protocol contract receiving an operation is different from a wallet account being initialized for the first time.
Receiver, Refund and Excess Addresses
One of the easiest mistakes for developers is to assume that every address in a swap transaction is the same type of destination.
It is not.
A swap can involve different address roles with different purposes.
Receiver
The receiver identifies where the resulting asset should ultimately be delivered.
Refund
A refund address can be used when an operation has to return value to the originating user or another designated destination.
Excess
An excess destination is used for value that remains after the required execution costs or amounts have been handled.
These addresses can travel through the protocol as TON MsgAddress values embedded in payloads.
This is why simply looking at the first address in a wallet transaction does not tell you everything that is happening inside the swap.
Why Builders Should Parse Addresses Instead of Comparing Strings
For developers, this may be the most practical lesson of all.
Do not build logic such as:
if (addressA === addressB)
when those values may be different user-friendly representations.
Instead, parse both values into proper TON Address objects and compare their underlying identity.
Libraries in the TON ecosystem are designed to convert between raw and friendly representations. TON's documentation explicitly describes converting between raw, bounceable, and non-bounceable forms, while security guidance warns developers to handle TON's multiple address representations correctly.
The application should care about:
workchain + account identifier
rather than:
EQ vs UQ
as a text prefix.
This is especially important for indexing, caching, database storage, portfolio tracking, recipient validation, analytics, and protocol integrations.
A Useful Mental Model
The easiest way to remember the entire system is to think of a TON address as having two layers.
Layer 1: The Account
This is the underlying identity:
Workchain + 256-bit account ID
That is what identifies the destination account.
Layer 2: The User-Friendly Representation
This is how that account is encoded for humans and software:
Raw / Bounceable / Non-bounceable / Testnet variants
The friendly representation adds metadata, including bounceability and testnet information, plus a checksum.
Two friendly strings can therefore describe the same underlying account.
That is exactly why an EQ... representation and a UQ... representation should not automatically be treated as two different wallets.
What Users Should Do Before a STONfi Swap
For everyday STONfi users, the safest approach is surprisingly simple.
Use the address supplied by your wallet or trusted TON tooling rather than manually editing prefixes.
Do not change EQ to UQ, or UQ to EQ, just because another application displays the address differently.
More importantly, always verify the actual destination, network, amount, and transaction details before signing.
TON wallets and TON Connect applications already understand user-friendly addresses and their associated behavior. TON Connect documentation, for example, expects user-friendly addresses for transaction messages and provides utilities for rendering the connected wallet address.
In other words, users generally do not need to manually manage bounce flags when using a properly integrated wallet and protocol interface.
What Builders Should Take Away
For developers integrating STONfi or building TON applications, address normalization should be treated as a fundamental part of the integration rather than an edge case.
A robust implementation should:
Parse addresses before comparing them.
Never assume two different strings mean two different accounts.
Preserve workchain information.
The account identifier must be interpreted together with the correct workchain. TON's security guidance specifically recommends validating the address chain when processing addresses.
Understand the difference between an account and a message.
Bounceability describes how a message should behave; it is not a permanent property that creates a second account.
Use bounceable messages for appropriate contract interactions.
Smart-contract operations generally benefit from bounceable delivery when failed execution should return remaining value.
Use non-bounceable delivery where initialization or funding requires it.
New or uninitialized wallet contracts are the classic case.
Let trusted SDKs handle representation details.
The purpose of an SDK is not only to make contract calls easier, but also to reduce the number of low-level address-handling mistakes developers can make.
The Bigger Picture for STONfi
As TON DeFi becomes more sophisticated, transactions increasingly involve multiple contracts rather than a simple wallet-to-wallet transfer.
STONfi swaps are a good example.
A user may only see:
“Swap token A for token B.”
Behind that simple interface, the blockchain may be coordinating wallet messages, routers, Jetton wallets, pool contracts, receiver destinations and value-return mechanisms.
Correct address handling therefore becomes part of the protocol's reliability.
The difference between EQ... and UQ... may look cosmetic to a user, but at the protocol level it represents a meaningful distinction in message construction.
At the same time, that distinction should never obscure the underlying truth:
The prefix does not automatically mean there are two different accounts.
The same TON account can have different user-friendly representations, while the message sent to that account can carry different bounce behavior depending on how the address is encoded and how the transaction is constructed.
Final Takeaway
TON's address system is powerful precisely because it separates account identity from user-facing representation.
An EQ... address and a UQ... address can point to the same underlying account. The important identity is the workchain plus the account identifier; the friendly prefix adds handling information such as bounceability.
For STONfi users, this means you should not worry when a trusted wallet or application presents your address in a different valid form.
For builders, the lesson is even more important:
Parse TON addresses. Normalize them. Compare their underlying identity. And choose bounce behavior according to the role of the destination and the purpose of the message.
Once that model is clear, STONfi's address handling becomes much easier to understand.
The next time you see an EQ... and UQ... address, do not immediately think “two wallets.”
Think:
same possible destination, different representation, different message-handling preference.
That distinction is small at the interface level, but fundamental when building reliable applications on TON.
Explore more on STON.FI app.ston.fi
Read more about STONfi here BLOG.STON.FI
#Wallet #TON #swap_crypto