How to Decode a STON.fi Swap Transaction

How to read the TON trace behind a swap, identify the STON.fi contracts involved, and verify what actually happened on-chain.

Decoding a STON.fi swap is less about finding one transaction and more about reconstructing a sequence of messages. TON uses an asynchronous execution model, so a swap that looks like one action in the STON.fi interface can produce several transactions across a wallet, jetton wallets, the STON.fi Router, a liquidity pool, and other contracts.

The practical method is simple: start from the transaction initiated by your wallet, open its full trace, identify each contract, decode the important message bodies, and follow the asset flow until the output tokens reach their destination.

Start with the trace, not a single transaction

If you come from Ethereum, the word "transaction" can create the wrong mental model.

An Ethereum swap commonly appears as one transaction containing multiple contract calls. TON works differently. A TON transaction records the processing of a message and the resulting state change on one account. When that account sends messages to other accounts, those messages trigger additional transactions.

The connected sequence is called a trace. TON documentation describes traces as causally connected messages, with explorers usually displaying transactions as nodes and messages as edges.

That distinction matters immediately when investigating a STON.fi swap. Seeing a successful transaction on your wallet contract does not necessarily tell you that the entire swap finished successfully. It tells you that one part of the trace was processed.

Think about the operation as three different layers:

• Interface action: You select two assets, review a quote, and approve a swap.
• Blockchain trace: Multiple accounts process messages and send new messages.
• Human-readable interpretation: An explorer or indexer groups those low-level events into labels such as token transfer or swap.

The third layer is useful, but it is not the blockchain itself. TON's API documentation explicitly notes that higher-level "actions" are classifications produced by indexer logic rather than objects stored directly on-chain.

For serious debugging, read both the convenient interpretation and the underlying trace.

What should you collect before decoding?

You usually need one reliable starting point.

That may be the transaction displayed by your wallet, the transaction linked by the application, or the wallet address and approximate time when you approved the swap. Developers may also have a query ID or the external message hash.

TON explorers can expose transaction history, messages, fees, execution phases, traces, contract information, and token activity. That makes an explorer the natural first tool for manual investigation.

STON.fi also exposes transaction-oriented API methods. Its API reference includes endpoints for resolving a transaction, checking swap status, and returning the STON.fi actions triggered by an originating transaction.

Before digging into individual cells, write down what you already expect:

• the wallet that initiated the swap
• the token you offered
• the approximate input amount
• the token you expected to receive
• the expected or minimum output
• the approximate execution time

These facts give you anchors. If the trace contains dozens of addresses, you do not have to understand every one immediately. You can follow the assets and identify the important contracts first.

Which accounts matter in a STON.fi swap?

A simple jetton-to-jetton swap can involve more contracts than its interface suggests because jettons themselves use distributed wallet contracts.

Under the TON jetton standard, each holder has a separate jetton wallet contract for a particular token. The jetton master represents the asset, while individual jetton wallets maintain balances and process transfers.

For a basic STON.fi swap, these are the main actors to look for:

Actor	What it does	What to inspect
Your TON wallet	Starts the operation	Initial message and destination
Your offer jetton wallet	Sends the input tokens	Transfer amount and destination
Router side	Receives the token transfer and routes the swap	Transfer notification and swap payload
STON.fi Pool	Executes the AMM exchange	Swap message, output conditions, execution result
Router payout side	Coordinates the output transfer	pay_to and outgoing token movement
Your ask jetton wallet	Receives output tokens	Final token balance change

STON.fi describes the Router as the entry point for DEX calls. For jetton operations, it receives the relevant jetton notification and routes the operation toward the appropriate pool. The Pool handles swap logic and returns the result for settlement.

Do not identify contracts only by friendly explorer labels. When accuracy matters, compare their addresses and message behavior with the documented STON.fi architecture.

Message op codes turn the trace into a readable story

Raw TON messages contain serialized data rather than English instructions. One of the fastest ways to understand them is to inspect the operation code at the beginning of the message body.

An op code tells a contract which operation the message is requesting.

Several identifiers are especially useful when following a STON.fi jetton swap:

Message or payload	Identifier	What it tells you
Jetton transfer	0x0f8a7ea5	A jetton wallet has been asked to transfer tokens
Jetton transfer_notification	0x7362d09c	The receiving owner is being notified about the transferred jettons
STON.fi v2 swap payload	0x6664de2a	The transferred tokens are intended for a swap
STON.fi v2 pay_to	0x657b54f5	The Router is being instructed to perform settlement
Jetton excesses	0xd53276db	Remaining attached TON is being returned

The standard jetton values come from TEP-74, while STON.fi publishes its own DEX v2 operation code reference.

You do not need to memorize these numbers. Their value is diagnostic. If an explorer exposes raw or decoded message bodies, the op code lets you verify that a message really represents the operation you think it does.

A friendly label saying "Swap" is useful. A matching STON.fi swap payload inside the expected part of the trace is stronger evidence.

Following one jetton-to-jetton swap from start to finish

Consider a simple case: you swap Token A for Token B through a STON.fi liquidity pool.

The exact trace can vary depending on contract versions, token implementation, wallet deployment state, routing, and other parameters. Still, the basic asset flow gives you a reliable framework.

1. Your wallet starts the operation

A STON.fi frontend can use TON Connect to ask your wallet to send the required blockchain message. TON Connect itself does not take possession of your private keys. It establishes the wallet connection and lets the dApp request transaction signing.

In the explorer, begin at your wallet transaction.

Ask:

• Where did the outgoing message go?
• How much TON was attached?
• Is there a payload?
• Does the destination correspond to the expected jetton wallet or swap entry path?

For a jetton input, the first relevant contract is commonly your wallet for Token A rather than the liquidity pool itself.

2. Your offer jetton wallet moves Token A

TON jetton transfers are message chains of their own.

The standard transfer request tells your jetton wallet how many tokens to send and where they should go. The jetton wallet updates its balance and causes the receiving side's jetton wallet to receive the transferred amount. If forwarding is requested, a transfer_notification can then reach the owner of that receiving jetton wallet.

At this point, check the jetton amount, not only the TON attached to the internal message.

A common decoding mistake is to see a small TON value traveling with the message and assume it represents the size of the trade. For jetton swaps, the trade amount is encoded in the jetton operation. Attached TON is also used to fund execution and message forwarding.

3. The STON.fi Router recognizes the swap request

The Router is where the generic jetton transfer becomes a DEX operation.

STON.fi's Router documentation describes handling transfer_notification messages and forwarding swap requests to the appropriate Pool. STON.fi's v2 swap documentation also defines the swap payload that accompanies the token transfer.

This part of the trace is especially useful for debugging.

You want to establish that:

1. the correct input token arrived
2. the expected amount was recognized
3. the payload requested a swap
4. the request was routed to the intended pool

If the trace never reaches the expected Pool, the failure happened before actual AMM execution.

4. The Pool executes the exchange

The Pool is the point where the input becomes an output amount according to the pool's state and swap rules.

STON.fi's v2 Pool specification includes swap-related parameters such as the minimum output and receiver information. After successful execution, the Pool can send the swap result toward the Router for settlement through the documented payout flow.

When examining the Pool transaction, check more than whether an explorer colors it green.

Look for:

• successful compute and action phases
• no relevant bounce or error downstream
• the output amount
• the receiver
• whether the minimum output condition was satisfied

This is often the most informative transaction in the entire trace because it connects the trade request with the resulting amount.

5. The Router settles the output

After the Pool calculates the result, the output still has to reach you.

STON.fi documents the pay_to operation on the Router. This operation initiates the required jetton transfer from the Router side during swap settlement.

You can now follow Token B in the opposite direction from the input:

Pool result -> Router settlement -> output jetton transfer -> your Token B jetton wallet

If you lose the trail in a large trace, search for the expected output jetton and receiver address.

6. Your destination jetton wallet receives Token B

The strongest practical confirmation is the final asset movement.

Find the transaction that credits the Token B jetton wallet owned by your receiving address. Confirm the token identity and amount rather than relying only on a high-level "swap successful" label.

The trace may continue with excess TON refunds or other bookkeeping messages after the economic result of the swap is already clear. The jetton standard defines an excesses message specifically for returning remaining TON associated with an operation.

How do you prove the swap actually succeeded?

A green first transaction is not enough.

TON's asynchronous model allows one contract to process its message successfully while a later part of the trace encounters a different outcome. A swap should therefore be verified end to end.

A strong verification uses several signals together:

• The input moved: the correct quantity of the offer jetton left your jetton wallet.
• The Router received the intended operation: the relevant notification and STON.fi payload are visible.
• The Pool processed the swap: the pool-side transaction completed as expected.
• No later failure invalidated the intended path: inspect bounced or failed messages when present.
• The output moved: the correct ask jetton was transferred toward your receiver.
• The destination balance changed: your output jetton wallet received the resulting tokens.

STON.fi's API provides another convenient layer. Its swap status and transaction action endpoints can help summarize what the protocol recognized, while the raw trace remains the source for inspecting individual TON transactions and messages.

This combination is much more reliable than reading only the first or last line shown by a wallet.

Do not confuse attached TON with swap value or total fees

TON messages frequently carry TON because downstream contracts need funds to execute and send further messages.

That TON can move through several contracts during one trace. Some may pay transaction and forwarding fees, and unused amounts may later return as excesses.

TON's documentation describes this carry-value pattern: incoming value becomes part of the receiving contract balance, and contracts use message modes and reserve logic to fund subsequent execution.

So when you see several internal transfers such as 0.05 TON, 0.03 TON, or smaller amounts, do not simply add them together and call the result the swap fee.

Instead, separate three things:

1. The asset being traded, such as a jetton amount.
2. TON attached for execution, which can continue through the trace.
3. Actual blockchain fees, recorded for the individual transactions.

TON transactions expose their own fee information, and a multi-contract trace contains multiple transactions.

For a technical investigation, inspect the fee fields rather than estimating cost from visible message values.

Use the STON.fi action tree and raw trace together

There are two useful ways to decode the same swap.

The raw TON view answers questions such as:

• Which account processed this message?
• What was the incoming body?
• Which messages did it create?
• What were the exit results?
• How much TON was attached?
• Which token wallet received the output?

The STON.fi protocol view answers the higher-level question: what STON.fi actions were triggered by the originating transaction?

STON.fi's REST API includes POST /v1/transaction/action_tree, which returns a flattened list of STON.fi actions and their statuses triggered by an originating transaction. The API reference also documents transaction resolution and swap-status functionality.

For most investigations, use both.

Start with the action tree to understand the likely story. Then use the blockchain trace to prove each important part of that story.

That approach is faster than manually decoding every cell from the beginning, but it does not make you dependent on an indexer's interpretation.

A compact STON.fi swap decoding checklist

When inspecting an unfamiliar swap, work through these checks in order:

• Find the complete trace, not just your wallet transaction.
• Identify the token wallets, Router, Pool, and final receiver.
• Follow the offer asset, from your balance toward STON.fi.
• Inspect the swap payload and Pool transaction, including output conditions.
• Follow the ask asset, from settlement to your receiving jetton wallet.
• Review failures, bounces, excesses, and fees only after the main asset path is clear.

If the trace is complicated, ignore unrelated branches initially. The central question is always the same: where did the input asset go, what contract converted it, and where did the output asset arrive?

Once those three points are established, op codes, query IDs, fees, and excess messages become supporting evidence rather than noise.

Frequently Asked Questions

Does a STON.fi swap have one transaction hash?

Not necessarily in the sense Ethereum users usually expect. A TON transaction describes a state change on one account after processing a message. A STON.fi swap can involve several such transactions connected through internal messages. The useful object to inspect is therefore the full trace that begins with the wallet operation and continues through the contracts involved in the swap.

Why does my STON.fi swap contain so many transactions?

Because TON smart contracts communicate asynchronously. Your wallet, jetton wallets, Router, Pool, and destination token wallet can each process separate messages and therefore generate separate transactions. Additional transactions may appear for wallet deployment, refunds, excess TON, or other execution details. A long trace does not by itself indicate that anything went wrong.

Can I identify a STON.fi swap from its op code?

An op code is strong evidence, but it should not be your only check. STON.fi documents protocol-specific swap operation identifiers, while TON's jetton standard defines codes for transfers and notifications. Confirm the op code together with the contract address, message direction, token identities, amounts, and surrounding trace.

How do I know whether the swap really delivered my tokens?

Follow the output asset until the receiving jetton wallet is credited. Also confirm that the Pool and settlement transactions completed without a downstream failure that prevented the expected payout. A successful initiating wallet transaction alone is weaker evidence than seeing the actual output token movement in the trace.

Why is the TON amount in an internal message different from my swap amount?

For jetton swaps, the amount being traded is encoded as a jetton amount. TON attached to messages is also used to pay for contract execution and forwarding through the trace. Some unused TON can later be returned. Treat attached TON, jetton quantities, and blockchain fees as separate values when decoding the operation.

Does a TON-to-jetton swap have exactly the same trace?

No. Native TON requires a different token path from an ordinary jetton-to-jetton exchange, so the exact contracts and messages can differ. STON.fi provides dedicated TON-to-jetton and jetton-to-TON swap methods in its DEX tooling. The same decoding principle still works: identify the input path, find the Pool execution, then follow the output to its final owner.

What is the fastest way to decode a STON.fi swap transaction?

Start with the full TON trace, identify the offer and ask token flows, and compare what you see with STON.fi's transaction action tree. Use friendly explorer labels to navigate quickly, but verify important conclusions from contract addresses, message bodies, op codes, amounts, and the final token transfer. That gives you both a readable summary and low-level confirmation.

Sources and Further Reading

• STON.fi DEX v2 Swap Examples - official message-flow examples for swaps and multi-step execution
• STON.fi DEX v2 Op Codes - official reference for STON.fi smart contract operation identifiers
• STON.fi Router v2 - official documentation for Router message handling and settlement operations
• STON.fi Pool v2 - official documentation for Pool state and swap-related operations
• STON.fi API Reference - transaction resolution, swap status, and transaction action tree endpoints
• TON Messages and Transactions Overview - explains how messages, account transactions, fees, and traces relate
• TON Traces - official explanation of causal message traces and their representation in explorers
• TON Jetton Standard - overview of jetton masters and per-owner jetton wallet contracts
• TON Connect Send Transaction - official documentation for wallet transaction requests from dApps

Comments

[Ivan “Crypto Vazima” Zimanov]

Hi. If you find an error, please let us know. This will help everyone else who might be looking into this issue! Thanks for your support!