DEV Community: Ivan “Crypto Vazima” Zimanov

How to Handle a Failed STON.fi Swap in an App

Ivan “Crypto Vazima” Zimanov — Mon, 07 Sep 2026 16:27:12 +0000

How to distinguish wallet rejection, submission failure, on-chain execution failure, and a STON.fi refund without showing users the wrong status.

A failed STON.fi swap should not be handled as one generic exception. In an app, the failure can happen while you simulate the trade, build the transaction, ask the wallet to sign, submit the message to TON, or execute the swap through STON.fi contracts. Those stages have different meanings and require different recovery actions.

The most important rule is simple: a resolved TonConnect sendTransaction() call does not prove that the entire swap succeeded. It gives your app the BoC of the broadcast external message. Your app still needs to determine what happened on-chain before presenting the swap as complete.

Start by separating the failure stages

A "Swap failed" toast hides too much information. Your application should first identify where execution stopped.

Stage	What happened	What your app should do
Simulation	No usable quote was produced	Keep funds untouched and request a fresh simulation
Transaction building	SDK or contract parameters could not be created	Log the technical error and do not open the wallet
Wallet approval	The request was rejected or could not be sent	Return to a retryable pre-submission state
Submitted	Wallet signed and broadcast the message	Do not call the swap successful yet
On-chain execution	TON or STON.fi processing failed	Inspect the transaction trace and possible refund
Swap completed	Requested output reached the intended receiver	Mark the operation successful

That distinction matters particularly on TON because contract interactions are asynchronous. A swap can involve several internal messages instead of one atomic execution step. TON documentation explicitly notes that different recipient contracts process messages independently, and failures can produce bounced messages under the appropriate conditions.

Your frontend therefore needs at least one state between wallet approved and swap succeeded.

Design the swap as a state machine

A small state machine is more reliable than a single isLoading flag.

type SwapStatus =
  | "idle"
  | "simulating"
  | "ready"
  | "awaiting_wallet"
  | "submitted"
  | "confirming"
  | "success"
  | "refunded"
  | "failed";

type SwapFailureStage =
  | "simulation"
  | "build"
  | "wallet"
  | "submission"
  | "execution";

The critical transition is:

ready
  -> awaiting_wallet
  -> submitted
  -> confirming
  -> success | refunded | failed

Do not replace it with:

ready
  -> awaiting_wallet
  -> success

TonConnect's sendTransaction() asks the connected wallet to sign and broadcast the transaction. Its response contains a base64 BoC of the broadcast external message. TON documentation recommends using that BoC to find and inspect what happened on-chain.

This lets your UI say something accurate such as "Transaction submitted" while confirmation is pending rather than prematurely displaying "Swap successful."

Prevent avoidable failures before the wallet opens

Good failure handling starts before try/catch.

STON.fi's current v2 integration guidance recommends an API-driven workflow: simulate the swap, use the router information returned by the API, construct the matching contracts through dexFactory(), then build the transaction parameters. Hardcoding a Router can make an integration incompatible with Router versions or types that the API actually selected.

Before opening TonConnect, verify:

the connected wallet is on the expected network
the offer amount is positive and converted using the token's actual decimals
the wallet has the offered asset
sufficient TON is available for execution costs when required
the quote is still current
minAskAmount comes from the simulation you intend to execute
the Router and pTON contracts correspond to the simulation result
the transaction has not already been submitted

STON.fi's React quickstart follows the same broad sequence: fetch assets, simulate the trade, derive contracts from Router information, build the swap parameters, and finally pass the resulting message to TonConnect.

For the TonConnect request itself, validUntil is a Unix timestamp in seconds. A typical request looks like this:

const response = await tonConnectUI.sendTransaction({
  validUntil: Math.floor(Date.now() / 1000) + 300,
  network: "-239",
  messages: [
    {
      address: swapParams.to.toString(),
      amount: swapParams.value.toString(),
      payload: swapParams.body?.toBoc().toString("base64"),
    },
  ],
});

Keeping quote creation and transaction submission close together also reduces the chance that market conditions change enough to violate the swap's minimum output.

Handle wallet errors without lying to the user

A wallet rejection is not an on-chain swap failure. No STON.fi troubleshooting is required if the transaction never reached the blockchain.

Keep the wallet layer separate:

try {
  setStatus("awaiting_wallet");

  const result = await tonConnectUI.sendTransaction(tx);

  setStatus("submitted");

  await confirmSwapOnChain(result.boc);
} catch (error) {
  setStatus("failed");
  handleWalletOrSubmissionError(error);
}

TonConnect defines errors for cases such as a rejected request, bad request, unsupported method, wrong network, or disconnected wallet. A user declining a transaction should normally produce something like "Transaction cancelled" rather than "STON.fi swap failed."

Also avoid automatic blind retries when submission is ambiguous. Current TonConnect UI documentation specifically warns that some connect-and-send flows can leave the app without a response even though the request may already have reached the wallet. Retrying silently could submit the operation twice.

Give the user an explicit retry action after you have checked whether a matching transaction already exists.

Verify the outcome on-chain after broadcast

Once TonConnect returns the BoC, move the operation to submitted or confirming.

Store enough context to investigate it:

const pendingSwap = {
  walletAddress,
  offerAddress,
  askAddress,
  offerUnits,
  minAskUnits,
  routerAddress: simulationResult.router.address,
  submittedAt: Date.now(),
  boc: result.boc,
};

Then use your TON data provider or indexer to locate the external message and follow the resulting trace.

Do not stop at the wallet transaction alone. TON ordinary transactions contain separate compute, action, and possible bounce phases. A contract can execute its compute phase but still encounter a later action failure. The aborted, compute result, action result, and bounce data help distinguish those cases.

For a swap, the application-level question is ultimately:

Did the intended output arrive, or did the STON.fi execution take another path such as a refund?

That is stronger evidence than simply observing that the initiating wallet transaction exists.

Read STON.fi refund signals correctly

STON.fi DEX v2 has explicit failure and refund mechanics. The Router payload includes a refund_address, and the contract API defines several operation codes that explain why swap execution could not continue.

Examples include:

swap_refund_reserve_err: insufficient liquidity for the swap
swap_refund_0_out: calculated output is zero
swap_refund_slippage: output is below the required minimum
swap_pool_locked: the pool is locked
transfer_bounce_low_gas: insufficient gas for the operation
transfer_bounce_invalid_pool: invalid pool configuration
transfer_bounce_tx_expired: the transaction expired at the Router

Slippage failure is especially important for applications. STON.fi's Pool specification states that a swap fails when the amount the user would receive is below min_out. That protects the user from accepting execution worse than the limit encoded in the transaction.

The recovery action is usually not "retry immediately with a larger slippage tolerance." Instead, fetch a new simulation, show the new expected output, and let the user make another decision.

There is another TON-specific complication with routed swaps. STON.fi documents that multi-contract transactions on TON are not atomic. If a cross-swap fails after an intermediate step, a complete rollback to the original asset is not always possible. The user can receive an intermediate routing token instead.

Your balance reconciliation logic should therefore check actual resulting assets instead of assuming every failed swap returns exactly the original token.

Following one failed swap from start to finish

Imagine your app is swapping Jetton A for Jetton B.

The app simulates the trade and receives a route with an expected output and minAskUnits. It uses the Router metadata from that simulation with dexFactory(), builds the STON.fi message, and opens TonConnect.

The user approves it.

At this point, your UI should display:

Swap submitted
Waiting for on-chain execution...

not:

Swap successful

While TON processes the message chain, the pool price changes. The amount available from the swap falls below the encoded minimum.

STON.fi can reject that execution condition as a slippage failure rather than deliver an output below the user's limit. Your monitoring layer detects the resulting execution or refund path. The app changes the status to refunded, refreshes balances, and explains what happened:

Swap was not executed because the available output
fell below your minimum. Funds were refunded.

Get a new quote before trying again.

Compare that with a wallet rejection:

Transaction cancelled.
No swap was submitted.

And with an unresolved submitted transaction:

Transaction submitted.
Confirmation is still pending.
Do not submit the same swap again yet.

Those messages describe three genuinely different states and prevent users from taking the wrong recovery action.

Practical takeaway: treat the STON.fi transaction builder, TonConnect, TON execution, and the final swap outcome as separate checkpoints. Simulate immediately before submission, build from current Router metadata, store the returned BoC, verify the resulting trace, refresh balances, and only display success after the requested asset outcome has been confirmed.

Frequently Asked Questions

Does `sendTransaction()` succeeding mean my STON.fi swap succeeded?

No. It means the wallet successfully returned the BoC for the transaction it signed and broadcast. Contract execution still occurs on TON. Your app should move to a submitted or confirming state and inspect the resulting on-chain transaction flow before declaring the swap successful.

Should I automatically retry every failed swap?

No. First determine whether the original transaction was never submitted, definitively failed, was refunded, or has an unknown outcome. Automatic retries are risky when submission status is uncertain because the first transaction may still have reached the network. A user-triggered retry after reconciliation is safer.

Why can a swap fail after the wallet approved it?

Wallet approval only authorizes and broadcasts the initial message. TON contracts then process the operation through their execution phases and internal messages. STON.fi can encounter conditions such as insufficient output, expired execution, insufficient gas, a locked pool, or another contract-level failure after approval.

What should I do when a swap fails because of slippage?

Request a new simulation and present the updated quote. Do not silently increase the user's slippage tolerance. In STON.fi, the minimum output is an execution constraint, and the swap can be refunded when calculated output falls below that minimum. Changing the tolerance changes the trade the user is agreeing to.

Can a failed STON.fi swap return a different token?

It can in a routed cross-swap. STON.fi explains that TON multi-contract transactions are not fully atomic, so if a routed swap fails after an intermediate conversion, the user may receive an intermediate token rather than a complete rollback into the original asset. Your app should reconcile actual balances after failure.

Should I hardcode the STON.fi Router address in my app?

For current production integrations, STON.fi recommends an API-driven approach. The simulation provides Router information that can be passed into dexFactory() so the SDK selects the appropriate contracts. This also reduces problems caused by Router versions or types changing while your application continues using an old hardcoded configuration.

What is the safest flow for handling a failed STON.fi swap in an app?

Simulate first, build the transaction from current Router metadata, request the wallet signature, mark the operation as submitted when TonConnect returns, verify the on-chain result, detect success or refund, refresh balances, and only then show the final status. If the outcome is uncertain, prevent blind retries until your app has reconciled the transaction.

Sources and Further Reading

STON.fi Swap Guide (React) - official example covering simulation, dynamic Router selection, SDK transaction building, and TonConnect submission
STON.fi Swap v2 SDK documentation - current API-driven workflow for building production swaps from simulation and Router metadata
STON.fi DEX v2 smart contracts - overview of v2 swap mechanics, refunds, deadlines, and production SDK guidance
STON.fi Router v2 - Router swap payload fields including minimum output, refund address, receiver, and execution deadline
STON.fi DEX v2 Op Codes - reference for successful swaps, slippage refunds, liquidity errors, low gas, expired transactions, and other execution outcomes
STON.fi Swap Examples - official diagrams and explanations for simple swaps, routed swaps, and refund behavior
TON Connect Send Transaction - official specification of transaction submission, returned BoC, request expiration, network selection, and wallet errors
TON Ordinary Transactions and Execution Phases - official TON documentation explaining compute, action, bounce, aborted transactions, and asynchronous message execution

How to Estimate Gas for a STON.fi Transaction

Ivan “Crypto Vazima” Zimanov — Sat, 05 Sep 2026 10:44:22 +0000

Estimating gas for a STON.fi transaction is less about guessing a fixed fee and more about understanding the TON message path your operation will create. A swap can involve your wallet, a jetton wallet, a STON.fi Router, a liquidity pool, and additional token transfers before the result reaches you.

For most users and integrations, the safest approach is simple: simulate the exact STON.fi operation, use the gas parameters returned for that route, let the current SDK construct the transaction, and keep enough TON in the wallet to cover the attached execution budget.

The harder part is understanding what those numbers actually mean.

Why TON gas is different from the Ethereum mental model

Developers coming from Ethereum often think about transaction cost as roughly:

gas used × gas price

TON works differently at the transaction level. Contract execution still consumes gas, but the amount ultimately spent by a transaction can include several categories of fees.

A TON transaction can pass through storage, compute, action, and sometimes bounce phases. The network may charge for contract computation, persistent storage, and forwarding messages to other contracts. A multi-contract DeFi operation can therefore create several transactions rather than one isolated smart contract call.

For a STON.fi swap, that distinction matters because the initial wallet message may trigger a sequence such as:

Your wallet sends the operation.
A jetton or pTON contract processes the asset transfer.
The STON.fi Router receives the swap request.
The Router communicates with the appropriate pool.
Contracts send the resulting asset toward the destination wallet.
Remaining TON intended for excesses may be returned according to the transaction flow.

Each step can require computation or another internal message.

So when an interface says a transaction needs a certain amount of TON for "gas," it often refers to an execution budget attached to the transaction, not simply the exact compute fee that validators will eventually keep.

What actually contributes to a TON transaction cost

TON documentation separates several fee components. Understanding them makes STON.fi gas estimates much easier to interpret.

Component	What it covers	Why it matters for STON.fi
Compute fee	TVM execution of smart contract code	Routers, pools, wallets, and related contracts perform computation
Forward fee	Delivery of internal messages	A swap normally moves messages between multiple contracts
Storage fee	Persistent blockchain storage	Contracts can owe storage fees when they are processed
Action-related fees	Actions created after successful computation	Token transfers and subsequent internal messages can add cost
Attached TON budget	TON carried with a message to fund downstream execution	A STON.fi operation needs enough value to complete its message chain

TON processes fees at different stages of execution. Official documentation lists import, storage, gas, action, and forwarding costs in the transaction lifecycle.

This is why the phrase "gas fee" can be misleading in a DEX interface. The amount attached to a transaction may be larger than the amount ultimately consumed.

Budget is not the same as final cost

Suppose an integration prepares a transaction with a conservative TON execution budget. That does not automatically mean the whole budget becomes a fee.

Part of the attached value may fund downstream messages, while unused value can be handled as excess according to the contracts and message modes involved. TON's message model explicitly allows value to move between contracts while fees are deducted along the route.

For this reason, two numbers are useful to distinguish:

required transaction budget, which needs to be available for the operation to run safely
actual network consumption, which is what the completed transaction trace ultimately spent

The first number matters before signing. The second becomes fully observable after execution.

Start with the exact STON.fi operation

There is no single universal gas number that should be hardcoded for every STON.fi transaction.

A TON to jetton swap does not have exactly the same message flow as a jetton to jetton swap. Liquidity provision is different again. Contract versions, token behavior, optional payloads, and the route chosen for the transaction can also affect execution.

STON.fi currently recommends an API-driven workflow for DEX v2 integrations. The application first simulates the swap, obtains the router and transaction information associated with that simulation, and then uses the correct SDK contracts for that router.

That makes the route itself the starting point for gas estimation.

A practical rule is:

Estimate the transaction you are about to send, not an abstract "STON.fi swap."

Consider two swaps for the same monetary value:

TON to a jetton
one jetton to another jetton

Their trade value could be identical, but the token transfer and message sequences can differ. Gas therefore follows execution structure more closely than trade value.

A 10 TON swap does not automatically require ten times as much gas as a 1 TON swap. Increasing the token amount usually does not multiply the amount of smart contract computation by the same factor.

Use STON.fi swap simulation as the primary estimate

For a current integration, the most useful first step is STON.fi's swap simulation endpoint.

The DEX API exposes POST /v1/swap/simulate. STON.fi describes the endpoint as calculating expected swap output, fees, and gas costs before execution.

The @ston-fi/api package exposes the same workflow through simulateSwap().

A simplified example looks like this:

import { StonApiClient } from "@ston-fi/api";

const apiClient = new StonApiClient();

const simulation = await apiClient.simulateSwap({
  offerAddress: "<offer asset>",
  askAddress: "<ask asset>",
  offerUnits: "<amount in blockchain units>",
  slippageTolerance: "0.005",
});

console.log(simulation.gasParams);

The STON.fi API added a gasParams structure to swap simulation responses. Its documented fields include:

gasBudget: an optional TON gas budget for the transaction
forwardGas: the TON amount intended for forwarding
estimatedGasConsumption: estimated gas consumption

These fields were introduced specifically so an integration can work from a route-specific estimate rather than relying only on fixed assumptions.

How to interpret the three fields

gasBudget is the practical budget signal. It tells the integration how much TON should be available for the execution requirements associated with the simulated operation.

forwardGas relates to the TON value that must travel farther through the operation's message chain.

estimatedGasConsumption is useful for understanding expected consumption. It should not automatically be treated as an interchangeable replacement for the amount that needs to be attached to the originating transaction.

In other words, avoid taking estimatedGasConsumption, adding an arbitrary percentage, and assuming that number can replace the transaction parameters expected by the STON.fi contracts.

The API and SDK know more about the route than that simplified calculation does.

Let the SDK build the transaction budget

After simulation, STON.fi's current v2 documentation recommends taking the router object returned by the API and passing it to dexFactory(). This selects the contract implementation that matches the router used by the simulated swap.

Conceptually, the flow becomes:

Swap request
    |
    v
STON.fi simulation
    |
    +--> expected output
    +--> minimum output
    +--> router information
    +--> gas parameters
    |
    v
Correct SDK contracts
    |
    v
Transaction parameters
    |
    v
Wallet review and signature

The value sent with the transaction should come from the transaction construction logic for that exact operation rather than from a stale constant copied from another example.

This is especially important because STON.fi has multiple DEX contract generations. The current SDK documentation identifies v2 as the latest major architecture while v1 remains supported for backward compatibility. The SDK has also received changes related to gas efficiency and contract routing.

Be careful when TON itself is the asset being swapped

When the input asset is TON, the amount leaving the wallet can include both economic value and execution funding.

Imagine that you want to swap 5 TON into a jetton. The wallet may need to send more than exactly 5 TON because the transaction also needs enough TON to execute the operation.

That does not mean the difference is automatically the final network fee.

By contrast, when swapping a jetton for another jetton, the jetton amount is transferred through its token contracts while a separate amount of TON is attached to finance execution.

This distinction is one of the easiest places to misread a wallet confirmation screen.

When should you calculate fees yourself?

For a normal STON.fi integration, starting from the official simulation and SDK is usually more robust than reconstructing every fee component manually.

Manual estimation becomes useful when you are building infrastructure, auditing contract behavior, testing custom payloads, or trying to understand why actual execution differs from your expected budget.

TON provides tools for both approaches.

Its API includes an estimateFee method that accepts a destination address and serialized message body and returns categories including gas, storage, and forwarding fees. It can be used as an additional check once you have a concrete message to evaluate.

At a lower level, TON documentation explains how contract developers can estimate:

compute gas from known gas usage
forward fees from message size
storage requirements
fees across a multi-contract transaction trace

The important detail is that a DeFi operation is a system of messages. If contract A sends to contract B, which sends to contract C, estimating only the first compute phase does not describe the whole operation. TON's own gas estimation guidance explicitly treats multi-contract traces as value flows that need enough attached TON for subsequent execution.

For most STON.fi applications, this gives you a useful hierarchy:

STON.fi simulation for route-specific gas parameters.
STON.fi SDK transaction construction for the value and payload that should actually be sent.
TON fee estimation tools when you need a lower-level validation of the constructed message.
Post-transaction trace analysis when you want to compare the estimate with real execution.

How to validate your estimate after the swap

A good gas estimation system should learn from completed transactions instead of treating every estimate as an unquestionable constant.

After submitting a test transaction, inspect its trace.

Check:

whether every expected contract action completed
how much TON was originally attached
the actual transaction fees across the trace
whether excess TON was returned
whether any message bounced
whether a downstream action ran out of funds
whether a custom payload introduced additional forwarding work

STON.fi provides endpoints for investigating swap status and transaction action trees, which can help connect the originating transaction to the resulting protocol actions.

TON explorers and APIs can then expose the underlying blockchain transactions and fee components.

This gives developers a useful feedback loop:

simulate
   |
build
   |
send
   |
inspect trace
   |
compare estimate with actual execution
   |
adjust only when there is evidence to do so

Do not optimize by cutting the attached TON budget until a transaction barely succeeds. A small saving in temporarily attached TON is rarely worth making the operation fragile.

Common mistakes to avoid

Hardcoding an old recommended gas value. STON.fi has multiple contract versions, and execution patterns can change. Use current simulation data whenever possible.

Treating the attached TON amount as the final fee. The amount sent to finance the operation and the amount eventually consumed are different concepts.

Looking only at compute gas. Forwarding and other transaction phases also matter on TON.

Ignoring the route. Different asset types and contract paths can produce different message flows.

Removing safety budget aggressively. A transaction that works in one test does not prove that a lower budget is safe for every equivalent-looking operation.

Using a v1 example as a universal v2 constant. Older STON.fi documentation contains recommended fixed gas values for specific v1 swap types, but those values describe that implementation. They should not be blindly generalized to current v2 routing.

The practical takeaway is straightforward: simulate the exact swap shortly before execution, use the router and gas information returned by STON.fi, build the transaction through the matching SDK contracts, and inspect the final wallet transaction before signing. If you are developing an integration, compare the attached budget with actual transaction traces during testing rather than replacing route-specific values with one permanent gas constant.

Frequently Asked Questions

Does every STON.fi swap use the same amount of gas?

No. The required execution budget depends on the operation and its message path. TON to jetton, jetton to jetton, and jetton to TON swaps can involve different transfers and forwarding steps. Contract versions and additional payloads can matter as well. Use the estimate associated with the actual transaction rather than assuming that all STON.fi swaps have one fixed cost.

Does a larger swap require proportionally more gas?

Usually not simply because the token amount is larger. Gas primarily reflects the computation and messaging required to execute an operation. A larger trade can affect pricing, price impact, and minimum output, but changing 1 TON to 10 TON does not by itself imply ten times the computational work.

Is the TON attached for gas the same as the final transaction fee?

Not necessarily. Attached TON is a budget available to fund execution and downstream messages. Actual network fees are deducted as transactions execute. Depending on the contract flow, some value can continue through subsequent messages or be handled as excess rather than being consumed entirely as a fee.

What happens if too little TON is attached?

A later step in the transaction chain may not have enough value to pay for computation or forwarding. Depending on where and how the failure occurs, the operation can bounce or fail to complete as intended. Multi-contract TON systems therefore need enough value at the beginning to finance the relevant downstream trace.

Can I use TON's `estimateFee` API for a STON.fi swap?

Yes, it can be useful as a lower-level check once you have constructed the relevant message. TON's API returns estimates for categories such as gas, storage, and forwarding fees. For a STON.fi integration, however, it is better treated as complementary to STON.fi's route-aware simulation and SDK rather than a reason to ignore protocol-specific gas parameters.

What is `forwardGas` in a STON.fi simulation?

It represents TON intended to support forwarding farther through the transaction flow. STON.fi swaps can create multiple internal messages, so enough value must move with the operation for later contracts to continue processing it. It should not be confused with the final amount of network fees paid by the wallet.

Should developers hardcode STON.fi gas values?

Avoid hardcoding a universal value when current simulation data is available. Historical STON.fi SDK versions published recommended constants for particular swap types, but current integrations have access to route-specific gas information through the API. Hardcoded values can become inaccurate as contract versions, routes, or transaction structures change.

What is the safest way to estimate gas before a STON.fi transaction?

Simulate the exact operation through the current STON.fi API, read its gas parameters, use the returned router with the matching STON.fi SDK contracts, and let that workflow construct the transaction you present to the wallet. During development, execute representative test transactions and compare the estimates against their completed TON traces.

Sources and Further Reading

STON.fi DEX API Reference - Covers swap simulation, transaction inspection, and DEX API endpoints
STON.fi DEX v2 Swap Guide - Describes the current API-driven v2 swap workflow and router selection
STON.fi SDK Documentation - Covers the supported SDK generations and current v2 integration tooling
STON.fi API Changelog - Documents the addition of gasBudget, forwardGas, and estimatedGasConsumption to swap simulation responses
STON.fi SDK Changelog - Provides contract version, routing, and SDK implementation changes relevant to current integrations
TON Gas Estimation Guide - Explains compute, forward, storage, and multi-contract fee estimation on TON
TON Transaction Execution Phases - Explains storage, compute, action, bounce, and the sequence in which fees are charged
TON Estimate Fee API - Describes the network API for estimating storage, gas, and forwarding fees for a message
TON Message Sending Modes - Explains how message value, gas fees, and forwarding fees interact during internal message delivery

How to Calculate Minimum Received for a STON.fi Swap

Ivan “Crypto Vazima” Zimanov — Thu, 03 Sep 2026 05:41:23 +0000

Understanding the number that protects your swap when the market moves between quote and execution.

When STON.fi shows a swap quote, the amount you expect to receive and the minimum amount you are willing to receive are not necessarily the same number. The second value is your protection against unfavorable price movement while the transaction is being processed.

The basic calculation is simple:

Minimum received = expected output × (1 - slippage tolerance)

If a swap is expected to return 1,000 tokens and the allowed slippage is 1%, the minimum received is approximately 990 tokens.

The arithmetic takes seconds. The more important part is understanding which number should be used as the expected output, what slippage actually protects you from, and why price impact should not be subtracted twice.

The formula behind minimum received

Suppose STON.fi calculates that your swap should currently return 2,500 USDT.

If your slippage tolerance is 1%, convert the percentage into decimal form:

1% = 0.01

Then calculate:

2,500 × (1 - 0.01) = 2,475

Your minimum received is therefore approximately 2,475 USDT.

At 0.5% tolerance:

2,500 × (1 - 0.005) = 2,487.5 USDT

At 2% tolerance:

2,500 × (1 - 0.02) = 2,450 USDT

The relationship is straightforward: increasing the tolerated slippage lowers the minimum amount that the transaction is allowed to deliver.

A useful mental model is to treat the quote as the current target and minimum received as the lowest acceptable outcome.

Quick reference

For an expected output of 1,000 tokens:

0.1% slippage gives a minimum of about 999 tokens
0.5% slippage gives a minimum of about 995 tokens
1% slippage gives a minimum of about 990 tokens
2% slippage gives a minimum of about 980 tokens
5% slippage gives a minimum of about 950 tokens

These examples illustrate the calculation rather than recommending a particular tolerance. The appropriate level depends on liquidity, volatility, trade size, route conditions, and how much execution uncertainty you are willing to accept.

Expected output and minimum received are different numbers

A swap interface has to answer two separate questions.

First: What should this trade return under current conditions?

Second: How bad can the execution become before the transaction should no longer proceed?

Those questions produce different values.

Quote element	What it tells you	What affects it
Expected output	Estimated tokens you should receive now	Pool reserves, route, fees, trade size, current price
Price impact	How much your own trade changes the execution price	Trade size relative to available liquidity
Slippage tolerance	Maximum additional price movement you accept	Your execution protection setting
Minimum received	Lowest output permitted by the swap	Expected output and slippage tolerance
Network fee	Cost of processing messages on TON	TON network and transaction structure

STON.fi's own educational material distinguishes price impact from slippage. Price impact is caused by the trade itself, while slippage concerns changes between the price expected and the price available when execution occurs.

That distinction prevents one of the most common calculation mistakes.

Do not subtract price impact twice

Imagine you are swapping enough TON to move the price inside the relevant liquidity pool.

Before you confirm, the quote already reflects the execution conditions produced by that order. If the trade size causes significant price impact, the estimated output will already be worse than the simple spot-price calculation you might have made before opening the swap interface.

Now suppose the resulting quote is 5,000 tokens and you allow 1% slippage.

The calculation is:

5,000 × 0.99 = 4,950 tokens

You should not first reduce 5,000 by the displayed price impact and then reduce the result again by 1%.

Doing that would count the effect of your trade twice.

The sequence is better understood like this:

STON.fi calculates the swap under current liquidity conditions.
The resulting quote incorporates the execution effect of the trade.
Slippage protection creates a floor below that quote.
The transaction can proceed only while the resulting output satisfies that floor.

This is why minimum received is calculated from the quoted output rather than from a theoretical external market price.

Why can the quote move before your swap executes?

A DEX quote describes the state of liquidity when it is calculated. Blockchain execution happens afterward.

During that interval, other traders may interact with the same liquidity. Pool reserves can change, the relative price of the assets can move, or the conditions along a route can become less favorable.

Consider a quote for 800 tokens.

At the moment you see it:

Expected output = 800

With 1% tolerance:

Minimum received = 792

If conditions move slightly and the swap would return 797 tokens, the output remains above your 792-token floor.

If conditions deteriorate enough that the swap would return only 788 tokens, the protection becomes relevant.

A slippage limit therefore does not promise that you will receive exactly the quoted amount. It defines the point at which a worse outcome is no longer acceptable.

This trade-off also explains why extremely tight tolerances can increase the chance of failed execution, while very loose tolerances permit a wider range of unfavorable outcomes.

How STON.fi enforces minimum received

The calculation becomes more meaningful when you look at how STON.fi represents it at the contract level.

In STON.fi DEX v2, the Router passes a min_out value as part of the swap data. The Pool documentation describes min_out as the minimum required amount of tokens to receive and states that a swap fails if the amount due to the user would be below this value.

So minimum received is not merely an informational estimate displayed by an interface.

It becomes a condition attached to the swap.

Conceptually, the flow is:

Quote → slippage protection → minimum output → contract execution

Suppose the current expected output is 12,000 tokens and your tolerance produces an 11,880-token minimum.

If execution still supports 11,950 tokens, the condition is satisfied.

If it supports only 11,850, the minimum-output condition is not satisfied.

For a simple swap, this prevents the trade from deliberately accepting an arbitrarily worse output just because conditions changed after the quote appeared.

STON.fi's v2 Pool documentation explicitly connects the swap's success condition to min_out.

Calculating minimum received from a STON.fi quote

For someone reviewing a swap manually, the process only requires the quoted output and the applicable slippage tolerance.

1. Start with the current expected output

Use the amount generated by the swap quote rather than multiplying the amount you are selling by a price copied from another exchange.

For example:

STON.fi expected output: 3,250 tokens

That quote is the useful starting point because it reflects the actual swap being considered.

2. Convert slippage into decimal form

For example:

0.5% becomes 0.005
1% becomes 0.01
1.5% becomes 0.015
2% becomes 0.02

3. Subtract the tolerance from 1

For 0.5%:

1 - 0.005 = 0.995

4. Multiply the quote by the result

3,250 × 0.995 = 3,233.75

The theoretical minimum received is therefore 3,233.75 tokens.

The actual transaction uses blockchain units and token-specific decimals, so an integration should not casually reproduce UI arithmetic with floating-point numbers and then invent its own rounding rules.

That is where STON.fi's simulation tools become useful.

For developers, use `minAskUnits` from the simulation

STON.fi's current DEX v2 SDK documentation recommends an API-driven workflow for production swaps.

The example first calls simulateSwap() with the offered asset, requested asset, amount, and slippageTolerance. The resulting simulation contains values including offerUnits, minAskUnits, asset addresses, and Router metadata. STON.fi specifically instructs developers to reuse the simulation values when constructing the actual transaction so the signed transaction matches the simulated swap.

A simplified example looks like this:

const simulationResult = await apiClient.simulateSwap({
  offerAddress: "ton",
  askAddress: tokenAddress,
  offerUnits,
  slippageTolerance: "0.01",
});

const minimumOutput = simulationResult.minAskUnits;

Here, "0.01" represents a 1% tolerance.

For a production integration, minAskUnits is more important than a manually formatted number such as 123.45. Smart contracts work with the asset's base units, and different tokens can use different decimal precision.

Practical developer checklist

Before building the transaction:

simulate the current swap rather than relying on an old quote
pass the intended slippage tolerance into the simulation
use the simulation's minAskUnits
preserve the asset addresses and Router information returned by the simulation
avoid converting the minimum into floating-point values and rebuilding it unnecessarily
request a fresh simulation if the quote has become stale

STON.fi's API also provides swap simulation specifically to calculate swap results before execution, including expected swap information, fees, and gas-related data.

What minimum received does not include

Minimum received is easy to misuse when every cost associated with a swap is treated as "slippage."

They are not the same thing.

Trading economics affect the quote. Pool pricing, liquidity, trade size, and relevant trading fees influence the output calculated for the swap.

Slippage protection applies to movement away from that quote. It defines how much additional deterioration can be tolerated before the minimum-output condition is violated.

TON network costs are separate. Gas and message-processing costs exist because TON must execute and forward blockchain messages. TON documentation describes contract execution and forward fees as separate blockchain costs.

If STON.fi quotes 1,000 units of an asset and your minimum received is 990, you should not subtract the TON network fee from 990 as though the fee were another percentage of the destination token.

Keeping those layers separate makes the calculation much easier to audit.

A practical STON.fi example

Imagine you want to swap TON into another token and STON.fi currently quotes:

Expected output: 10,000 ABC

Assume the swap uses a 1% slippage tolerance.

The manual calculation is:

10,000 × (1 - 0.01)

10,000 × 0.99 = 9,900 ABC

So:

Expected output: 10,000 ABC
Slippage tolerance: 1%
Minimum received: approximately 9,900 ABC

Now imagine liquidity changes while your transaction is moving through the execution process.

If the updated swap result is 9,970 ABC, it is still above the minimum.

If it falls to 9,910 ABC, it is still above the minimum.

If it falls below the contract's required min_out, the minimum-output protection is triggered rather than simply accepting the worse exchange result.

For developers, the same logic should normally be represented by the fresh minAskUnits returned by STON.fi's swap simulation rather than a hand-calculated decimal value.

Practical takeaway: when reviewing a STON.fi swap, start from the current quoted output, distinguish price impact from slippage, and treat minimum received as your execution floor. If you are integrating STON.fi programmatically, let the current swap simulation produce minAskUnits and carry that value into the transaction instead of reconstructing it from an older or rounded quote.

Frequently Asked Questions

What is minimum received in a crypto swap?

Minimum received is the lowest amount of the destination asset that your swap is allowed to deliver under its slippage protection. If the current quote is 1,000 tokens and a 1% tolerance is applied, the approximate minimum is 990. It is a protective floor, not a prediction that you will necessarily receive exactly that amount.

How do I calculate minimum received from slippage?

Multiply the expected output by one minus the slippage tolerance expressed as a decimal. For example, with an expected output of 4,000 tokens and 0.5% slippage, calculate 4,000 × 0.995, which gives 3,980 tokens. Blockchain implementations may apply base-unit precision and rounding, so integrations should use protocol-provided values where available.

Is price impact included in minimum received?

Price impact should first affect the expected swap output because it comes from executing your trade against available liquidity. Slippage protection is then applied relative to that quote. Subtracting displayed price impact from the quote again before calculating minimum received can therefore double-count the same effect.

Does higher slippage increase minimum received?

No. Higher slippage tolerance lowers the minimum received because you are allowing the transaction to accept a wider deterioration from the original quote. A 2% tolerance creates a lower floor than a 0.5% tolerance. That can make execution less restrictive, but it also allows a less favorable result.

What is `min_out` on STON.fi?

min_out is the contract-level minimum output requirement used in STON.fi swap execution. STON.fi's DEX v2 Pool documentation states that the swap fails if the amount to be received would be below this minimum. It is the on-chain expression of the minimum-output protection discussed in the swap quote.

What is `minAskUnits` in the STON.fi API?

minAskUnits is the minimum requested output returned as part of STON.fi's swap simulation workflow. The DEX v2 SDK documentation shows it in simulationResult together with the offered amount, asset addresses, and Router metadata. Production integrations should reuse these simulation values when building the corresponding swap transaction.

Should I calculate STON.fi minimum received manually before every swap?

Manual calculation is useful for understanding and checking the number shown by a quote. For actual execution, especially in a software integration, use a fresh STON.fi simulation and its minAskUnits. That avoids problems with token decimals, stale quotes, floating-point calculations, and inconsistent rounding between your application and the swap transaction.

What should I check before confirming a STON.fi swap?

Check the asset pair, input amount, expected output, price impact, minimum received, and network costs. Make sure you understand that expected output is the current estimate while minimum received is the lower execution boundary. If the quote looks unexpectedly poor, review liquidity and trade size rather than simply increasing the tolerated slippage.

Sources and Further Reading

STON.fi DEX v2 Swap SDK - Official production swap workflow, swap simulation, slippageTolerance, minAskUnits, and Router handling
STON.fi DEX v2 Pool - Official smart contract documentation for min_out and the minimum-output swap condition
STON.fi DEX v2 Router - Official Router swap structure and the min_out field passed during swap execution
STON.fi DEX API Reference - Official API overview covering swap simulation before execution
STON.fi DEX v2 Smart Contracts - Official overview of the current v2 smart contract architecture and swap functionality
STON.fi Blog, All You Need to Know About Price Impact on Decentralized Exchanges - Explanation of price impact, slippage, and their distinction in a STON.fi swap context
TON Documentation, How to Estimate Gas Usage in TON Contracts - Official explanation of TON gas and forward-fee mechanics

How to Build a STON.fi Pool Explorer

Ivan “Crypto Vazima” Zimanov — Sun, 30 Aug 2026 17:33:03 +0000

A practical TypeScript guide to discovering pools, joining token metadata, displaying meaningful metrics, handling multiple AMM types, and verifying pool state on TON.

A STON.fi pool explorer is essentially a read-only DeFi application that turns raw pool contracts and indexed protocol data into something people can understand. At minimum, it should answer a few questions quickly: which assets are in a pool, how much liquidity is there, what fees apply, how active is the pool, which STON.fi contract version powers it, and where can the underlying addresses be verified?

The good news is that you do not need to index TON from scratch. STON.fi exposes a public REST API for pools, assets, routers, statistics, simulations, and other protocol data. You can use that API as the discovery layer, then optionally read the pool contract directly when you want stronger on-chain verification.

This guide builds that architecture step by step.

What a useful STON.fi pool explorer should show

A pool explorer becomes useful when it combines several kinds of information that exist separately at the protocol level.

For each pool, a practical interface should expose:

token names, symbols, images, decimals, and contract addresses
both pool reserves in readable token units
LP fee and other relevant fee information
24-hour trading volume
recent APY values when available
LP token supply and its USD value
pool contract and router addresses
router version and pool type
warnings for deprecated or problematic assets
pool-specific parameters for specialized AMMs

STON.fi's API already exposes much of this data. The main engineering problem is joining it correctly.

A pool response identifies its assets through token0_address and token1_address, while token metadata lives in the asset dataset. The pool also contains router_address, which you can join with the router dataset to identify the contract version and router type.

A simple data flow therefore looks like this:

Load pools from /v1/pools.
Load assets from /v1/assets.
Load routers from /v1/routers.
Index assets and routers by address.
Enrich every pool with token metadata and router information.
Normalize raw blockchain amounts using token decimals.
Render searchable pool cards and detailed pool pages.

That is enough for a surprisingly capable first version.

Model the data around pools, assets, and routers

It is tempting to treat the pool response as a complete object, but keeping the three protocol concepts separate makes the application easier to maintain.

The current STON.fi pool schema includes fields such as:

address
token0_address
token1_address
reserve0
reserve1
lp_fee
protocol_fee
ref_fee
router_address
lp_total_supply
lp_total_supply_usd
volume_24h_usd
apy_1d
apy_7d
apy_30d
deprecated
amp
rate
w0
tags

The asset API provides the presentation layer around those addresses, including display_name, symbol, decimals, image_url, pricing fields, tags, and status flags.

The router endpoint adds another important dimension. Routers expose their major and minor contract versions as well as a router_type. Current router types can include Constant Product, Stable Swap, Weighted Stable Swap, Weighted Constant Product, and Constant Sum variants.

That distinction matters because your explorer should not assume that every pool behaves like a basic x * y = k AMM.

A useful mental model is:

Layer	What your explorer gets from it
Pool	reserves, fees, LP data, volume, APY, pool parameters
Asset	symbol, name, decimals, image, pricing metadata, safety flags
Router	DEX version, router type, contract context
TON contract	direct verification of current on-chain state

Keep these layers separate internally even if the UI eventually merges them into a single pool card.

Fetch and join the STON.fi API data

You can use the official @ston-fi/api TypeScript client, but raw HTTP requests make the underlying explorer architecture especially easy to see.

Start with a small loader:

const STON_API = "https://api.ston.fi";

async function getJson<T>(path: string): Promise<T> {
  const response = await fetch(`${STON_API}${path}`);

  if (!response.ok) {
    throw new Error(
      `STON.fi API returned ${response.status} for ${path}`
    );
  }

  return response.json() as Promise<T>;
}

type Pool = {
  address: string;
  token0_address: string;
  token1_address: string;
  reserve0: string;
  reserve1: string;
  router_address: string;
  lp_fee: string;
  protocol_fee: string;
  ref_fee: string | null;
  lp_total_supply: string;
  lp_total_supply_usd: string | null;
  volume_24h_usd: string | null;
  apy_1d: string | null;
  apy_7d: string | null;
  apy_30d: string | null;
  deprecated: boolean;
  amp: string | null;
  rate: string | null;
  w0: string | null;
  tags: string[];
};

type Asset = {
  contract_address: string;
  display_name: string | null;
  symbol: string;
  decimals: number;
  image_url: string | null;
  deprecated: boolean;
  blacklisted: boolean;
  kind: string;
  tags: string[];
};

type Router = {
  address: string;
  major_version: number;
  minor_version: number;
  router_type: string;
};

Then retrieve the datasets together:

async function loadExplorerData() {
  const [poolData, assetData, routerData] = await Promise.all([
    getJson<{ pool_list: Pool[] }>("/v1/pools?dex_v2=true"),
    getJson<{ asset_list: Asset[] }>("/v1/assets"),
    getJson<{ router_list: Router[] }>("/v1/routers?dex_v2=true"),
  ]);

  const assets = new Map(
    assetData.asset_list.map((asset) => [
      asset.contract_address,
      asset,
    ])
  );

  const routers = new Map(
    routerData.router_list.map((router) => [
      router.address,
      router,
    ])
  );

  return poolData.pool_list.map((pool) => ({
    ...pool,
    asset0: assets.get(pool.token0_address),
    asset1: assets.get(pool.token1_address),
    router: routers.get(pool.router_address),
  }));
}

You now have one object that the frontend can render without repeatedly searching arrays.

For a prototype, loading the complete datasets is convenient. Once your explorer becomes larger, investigate /v1/pools/query, which supports search terms, sorting, limits, and other query conditions. Server-side filtering can reduce unnecessary data transfer.

Turn raw blockchain values into readable metrics

The next problem is units.

STON.fi reserves are returned in basic token units. A jetton with six decimals and a raw reserve of "2500000000" represents 2,500 tokens, not 2.5 billion tokens.

You therefore need the decimals from the asset metadata before displaying reserves.

A BigInt-safe formatter can look like this:

function formatUnits(raw: string, decimals: number): string {
  const value = BigInt(raw);
  const base = 10n ** BigInt(decimals);

  const whole = value / base;
  const fraction = value % base;

  if (fraction === 0n) {
    return whole.toString();
  }

  const fractionString = fraction
    .toString()
    .padStart(decimals, "0")
    .replace(/0+$/, "");

  return `${whole}.${fractionString}`;
}

Then:

const reserve0 = pool.asset0
  ? formatUnits(pool.reserve0, pool.asset0.decimals)
  : pool.reserve0;

const reserve1 = pool.asset1
  ? formatUnits(pool.reserve1, pool.asset1.decimals)
  : pool.reserve1;

Fees deserve similar care. STON.fi pool contract documentation defines fee values against a divider of 10,000. A fee value of 100, for example, corresponds to 1%.

For display:

function formatFee(value: string): string {
  return `${Number(value) / 100}%`;
}

For sorting and presentation, converting USD metrics to JavaScript numbers is usually acceptable:

const volume24h = pool.volume_24h_usd
  ? Number(pool.volume_24h_usd)
  : null;

For financial calculations where precision matters, keep the original integer or decimal strings and use BigInt or a decimal arithmetic library rather than binary floating-point math.

APY should also be labeled carefully. Fields such as apy_1d, apy_7d, and apy_30d describe recent annualized conditions. They are useful historical signals, not promised future returns.

Build the pool list and detail views

With normalized data, the frontend becomes straightforward.

A compact explorer card might contain:

function PoolCard({ pool }: { pool: any }) {
  const token0 = pool.asset0;
  const token1 = pool.asset1;

  return (
    <article>
      <h3>
        {token0?.symbol ?? "Unknown"} /{" "}
        {token1?.symbol ?? "Unknown"}
      </h3>

      <p>
        Type: {pool.router?.router_type ?? "Unknown"}
      </p>

      <p>
        Version:{" "}
        {pool.router
          ? `v${pool.router.major_version}.${pool.router.minor_version}`
          : "Unknown"}
      </p>

      <p>
        24h volume:{" "}
        {pool.volume_24h_usd
          ? `$${Number(pool.volume_24h_usd).toLocaleString()}`
          : "N/A"}
      </p>

      <p>LP fee: {formatFee(pool.lp_fee)}</p>

      <code>{pool.address}</code>
    </article>
  );
}

The list page should optimize for comparison. Pair, liquidity value, 24-hour volume, fee, recent APY, pool type, and version are usually enough.

The detail page can go deeper.

Useful detail fields include:

full pool, router, and token contract addresses
normalized and raw reserves
LP token supply
protocol and referral fee settings
collected protocol fees
amp, rate, or w0 when applicable
pool and asset tags
deprecated status
1-day, 7-day, and 30-day APY
links to a TON blockchain explorer

Always display the underlying token addresses somewhere accessible. TON's token metadata documentation explicitly warns that anyone can create a jetton with a copied name, symbol, description, or image. A professional pool explorer should never identify an asset by ticker alone.

You can also use STON.fi's asset flags, such as deprecated or blacklisted status, to add visible warnings rather than silently treating every returned token as equivalent.

Handle pricing and pool types correctly

One of the easiest mistakes when building an AMM explorer is calculating:

price = reserve1 / reserve0

and calling the result the pool's current execution price.

That shortcut can be informative for a conventional constant product pool after adjusting both reserves for token decimals. It is not a universal pricing formula.

STON.fi supports multiple pool and router types, and the API exposes specialized parameters such as amp, rate, and w0. Those exist because different pool designs do not share one invariant.

A better explorer separates three concepts:

Reserve ratio: a description of the pool's current token composition.
Reference or statistical price: a price derived from indexed market statistics.
Executable quote: the expected result for a particular trade size under the current pool conditions.

If the reader wants to know what a trade would actually return, use STON.fi's swap simulation endpoint rather than extrapolating from reserves. POST /v1/swap/simulate is designed to calculate expected swap output, fees, gas information, and other execution data before a transaction is built.

Trade size matters. A quote for 1 TON and a quote for 10,000 TON can imply different effective prices because the trade itself moves through pool liquidity.

This gives your explorer a useful optional feature: a small "simulate swap" panel on each pool page. It turns a static pool viewer into a tool for understanding liquidity depth without requiring a wallet connection or transaction.

Add on-chain verification and production hardening

The STON.fi REST API is the convenient discovery and analytics layer. The pool contract remains the source of on-chain state.

For DEX v2 pools, the documented get_pool_data getter exposes values including the router address, LP supply, token reserves, token wallet addresses, and liquidity pool fee. A verification mode can query the relevant contract through a TON RPC provider and compare selected values with the indexed API response.

That creates two complementary modes:

Fast mode: use STON.fi API data for discovery, metadata, statistics, search, and normal page rendering.
Verification mode: read selected contract state directly from TON when the reader wants to inspect the underlying pool.

Do not treat a temporary difference as automatic evidence that something is wrong. An indexed API and the latest blockchain state can briefly differ because they are observed at different moments.

Before publishing the explorer, I would also add this checklist:

Cache pool, asset, and router requests instead of refetching everything on every render.
Add graceful handling for missing metadata and nullable USD values.
Search by token symbol, token address, and pool address.
Make contract addresses copyable.
Show deprecated and blacklisted warnings prominently.
Never use token symbols as unique database keys.
Distinguish pool types before calculating derived metrics.
Keep the raw API values available for debugging.
Record when your application last refreshed its data.
Treat API schemas as external dependencies and validate responses at runtime.

The official STON.fi documentation currently states that the DEX API has no usage limits. That is useful for development, but production software should still cache sensible responses and avoid unnecessary traffic because service policies can change.

Practical takeaway: start the explorer with three STON.fi datasets: pools, assets, and routers. Join them by contract address, normalize reserves using token decimals, and render only metrics whose meaning you can explain precisely. Once that works, add simulation for executable pricing and direct TON contract reads for verification. That architecture keeps the first version simple without locking you into an inaccurate data model.

Frequently Asked Questions

Do I need to run a TON node to build a STON.fi pool explorer?

No. A basic explorer can use the public STON.fi REST API for pool discovery, token metadata, router information, volume, APY, and other indexed data. A TON RPC provider becomes useful when you want to verify contract state directly or add deeper blockchain functionality, but it is not required for the first working version.

Which STON.fi endpoint should I start with?

Start with GET /v1/pools, then join its token addresses with GET /v1/assets and its router addresses with GET /v1/routers. This combination gives you the core information needed for a pool directory. You can later use /v1/pools/{address} for individual pages and /v1/pools/query for more selective discovery.

Can I calculate a token's price directly from pool reserves?

Sometimes, but you should not use one reserve-ratio formula for every STON.fi pool. Different AMM types can use different pricing mechanics. A reserve ratio is useful as a pool-composition metric. For an expected trade result, STON.fi's swap simulation endpoint is a safer source because it evaluates a specific amount against the relevant routing and pool logic.

What should I use as the pool's liquidity or TVL figure?

STON.fi pool responses expose LP supply information, including lp_total_supply_usd when available, alongside the underlying reserves. You can use the USD LP supply value as a convenient liquidity-value metric in your interface, while keeping the field's actual meaning clear. If you calculate your own value from reserves and asset prices, document exactly how that calculation works.

Why do I need the router endpoint if I already have the pool?

The router tells you important context about the contract behind the pool, including its major and minor version and router type. That information matters once your explorer supports multiple STON.fi pool designs. It prevents the frontend from assuming that every pool follows the same pricing model or exposes the same specialized parameters.

Should a STON.fi pool explorer trust token names and symbols?

No. Names and symbols are presentation metadata, not unique identities. TON documentation warns that jettons can copy another token's name, symbol, or image. Display contract addresses and use STON.fi metadata flags where appropriate. Internally, index tokens by their contract addresses rather than by symbols such as USDT, TON, or STON.

How can I verify that the STON.fi API reserves match the blockchain?

Read the pool contract's documented get_pool_data getter through a TON provider and compare its reserves and other relevant state with the indexed API values. Small temporary differences can occur because indexing and direct blockchain reads happen at different times. For an explorer, API-first rendering plus optional on-chain verification is usually a practical architecture.

Sources and Further Reading

STON.fi DEX API Reference - official list of pool, asset, router, statistics, simulation, wallet, and market endpoints
STON.fi REST API documentation - overview of the public DEX data API and integration options
STON.fi Swagger UI - current REST API schemas, including PoolInfoSchema, AssetInfoSchema, RouterInfoSchema, query parameters, and supported router types
STON.fi API TypeScript client - official @ston-fi/api client with methods for retrieving pools, assets, routers, wallet positions, and other protocol data
STON.fi DEX Architecture - official explanation of routers, pools, LP contracts, liquidity flows, and the protocol contract model
STON.fi Pool v2 smart contract reference - documents get_pool_data, reserves, LP supply, fee fields, router address, and other on-chain pool state
STON.fi v1 to v2 SDK migration guide - explains typed pool support and architectural differences developers should account for across STON.fi versions
TON Token Metadata - official guidance on jetton metadata fields and why applications should distinguish tokens by contract address rather than names or symbols
TON Run Get Method API - official TON API documentation for executing read-only smart contract getter methods when adding direct on-chain verification

How to Query STON.fi Token and Asset Metadata

Ivan “Crypto Vazima” Zimanov — Mon, 24 Aug 2026 06:04:19 +0000

How to fetch token names, symbols, decimals, images, prices, tags, and contract addresses with the STON.fi REST API and TypeScript client.

If you are building a token selector, portfolio view, swap interface, analytics dashboard, or any other TON application, you rarely want to decode every jetton's metadata yourself. STON.fi provides an HTTP API that exposes normalized asset information and a TypeScript client that makes those endpoints easier to use.

For most applications, the workflow is simple: query STON.fi for an asset list, identify every asset by its contract address, read the metadata you need for display, and keep transaction-critical logic separate from labels such as token names and symbols. The API currently provides endpoints for listing assets, fetching one asset by address, and querying assets with search and filtering conditions.

What does STON.fi mean by an asset?

On TON, fungible tokens normally use the jetton standard. Their metadata can include a name, symbol, decimals, image, and other fields. TEP-64 allows metadata to be stored on-chain, off-chain, or through a semi-chain combination where some values come from the contract and others come from an external document.

STON.fi gives developers a more convenient application-level view of assets used around the DEX. Instead of decoding cells and resolving metadata yourself for every token, you can query the STON.fi API.

Depending on the endpoint, an asset can contain information such as:

contract address
asset kind
token name and symbol
decimals
image URL
STON.fi DEX price in USD
tags
popularity information
wallet balance when a wallet-aware endpoint is used
optional extensions and scaling information

The API currently distinguishes asset kinds such as Ton, Wton, Jetton, and NotAnAsset. Its newer asset schema groups display metadata under a meta object, while the older asset response exposes fields such as symbol, display_name, decimals, and image_url directly.

That schema difference is worth noticing because code written for getAsset() and code written for queryAssets() may access metadata differently.

Pick the query that matches your UI

STON.fi provides several related asset endpoints, but they answer different questions.

What you need	REST endpoint	TypeScript client
Every available DEX asset	`GET /v1/assets`	`getAssets()`
One known asset	`GET /v1/assets/{address}`	`getAsset(address)`
Search and filter assets	`POST /v1/assets/query`	`queryAssets(...)`
Assets held by a wallet	`GET /v1/wallets/{address}/assets`	`getWalletAssets(address)`
One wallet asset and its balance	`GET /v1/wallets/{address}/assets/{asset}`	`getWalletAsset(...)`

For a production token selector, queryAssets() is usually more useful than downloading every known asset. It lets you search by text or address and combine the search with STON.fi asset conditions.

If you already know the contract address, however, fetching that specific asset is simpler and removes the ambiguity that comes with searching by a ticker.

Query one token directly by address

The most deterministic asset lookup starts with the contract address.

Using the REST API:

async function getStonAsset(address: string) {
  const response = await fetch(
    `https://api.ston.fi/v1/assets/${encodeURIComponent(address)}`
  );

  if (!response.ok) {
    throw new Error(`STON.fi API returned ${response.status}`);
  }

  const data = await response.json();
  return data.asset;
}

The official API base URL is:

https://api.ston.fi

The equivalent operation with the official TypeScript package is shorter:

npm install @ston-fi/api

import { StonApiClient } from "@ston-fi/api";

const client = new StonApiClient();

const asset = await client.getAsset("EQ...");

console.log(asset);

StonApiClient uses https://api.ston.fi by default, so no API configuration is required for a basic request. The current client source maps getAsset() directly to GET /v1/assets/{assetAddress}.

This pattern is ideal when an address comes from a trusted configuration, a pool response, a swap quote, or another part of your application where the asset has already been identified.

Search for tokens without downloading the whole list

A token picker has a different problem. The visitor may type USD, STON, or part of a token name, so you need discovery rather than an exact lookup.

STON.fi provides POST /v1/assets/query for this.

A direct REST request can look like this:

async function searchAssets(search: string) {
  const response = await fetch(
    "https://api.ston.fi/v1/assets/query",
    {
      method: "POST",
      headers: {
        "content-type": "application/json",
      },
      body: JSON.stringify({
        search_terms: [search],
        condition:
          "asset:liquidity:very_high | asset:liquidity:high",
        limit: 20,
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`Asset query failed: ${response.status}`);
  }

  const data = await response.json();
  return data.asset_list;
}

The request schema supports search terms containing addresses or text such as token names and symbols. It also supports a condition, sorting parameters, a result limit, unconditional assets, and an optional wallet address.

With @ston-fi/api, the same query becomes easier to read:

import {
  StonApiClient,
  AssetTag,
} from "@ston-fi/api";

const client = new StonApiClient();

const assets = await client.queryAssets({
  searchTerms: ["USD"],
  condition: [
    AssetTag.LiquidityVeryHigh,
    AssetTag.LiquidityHigh,
  ].join(" | "),
  limit: 20,
});

console.log(assets);

STON.fi's own quickstart uses the same approach to populate token selectors, combining LiquidityVeryHigh, LiquidityHigh, and LiquidityMedium tags and then storing the returned AssetInfoV2 objects in application state.

The older searchAssets() client method still exists, but the current source marks it as deprecated and redirects it through queryAssets(). New integrations should therefore use queryAssets() directly.

Turn the response into clean application data

A raw API object usually contains more information than a component needs. Normalizing it once makes the rest of your frontend much easier to maintain.

The newer query response exposes display metadata under meta.

import type { AssetInfoV2 } from "@ston-fi/api";

type TokenOption = {
  address: string;
  name: string;
  symbol: string;
  decimals?: number;
  imageUrl?: string;
  priceUsd?: string;
  tags: string[];
};

function toTokenOption(asset: AssetInfoV2): TokenOption {
  return {
    address: asset.contractAddress,
    name: asset.meta?.displayName ?? "Unknown token",
    symbol: asset.meta?.symbol ?? "TOKEN",
    decimals: asset.meta?.decimals,
    imageUrl: asset.meta?.imageUrl,
    priceUsd: asset.dexPriceUsd,
    tags: asset.tags ?? [],
  };
}

Then your UI can work with a small predictable model:

const options = assets.map(toTokenOption);

The official AssetInfoV2 structure includes the contract address, asset kind, optional balance, DEX price, meta, popularity information, tags, wallet address, scale, and extensions. Inside meta, fields such as decimals, symbol, display name, image URL, and custom payload API URI are optional.

That optionality matters. A robust token selector should not assume that every asset has a complete name, icon, or even every display field.

A reasonable display fallback is:

Show displayName when available.
Fall back to symbol.
Keep the contract address available as the definitive identifier.
Use a local placeholder when no usable image exists.

Decimals are metadata that affect real amounts

A missing icon is mostly a visual problem. Incorrect decimals are different because decimals determine how integer token units become human-readable balances.

Suppose an API returns:

{
  meta: {
    symbol: "EXAMPLE",
    decimals: 6
  }
}

An on-chain amount of:

represents:

1.25 EXAMPLE

not 1,250,000 tokens.

Avoid normal JavaScript floating-point arithmetic when converting transaction amounts. A simple display helper can use BigInt:

function formatUnits(value: string, decimals: number) {
  const units = BigInt(value);
  const base = 10n ** BigInt(decimals);

  const whole = units / base;
  const fraction = (units % base)
    .toString()
    .padStart(decimals, "0")
    .replace(/0+$/, "");

  return fraction
    ? `${whole}.${fraction}`
    : whole.toString();
}

TON's token metadata standard defines decimals as a jetton metadata attribute and specifies 9 as the default when the field is absent. Still, if your application receives incomplete or unexpected STON.fi metadata, treating that object carefully is safer than blindly assuming every response represents a normal jetton.

Use tags to improve token discovery

STON.fi does more than return names and icons. Its TypeScript client currently exposes a range of asset tags that can help shape search results and token lists.

Examples include:

AssetTag.Essential
AssetTag.Popular
AssetTag.LiquidityVeryHigh
AssetTag.LiquidityHigh
AssetTag.LiquidityMedium
AssetTag.WalletHasBalance
AssetTag.Deprecated
AssetTag.Blacklisted
AssetTag.Suspicious
AssetTag.Fake
AssetTag.Honeypot
AssetTag.NonSearchable

The exact tag set can evolve, so import the constants from the package instead of copying string values throughout your application. The current client source also includes tags for scaled assets, taxable assets, DMCA complaints, wallet liquidity, and several liquidity levels.

A wallet-aware selector can combine discovery with the connected wallet:

const walletAssets = await client.queryAssets({
  condition: [
    AssetTag.Essential,
    AssetTag.Popular,
    AssetTag.WalletHasBalance,
  ].join(" | "),
  walletAddress,
});

That gives you a useful foundation for sections such as "Your tokens" or "Popular assets" without maintaining a separate token registry in your frontend.

Tags should still be treated as API classification data, not as cryptographic proof that an asset is safe.

Never identify a token by its symbol alone

Imagine your application searches for USD and receives several assets. Choosing the first item because its ticker looks familiar is a dangerous shortcut.

TON's own token metadata documentation explicitly warns that anyone can create a jetton using any name, description, or image. Applications should distinguish tokens by their addresses rather than relying on names or tickers.

For a production STON.fi integration, keep these rules simple:

Use contractAddress as the asset identifier.
Treat symbol and display name as presentation metadata.
Preserve the selected address when requesting quotes or constructing transactions.
Do not infer authenticity from an icon.
Consider STON.fi tags when deciding which assets should appear prominently.
Give users a way to inspect or verify the contract address for unfamiliar assets.

This becomes especially important for symbols such as USDT, USD, TON, or any popular project ticker that someone could imitate.

The interface may display:

Example USD
USD
$1.00

but the application state should fundamentally remember:

{
  contractAddress: "EQ..."
}

The address is what connects the display object to the actual TON asset.

A practical STON.fi token selector

Putting the pieces together, a small React application might query STON.fi as the user types instead of loading the entire asset catalog.

import {
  AssetTag,
  StonApiClient,
  type AssetInfoV2,
} from "@ston-fi/api";

const stonApi = new StonApiClient();

export async function findTokens(
  searchTerm: string
): Promise<AssetInfoV2[]> {
  const searchTerms = searchTerm.trim()
    ? [searchTerm.trim()]
    : undefined;

  return stonApi.queryAssets({
    searchTerms,
    condition: [
      AssetTag.LiquidityVeryHigh,
      AssetTag.LiquidityHigh,
      AssetTag.LiquidityMedium,
    ].join(" | "),
    limit: 30,
  });
}

Your component can then render the fields STON.fi already normalized:

{assets.map((asset) => (
  <button
    key={asset.contractAddress}
    onClick={() => setSelectedAsset(asset)}
  >
    {asset.meta?.imageUrl && (
      <img
        src={asset.meta.imageUrl}
        alt=""
        width={32}
        height={32}
      />
    )}

    <strong>
      {asset.meta?.symbol ?? "Unknown"}
    </strong>

    <span>
      {asset.meta?.displayName ?? asset.contractAddress}
    </span>
  </button>
))}

For a real product, add loading states, request cancellation or debouncing for live search, image fallbacks, error handling, and caching. Metadata images and other external resources should also be treated as untrusted input. If your backend fetches arbitrary remote resources, apply normal URL validation and server-side request protections.

STON.fi's own Omniston quickstart follows the same core architecture: fetch assets through StonApiClient, keep AssetInfoV2 objects in state, display meta.symbol or meta.displayName, and pass the selected contract addresses into later swap operations.

Practical takeaway: use getAsset() when the contract address is already known and queryAssets() when you are building discovery or search. Keep the contract address as your canonical identifier, normalize optional metadata before it reaches your UI, and use STON.fi's tags to make large token lists easier to navigate.

Frequently Asked Questions

Can I query STON.fi token metadata without installing an SDK?

Yes. The REST API is available at https://api.ston.fi, so any environment capable of making HTTP requests can use it. GET /v1/assets/{address} retrieves a specific asset, while POST /v1/assets/query supports filtered discovery. The @ston-fi/api package is mainly a convenience layer for TypeScript and JavaScript applications.

What metadata does STON.fi return for a token?

Depending on the endpoint and schema, you can receive a contract address, kind, symbol, display name, decimals, image URL, prices, tags, popularity information, optional extensions, and wallet-related fields. Query responses use the newer model where core display metadata is grouped under meta, and those metadata fields can be optional.

Should I use `getAssets()` or `queryAssets()`?

Use getAssets() when you genuinely need the complete DEX asset collection. Use queryAssets() for most interactive interfaces because it supports search terms, conditions, wallet-aware queries, sorting, and limits. A search box usually does not need the full asset catalog before the user has typed anything.

Can two TON tokens have the same symbol?

Yes. Names and symbols are metadata, and token creators can choose them. A familiar ticker therefore does not uniquely identify a jetton. TON documentation recommends distinguishing tokens by address. Your frontend can display the symbol prominently, but your application logic should retain and use the contract address.

What should I do if `meta.imageUrl` or `meta.displayName` is missing?

Use a fallback. Display the symbol or a shortened address when a name is unavailable, and use a local placeholder image when no valid icon exists. Do not make rendering a token dependent on optional cosmetic metadata. AssetInfoV2 deliberately represents several metadata properties as optional.

Does STON.fi provide token prices together with metadata?

The asset schemas include optional STON.fi DEX price information such as dex_price_usd, exposed in camelCase by the TypeScript client. Treat price data separately from identity metadata because a price can be absent or change frequently, while the contract address is the persistent identifier used by your application.

Can I use STON.fi metadata to build a wallet token list?

Yes. STON.fi exposes wallet-specific asset endpoints, and queryAssets() can also accept a wallet address together with conditions such as AssetTag.WalletHasBalance. That makes it possible to combine searchable DEX assets with wallet-aware token selection without maintaining a completely separate metadata database.

What is the safest way to query a STON.fi asset before using it in a swap?

Start from the exact contract address whenever possible. Retrieve the asset, display its metadata for readability, but keep the address as the selected value passed into your swap logic. For search-based selection, show enough identifying information for the user to distinguish similar tokens and avoid treating a matching name, ticker, or image as proof of identity.

Sources and Further Reading

STON.fi DEX API Reference - Official overview of asset, pool, wallet, swap, and other REST endpoints
STON.fi REST API - Official introduction to the STON.fi HTTP API and TypeScript client
STON.fi Swagger UI - Current interactive REST API schemas, asset endpoints, request parameters, and response models
STON.fi API GitHub repository - Official source and usage examples for the @ston-fi/api TypeScript client
STON.fi asset types - Official AssetInfo, AssetInfoV2, AssetKind, and AssetTag definitions
STON.fi Omniston Quickstart - Official React example showing how StonApiClient and queryAssets() populate token selectors
TON Token Metadata Documentation - Official explanation of on-chain, off-chain, and semi-chain token metadata and token identity considerations
TEP-64 Token Data Standard - TON specification defining token metadata layouts and jetton metadata fields

How to Display STON.fi Pool Data in a Web App

Ivan “Crypto Vazima” Zimanov — Fri, 21 Aug 2026 10:52:22 +0000

Build a small React and TypeScript dashboard that fetches STON.fi liquidity pools, resolves token metadata, formats reserves, and presents useful market data.

Displaying STON.fi pool data in a web app does not require reading TON smart contracts directly. For most dashboards, analytics pages, token explorers, and liquidity interfaces, the simplest route is the official STON.fi REST API or its TypeScript client, @ston-fi/api.

The API already organizes contract data into application-friendly structures. You can request pools, retrieve asset metadata, find pools for a specific token pair, and expose fields such as reserves, USD liquidity values, and 24-hour volume.

In this guide, we will build a small React interface that turns those responses into readable pool cards without adding wallet connections or transaction logic.

What we will build:

fetch the current STON.fi pool list
resolve token addresses into symbols
format reserves using each token's decimals
display liquidity and 24-hour volume
handle loading, errors, and stale data
keep the data layer ready for filtering or a larger dashboard

Why use the STON.fi API instead of reading contracts directly?

A liquidity pool ultimately lives on-chain. STON.fi pool contracts contain reserves and other state, and the protocol documentation exposes contract getters such as get_pool_data. The V2 pool getter, for example, includes the LP token supply, both reserves, token wallet addresses, and fee-related fields.

You could query those contracts yourself. For a web interface whose job is simply to show pool information, however, that creates work you often do not need.

STON.fi provides a REST API specifically to organize protocol data for applications. Its current pool endpoints include:

GET  /v1/pools
GET  /v1/pools/{address}
GET  /v1/pools/by_market/{asset0}/{asset1}
POST /v1/pools/query

The base URL is:

https://api.ston.fi

The official TypeScript package wraps these endpoints with methods such as getPools(), getPool(), getPoolsByAssetPair(), and queryPools(). The current client also normalizes API response keys from snake_case to camelCase, which is convenient in a TypeScript frontend.

For a read-only pool dashboard, that is the layer we want.

Which pool fields are actually useful in a UI?

The pool response contains considerably more information than most users need to see. The current STON.fi schema includes fields for the pool address, token addresses, reserves, LP supply, protocol fees, LP price, USD LP supply, recent APY values, 24-hour USD volume, router address, and parameters used by different pool types.

A compact market interface can start with just a few fields:

API value	What it gives your UI
`token0Address` and `token1Address`	Identifies the pool pair
`reserve0` and `reserve1`	Current token reserves in base units
`lpTotalSupplyUsd`	USD value associated with total LP supply
`volume24hUsd`	Trading volume during the last 24 hours
`address`	Pool contract address
`deprecated`	Helps avoid presenting deprecated pools as normal active choices

There are two important display details here.

First, token addresses are not good labels. A visitor wants to see something like TON / USDT, not two long TON addresses. We therefore need the asset list as well as the pool list.

Second, reserves are raw blockchain quantities. Token metadata defines the number of decimals that must be applied to convert a base-unit balance into a human-readable amount. TON documentation explicitly warns applications to respect token decimals rather than assuming every asset uses the same value.

Set up the React project

A basic React and TypeScript application is enough for the example.

npm create vite@latest stonfi-pools -- --template react-ts
cd stonfi-pools
npm install
npm install @ston-fi/api
npm run dev

For this dashboard, we do not need @ston-fi/sdk.

That distinction is useful. @ston-fi/api is the HTTP API client and is appropriate for retrieving application data. @ston-fi/sdk is aimed at interaction with STON.fi DEX contracts, including swaps and liquidity operations.

Create a small API module:

// src/stonfi.ts
import { StonApiClient } from "@ston-fi/api";

export const stonApi = new StonApiClient();

The client requires no special configuration for the standard API endpoint. The package uses https://api.ston.fi as its default base URL.

Fetch pools and token metadata together

Calling getPools() gives us the pool data, while getAssets() gives us the metadata required to turn token addresses into recognizable names and symbols.

Fetching both in parallel keeps the first render simple:

import { useEffect, useState } from "react";
import { stonApi } from "./stonfi";

type Pool = Awaited<
  ReturnType<typeof stonApi.getPools>
>[number];

type Asset = Awaited<
  ReturnType<typeof stonApi.getAssets>
>[number];

export default function App() {
  const [pools, setPools] = useState<Pool[]>([]);
  const [assets, setAssets] = useState<Asset[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    let ignore = false;

    async function loadData() {
      try {
        setLoading(true);
        setError(null);

        const [poolList, assetList] = await Promise.all([
          stonApi.getPools(),
          stonApi.getAssets(),
        ]);

        if (ignore) return;

        setPools(poolList);
        setAssets(assetList);
      } catch (err) {
        if (!ignore) {
          setError(
            err instanceof Error
              ? err.message
              : "Unable to load STON.fi data"
          );
        }
      } finally {
        if (!ignore) {
          setLoading(false);
        }
      }
    }

    loadData();

    return () => {
      ignore = true;
    };
  }, []);

  if (loading) return <p>Loading STON.fi pools...</p>;
  if (error) return <p>Error: {error}</p>;

  return <p>Loaded {pools.length} pools.</p>;
}

React documents useEffect as one way to synchronize a component with an external system, including manual data fetching. It also recommends cleanup logic so a response does not update a component after the relevant effect has been discarded.

For a production Next.js, Remix, or similar application, you may prefer the framework's server-side data fetching or a caching library. The STON.fi-specific part does not change.

Turn contract addresses into readable pool pairs

The asset response includes fields such as the contract address, symbol, display name, decimals, and price information. The STON.fi client converts the raw API keys into camelCase before returning them.

Build a lookup map once:

import { useMemo } from "react";

// inside App

const assetByAddress = useMemo(() => {
  return new Map(
    assets.map((asset) => [asset.contractAddress, asset])
  );
}, [assets]);

Now each pool's token addresses can be resolved efficiently:

function getSymbol(
  address: string,
  assetByAddress: Map<string, Asset>
) {
  return assetByAddress.get(address)?.symbol ?? "Unknown";
}

The same metadata lets us convert reserves into display values.

function formatUnits(value: string, decimals: number) {
  if (decimals === 0) return value;

  const padded = value.padStart(decimals + 1, "0");
  const whole = padded.slice(0, -decimals);

  const fraction = padded
    .slice(-decimals)
    .replace(/0+$/, "")
    .slice(0, 4);

  return fraction ? `${whole}.${fraction}` : whole;
}

Do not silently assume nine decimals when metadata is unavailable. Nine is common on TON, but tokens can use another value. USDT, for example, uses six decimals.

For unknown assets, showing the raw amount or an explicit unavailable state is safer than presenting a confidently formatted but incorrect number.

Render the pool data

We can now turn the two API responses into a small dashboard.

Add a USD formatter:

const usd = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  maximumFractionDigits: 0,
});

function formatUsd(value?: string) {
  if (!value) return "N/A";

  const number = Number(value);

  return Number.isFinite(number)
    ? usd.format(number)
    : "N/A";
}

Then render the pools:

return (
  <main>
    <h1>STON.fi Pools</h1>

    <div className="pool-grid">
      {pools
        .filter((pool) => !pool.deprecated)
        .sort(
          (a, b) =>
            Number(b.lpTotalSupplyUsd ?? 0) -
            Number(a.lpTotalSupplyUsd ?? 0)
        )
        .slice(0, 20)
        .map((pool) => {
          const token0 = assetByAddress.get(pool.token0Address);
          const token1 = assetByAddress.get(pool.token1Address);

          const reserve0 = token0
            ? formatUnits(pool.reserve0, token0.decimals)
            : `${pool.reserve0} base units`;

          const reserve1 = token1
            ? formatUnits(pool.reserve1, token1.decimals)
            : `${pool.reserve1} base units`;

          return (
            <article className="pool-card" key={pool.address}>
              <h2>
                {token0?.symbol ?? "Unknown"} /{" "}
                {token1?.symbol ?? "Unknown"}
              </h2>

              <p>
                <strong>Liquidity:</strong>{" "}
                {formatUsd(pool.lpTotalSupplyUsd)}
              </p>

              <p>
                <strong>24h volume:</strong>{" "}
                {formatUsd(pool.volume24hUsd)}
              </p>

              <p>
                <strong>Reserve 0:</strong>{" "}
                {reserve0} {token0?.symbol ?? ""}
              </p>

              <p>
                <strong>Reserve 1:</strong>{" "}
                {reserve1} {token1?.symbol ?? ""}
              </p>

              <small>
                Pool: {pool.address.slice(0, 10)}...
                {pool.address.slice(-6)}
              </small>
            </article>
          );
        })}
    </div>
  </main>
);

At this point the app has moved from protocol-oriented data to UI-oriented data:

STON.fi API
    |
    +-- pools
    |    +-- reserves
    |    +-- liquidity value
    |    +-- volume
    |    +-- pool address
    |
    +-- assets
         +-- symbols
         +-- names
         +-- decimals
              |
              v
       React view model
              |
              v
       readable pool cards

That transformation layer is worth keeping separate from the markup. It becomes much easier to add search, sorting, charts, or token filters later.

Fetch less data when the page becomes more specific

getPools() is a good starting point because it lets you explore the dataset. It should not automatically become the request used by every future screen.

If a page is about one pool, request one pool:

const pool = await stonApi.getPool(poolAddress);

If the user has selected two assets, request pools for that pair:

const pools = await stonApi.getPoolsByAssetPair({
  asset0Address,
  asset1Address,
});

For more advanced discovery, STON.fi also exposes queryPools(). The current client supports search terms, conditions, sorting, limits, wallet-specific context, and a DEX V2 option.

That gives you a useful progression:

Use getPools() while building a general explorer.
Move to pair-specific requests when the visitor selects assets.
Use getPool() on detail pages.
Use queryPools() when your interface needs server-side filtering or ranking.

The UI stays the same. Only the retrieval strategy becomes more precise.

Treat pool data as live application data

A working first render is not the end of the integration. Pool reserves and trading volume change as swaps and liquidity operations occur.

Before shipping, decide how fresh the interface actually needs to be.

For a pool directory, refreshing every few minutes may be enough. A trading interface may need a different data path and much fresher quoting logic. Do not confuse a periodically refreshed pool dashboard with an executable swap quote.

A practical production checklist:

cache responses instead of requesting the complete pool list on every render
show a loading state during the initial request
preserve a clear error state when the API is unavailable
display when the data was last refreshed
remove or visually mark deprecated pools
never use rounded UI numbers as transaction inputs
keep original string values for financial calculations

The STON.fi documentation currently states that the DEX API has no rate limits, but that should not be treated as a reason to make wasteful requests. API behavior and operational limits can change, and caching makes the application faster regardless.

Also remember that the STON.fi REST API is intended for mainnet data. If your development workflow depends on testnet contract state, do not assume the same REST endpoint is a testnet indexer.

Common mistakes when displaying STON.fi pools

Showing raw addresses as the main identity. Addresses are essential identifiers, but they make poor primary labels. Resolve them through the asset metadata response and use addresses as secondary verification information.

Formatting every reserve with nine decimals. Token decimals belong to the token metadata. A wrong decimal assumption can produce a dramatically wrong displayed amount.

Calling getPools() after every state update. Pool data is external network data. Fetch it intentionally, cache it where appropriate, and separate filters that can run locally from filters that genuinely require another API request.

Treating lpTotalSupplyUsd as a universal definition of TVL without explanation. The API schema describes this field as the USD value of total LP token supply. If your product labels a metric "TVL," document exactly how your application defines it.

Mixing analytics values with transaction calculations. A rounded reserve or USD number that looks good in a card is not a substitute for a swap simulation or exact base-unit value.

For a useful first STON.fi integration, keep the exercise narrow: load pools, resolve their assets, inspect the exact API values in your browser, and compare the displayed reserves with the token decimals before adding more features. Once that layer is reliable, search, sorting, charts, pool detail pages, and wallet-specific liquidity views become incremental improvements rather than a rewrite.

Frequently Asked Questions

Can I display STON.fi pool data without connecting a wallet?

Yes. Public pool and asset information can be retrieved through the STON.fi REST API without asking the visitor to connect a wallet. A wallet becomes relevant when you want wallet-specific positions or when the application starts constructing transactions. A read-only pool explorer can remain completely independent of TonConnect.

Do I need `@ston-fi/sdk` to fetch liquidity pools?

No. For the workflow in this article, @ston-fi/api is the relevant package. It provides methods such as getPools(), getPool(), getAssets(), and getPoolsByAssetPair(). The separate DEX SDK is intended for interaction with protocol contracts and becomes useful when your application moves beyond displaying data.

What does `GET /v1/pools` return?

The endpoint returns the STON.fi pool collection. Pool records contain identifiers and state including pool and router addresses, token addresses, reserves, LP-related values, fee fields, recent APY fields, and 24-hour USD volume where available. The exact live schema should always be checked in the official Swagger interface.

How should I display token reserves correctly?

Retrieve the corresponding asset metadata and use its decimals value to convert the base-unit reserve into a human-readable amount. Do not assume that all tokens use the same number of decimals. Keep the original string or integer representation for calculations and perform formatting only at the presentation boundary.

Should I refresh pool data every second?

Usually not for a general pool dashboard. Choose a refresh interval that matches the purpose of the page, cache shared data, and avoid repeated full-list requests. A fast-changing execution interface should use purpose-built quote or simulation data rather than assuming that a periodically fetched pool card represents an executable price.

Can I request only pools for one token pair?

Yes. STON.fi exposes GET /v1/pools/by_market/{asset0}/{asset1}, and the TypeScript client wraps it with getPoolsByAssetPair(). That is preferable to loading every pool and filtering in the browser when the application already knows the two selected assets.

Can I show a user's STON.fi liquidity positions with the same API?

Yes. The REST API includes wallet-specific pool endpoints, and @ston-fi/api exposes getWalletPools() and getWalletPool(). That is a different UI state from the public pool directory because the response is enriched with information relevant to the specified wallet.

What should I verify before publishing a STON.fi pool dashboard?

Compare your field names against the current Swagger schema, verify token decimals, confirm that deprecated pools are handled correctly, and test missing optional values such as USD metrics. Also inspect the actual API response rather than copying an old example, since the STON.fi API and TypeScript client continue to evolve.

Sources and Further Reading

STON.fi REST API - Official overview of the REST interface, API viewers, and current usage notes
STON.fi API Reference - Official list of pool, asset, wallet, statistics, and other DEX endpoints
STON.fi Swagger UI - Current interactive REST API schema and response definitions
STON.fi API TypeScript client - Official source repository for @ston-fi/api, including pool and asset client methods
@ston-fi/api on npm - Package installation and TypeScript client usage examples
STON.fi V2 Pool contract reference - On-chain pool state and get_pool_data fields behind pool information
TON token metadata - Official explanation of token metadata and decimal handling for human-readable amounts
React useEffect reference - Official React guidance for synchronizing components with external systems and manual data fetching

How to Track STON.fi Swap Status with an Indexer

Ivan “Crypto Vazima” Zimanov — Tue, 18 Aug 2026 06:42:55 +0000

How to turn TON transaction data into a reliable pending, processing, completed, or failed state for a STON.fi swap.

When a user signs a STON.fi swap, your application still has an important job to do: determine what actually happened on-chain.

On TON, that is not always as simple as waiting for one transaction hash. A swap can involve several contracts and internal messages, so the wallet transaction that starts the operation is only the beginning of the execution path. A blockchain indexer lets you locate that transaction, follow its trace, inspect the resulting actions, and turn low-level blockchain data into a useful swap status.

For a production integration, the safest approach is to separate two questions: Has the TON trace finished? and Did the STON.fi swap itself succeed?

Why one transaction hash is not enough

Developers coming from EVM networks often expect a swap to map neatly to one transaction. TON works differently.

A transaction on TON records a state change for one account. If that account sends internal messages to other contracts, those messages can trigger additional transactions. The related messages and transactions form a trace. Because TON uses asynchronous message processing, different parts of that trace may execute across different blocks.

A simplified STON.fi swap can therefore look conceptually like this:

Your wallet sends the initiating message.
The wallet transaction sends an internal message toward the swap contracts.
Router and pool contracts process the request.
Jetton wallets may process token transfers.
The output asset reaches the destination wallet.
Excess TON or other follow-up messages may also be processed.

The exact path depends on the swap and protocol version, but the monitoring lesson stays the same: finding the first transaction does not prove that the entire swap has completed successfully.

TON defines traces specifically to connect these causally related transactions and messages. An indexer makes those traces much easier to query than reconstructing them manually from raw node data.

What an indexer adds to swap tracking

An indexer continuously reads blockchain data, parses transactions and messages, and stores structured results in a query-friendly database.

TON Center API v3 is one example. TON documentation describes it as an indexed access layer that supports historical transactions, traces, decoded Jetton data, and higher-level actions. Its mainnet endpoint is https://toncenter.com/api/v3.

For a STON.fi integration, that gives you several useful capabilities:

find the transaction associated with the message sent by the wallet
retrieve the full trace related to that transaction
see whether the trace is still incomplete
inspect pending messages
request classified actions when available
recover historical status after a page reload or backend restart

This is much more useful than repeatedly asking whether a single account has a new transaction.

A good architecture treats the indexer as an observation layer. Your application stores the swap identifiers, queries indexed blockchain state, and then maps the returned data into a much smaller set of statuses that make sense to the person waiting for the swap.

Build a status model for your application

Do not expose every low-level TON state directly to the UI. Define your own swap lifecycle instead.

Application status	What you know	Typical evidence
Submitted	Wallet accepted the request	TON Connect returned the outgoing message BoC
Locating	Message was sent, but the indexed transaction is not available yet	No matching indexed transaction yet
Processing	Initial transaction exists and the trace is still progressing	Trace is incomplete or still has pending messages
Verifying	Trace is complete, but the protocol outcome still needs interpretation	Complete trace and available actions
Succeeded	Swap completed with the expected protocol result	Successful STON.fi swap status or validated swap action
Failed	Execution completed without a successful swap result	Failed or aborted protocol action, refund path, or other terminal failure

The key distinction is between trace completion and swap success.

An indexer can tell you that the chain of messages has stopped progressing. It does not automatically mean your application's intended business operation succeeded. For a STON.fi swap, you should also interpret STON.fi-specific data rather than relying only on a generic transaction success flag.

Start with the message returned by TON Connect

After a user signs through TON Connect, sendTransaction() returns a serialized external message as a BoC.

That BoC is a useful tracking anchor, but TON recommends using the normalized hash of the external message for message lookup. Normalization exists because equivalent external messages can otherwise have different hashes depending on serialization details. TON documents the normalization rules in its TON Connect message lookup guide and notes that normalized message lookup is supported by many providers.

A shortened TypeScript version follows the same approach:

import {
  beginCell,
  Cell,
  loadMessage,
  storeMessage,
} from "@ton/core";

function getNormalizedHash(boc: string): string {
  const message = loadMessage(
    Cell.fromBase64(boc).beginParse()
  );

  if (message.info.type !== "external-in") {
    throw new Error("Expected an external-in message");
  }

  const normalized = {
    ...message,
    init: null,
    info: {
      ...message.info,
      src: undefined,
      importFee: 0n,
    },
  };

  return beginCell()
    .store(storeMessage(normalized, { forceRef: true }))
    .endCell()
    .hash()
    .toString("hex");
}

Save this tracking identifier with the swap record in your backend.

Do not depend on React component state alone. If the user closes the tab immediately after signing, you still want to be able to reconstruct the operation later.

Your stored swap record might contain:

wallet address
normalized external message hash
STON.fi router used for the swap
input and output assets
expected output or minimum output
STON.fi query ID when available
creation time
your current application status

Those fields give you enough context to recover after temporary API failures or user disconnects.

Follow the transaction into its trace

Once you know the transaction hash, TON Center API v3 can retrieve a trace with GET /traces.

The endpoint supports filters including trace_id, tx_hash, and msg_hash. You can also request classified actions with include_actions=true. The returned trace data includes fields such as is_incomplete, transaction information, actions, and trace metadata.

A simple backend request can look like this:

async function getTrace(txHash: string) {
  const url = new URL(
    "https://toncenter.com/api/v3/traces"
  );

  url.searchParams.append("tx_hash", txHash);
  url.searchParams.set("include_actions", "true");

  const response = await fetch(url, {
    headers: {
      "X-API-Key": process.env.TONCENTER_API_KEY!,
    },
  });

  if (!response.ok) {
    throw new Error(
      `Indexer returned ${response.status}`
    );
  }

  return response.json();
}

Keep API keys on the server. TON Center accepts API keys through the X-API-Key header, and its documentation explicitly recommends not exposing them in client-side applications or public repositories.

Your first status function can remain deliberately simple:

function getTraceState(data: any) {
  const trace = data.traces?.[0];

  if (!trace) {
    return "locating";
  }

  if (
    trace.is_incomplete ||
    (trace.trace_info?.pending_messages ?? 0) > 0
  ) {
    return "processing";
  }

  return "verifying";
}

Notice that the final state is verifying, not succeeded.

That extra step prevents one of the most common monitoring mistakes: treating a completed trace as proof that the desired swap completed.

Verify the STON.fi result, not only TON execution

STON.fi provides protocol-specific APIs that are useful once you need to interpret what happened.

The current STON.fi DEX API documents:

GET /v1/swap/status for checking a swap using router address, owner address, and query ID
POST /v1/transaction/query for resolving a transaction from identifiers such as wallet address plus query ID or an external message hash
POST /v1/transaction/action_tree for obtaining STON.fi actions and their statuses from an originating transaction

The API base URL is https://api.ston.fi.

These endpoints solve a different problem from a generic TON indexer.

The indexer answers:

What transactions and messages happened on TON?

STON.fi-specific decoding answers:

What did those transactions mean for this swap?

For a direct STON.fi DEX integration, combining both gives you a stronger status pipeline:

TON Connect
    |
    v
External message
    |
    v
Indexer finds transaction
    |
    v
Indexer follows TON trace
    |
    v
Trace completes
    |
    v
STON.fi status or action verification
    |
    +--> succeeded
    |
    +--> failed / aborted / recovery path

This also makes debugging much easier. If your UI says that a swap failed, you can distinguish between "the initiating transaction was never found", "the TON trace is still executing", and "execution completed but the swap did not produce the intended result."

What changes when the swap uses Omniston?

Do not confuse generic indexer tracking with Omniston's own trade tracking interface.

For Omniston swaps, STON.fi provides trackTrade functionality through its SDKs and the underlying trade.track API. Tracking uses the quote ID, trader wallet address, and outgoing transaction hash. Omniston can report states such as waiting for the initial transfer, transferring, swapping, receiving funds, and a final settled trade result.

If you are already building with the Omniston SDK, its native trade tracker should usually be your primary protocol-level status source.

An indexer is still valuable for:

independent on-chain verification
debugging failed or unusual traces
rebuilding state after an application restart
storing your own transaction history
linking protocol status to raw TON transactions

The two approaches complement each other. They are not competing definitions of the same status.

Polling or streaming?

Polling is usually the easiest starting point.

After submission, poll quickly while the swap is active, then reduce the frequency after several unsuccessful attempts. Stop polling once you reach a terminal state. Add a maximum tracking window, but do not automatically classify a temporary timeout as an on-chain failure.

For faster interfaces, TON Center also provides a Streaming API using SSE and WebSockets. It can stream transactions, actions, and traces with pending, confirmed, and finalized finality levels. TON documentation warns that the streaming API does not replay events missed during a connection interruption, so applications that require complete state should resynchronize from API v3 after reconnecting.

A practical production pattern is therefore:

stream for responsiveness, query the indexer for recovery and truth reconstruction.

A practical STON.fi tracking checklist

Before shipping your status component, test more than the happy path.

Check that your application can recover a swap after a browser refresh, distinguish "not indexed yet" from "failed", follow the complete trace instead of only the wallet transaction, and validate the STON.fi-level result before displaying success.

Also store enough identifiers to investigate a transaction later. A wallet address by itself is usually not a strong correlation key when the same wallet can initiate several swaps close together.

Most importantly, make your status names describe what you actually know. Processing is safer than Success while internal messages are still active, and Verifying is safer than assuming every completed TON trace represents a completed swap.

Frequently Asked Questions

What is an indexer in TON?

An indexer reads blockchain data, parses transactions and messages, and stores them in a database optimized for queries. TON Center API v3 is an indexed API that supports traces, historical transactions, actions, Jetton data, and other structured information that is harder to obtain efficiently from raw node access.

Why can a STON.fi swap involve multiple transactions?

TON smart contracts communicate asynchronously through messages. One transaction processes a message for one account, and that account may send messages that trigger transactions on other accounts. A DEX operation can therefore become a trace containing wallet, router, pool, and token-related transactions rather than one monolithic transaction.

Does finding the wallet transaction mean the swap succeeded?

No. It proves that the initiating message was processed, not necessarily that the entire swap completed successfully. Follow the resulting trace and then verify the protocol-level swap result before showing a final success state.

What should I store after sending the swap?

Store a stable correlation record containing the wallet address, tracking hash or transaction identifier, swap creation time, and STON.fi-specific identifiers such as the query ID or router when your integration provides them. This lets your backend reconstruct status even if the frontend disappears.

Should I poll an indexer continuously?

Only while the operation is unresolved. Poll relatively frequently immediately after submission, then apply backoff. Once the swap reaches a terminal state, stop. For higher responsiveness, use streaming notifications while retaining historical polling as a recovery mechanism.

Can I use the STON.fi API instead of a TON indexer?

For some status questions, yes. STON.fi exposes swap status, transaction query, and transaction action-tree endpoints that understand STON.fi operations. A generic TON indexer is still useful when you need raw trace visibility, independent verification, historical analysis, or debugging outside STON.fi-specific abstractions.

How should I track an Omniston swap?

Use Omniston's native trade tracking when possible. Its SDK tracking accepts the quote ID, trader wallet address, and outgoing transaction hash and provides trade-specific lifecycle information. A TON indexer can then serve as an additional on-chain verification and debugging layer.

What is the safest way to display STON.fi swap status?

Use several stages rather than jumping directly from "sent" to "success": record the wallet submission, locate the transaction, wait for the trace to finish, and then verify the STON.fi-specific outcome. That model reflects TON's asynchronous execution much more accurately and produces a status UI that remains useful when something goes wrong.

Sources and Further Reading

STON.fi DEX API Reference - official REST endpoints for swap status, transaction resolution, and STON.fi action trees
STON.fi Omniston Swap Overview - official description of Omniston swap execution and the trade.track lifecycle
STON.fi Omniston React SDK - official SDK guidance for tracking an initiated Omniston trade
TON Center API v3 Overview - official description of TON's indexed API layer and available trace and action endpoints
TON Center Get Traces - official reference for querying traces by transaction, message, or trace identifiers
TON Connect Message Lookup - official guidance for identifying transactions from messages returned after wallet submission
TON Traces - explanation of how related messages and transactions form a TON execution trace
TON Center Streaming API - official documentation for real-time transaction, action, and trace monitoring

How to Decode a STON.fi Swap Transaction

Ivan “Crypto Vazima” Zimanov — Sun, 16 Aug 2026 06:59:27 +0000

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:

the correct input token arrived
the expected amount was recognized
the payload requested a swap
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:

The asset being traded, such as a jetton amount.
TON attached for execution, which can continue through the trace.
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

How to Send a STON.fi Swap Transaction from a TON Wallet

Ivan “Crypto Vazima” Zimanov — Wed, 12 Aug 2026 16:42:49 +0000

Build the swap with STON.fi, hand the transaction to TON Connect, and let the connected wallet sign and broadcast it.

A STON.fi swap is not sent by giving your dApp access to a user's private key. Your application prepares the contract message required for the swap, converts it into a TON Connect transaction request, and asks the connected TON wallet to approve it. The wallet remains responsible for signing and broadcasting the transaction.

For a modern STON.fi integration, the recommended mainnet pattern is to simulate the swap first, use the router metadata returned by STON.fi, build the corresponding transaction parameters with @ston-fi/sdk, and pass those parameters to sendTransaction() from TON Connect.

The full path looks like this:

Connect the TON wallet.
Simulate the swap.
Use the simulation's router information.
Ask the STON.fi SDK to build the contract message.
Convert that message into TON Connect format.
Ask the wallet to sign and broadcast it.
Verify the resulting transaction on-chain.

The separation between steps 4 and 5 is particularly useful. STON.fi knows how the swap contract should be called. TON Connect knows how to request authorization from the user's wallet.

What are you actually sending?

When you call one of the STON.fi SDK transaction-building methods, the SDK produces transaction parameters describing an internal message. The common result contains three important fields:

{
  to: Address;
  value: bigint;
  body?: Cell | null;
}

to is the destination contract address. value is the amount of TON that must accompany the message. body is the serialized contract payload describing the operation that STON.fi should execute.

Your dApp does not sign this message.

Instead, it transforms those parameters into something TON Connect can send to the wallet:

{
  address: swapParams.to.toString(),
  amount: swapParams.value.toString(),
  payload: swapParams.body?.toBoc().toString("base64"),
}

That distinction is worth remembering:

STON.fi SDK builds the swap message. TON Connect requests the wallet signature. The wallet broadcasts the transaction.

TON itself is message-driven. Smart contracts receive messages, process their payloads, and may generate transactions that change contract state. The payload created by the STON.fi SDK is therefore not arbitrary metadata. It is the instruction that the relevant contract will interpret when the message arrives.

Set up TON Connect first

For a React dApp, TON documentation recommends @tonconnect/ui-react. The package provides TonConnectUIProvider, TonConnectButton, useTonConnectUI, and wallet-state hooks that you can use without handling private keys yourself.

Install the packages needed for the basic STON.fi flow:

npm install @ston-fi/sdk @ston-fi/api @tonconnect/ui-react @ton/ton

You also need a public TON Connect manifest. For example:

{
  "url": "https://swap.example.com",
  "name": "My STON.fi Swap App",
  "iconUrl": "https://swap.example.com/icon-180.png"
}

In production, TON requires the manifest to be publicly reachable, and current documentation says it should be served through HTTPS. The wallet uses this metadata to identify the dApp during connection.

Wrap your React app with the provider:

import { TonConnectUIProvider } from "@tonconnect/ui-react";

export function Root() {
  return (
    <TonConnectUIProvider
      manifestUrl="https://swap.example.com/tonconnect-manifest.json"
    >
      <App />
    </TonConnectUIProvider>
  );
}

Then expose the wallet connection button:

import { TonConnectButton } from "@tonconnect/ui-react";

export function Header() {
  return <TonConnectButton />;
}

Inside your swap component you can read the connected address and access the transaction API:

import {
  useTonAddress,
  useTonConnectUI,
} from "@tonconnect/ui-react";

const userAddress = useTonAddress();
const [tonConnectUI] = useTonConnectUI();

If userAddress is empty, there is no connected account available to sign the swap.

Simulate before building the transaction

For STON.fi v2 mainnet swaps, hardcoding a router is not the preferred production pattern. STON.fi documentation recommends obtaining routing information from the API and using the router returned by the simulation. This lets the integration follow the router selected for the actual swap instead of assuming one specific contract configuration.

A simplified simulation looks like this:

import { StonApiClient } from "@ston-fi/api";

const stonApi = new StonApiClient();

const simulationResult = await stonApi.simulateSwap({
  offerAddress: fromAsset.contractAddress,
  askAddress: toAsset.contractAddress,
  offerUnits,
  slippageTolerance: "0.01",
});

The amount supplied as offerUnits must already be expressed in the asset's smallest units. Do not assume that every TON ecosystem asset uses the same number of decimals. The STON.fi quickstart explicitly uses asset metadata when converting user-facing amounts into blockchain units.

A simulation is useful for more than displaying an estimated output. It gives the transaction-building stage values such as the offer amount, minimum acceptable output, token addresses, and router information associated with that swap.

That creates an important safety boundary in your UI:

changing the input asset should invalidate the old simulation
changing the output asset should invalidate it
changing the amount should invalidate it
changing the slippage setting should trigger a new simulation
the transaction should be built from the current simulation, not from stale UI state

You want the transaction the wallet sees to correspond to the swap the user just reviewed.

Build the STON.fi swap message

Once you have a valid simulation and connected wallet, create the router from the router metadata supplied by STON.fi.

A compact version of the current API-driven pattern looks like this:

import { dexFactory, Client } from "@ston-fi/sdk";

const tonClient = new Client({
  endpoint: "https://toncenter.com/api/v2/jsonRPC",
});

const routerInfo = simulationResult.router;

const dexContracts = dexFactory(routerInfo);

const router = tonClient.open(
  dexContracts.Router.create(routerInfo.address)
);

const proxyTon = dexContracts.pTON.create(
  routerInfo.ptonMasterAddress
);

STON.fi's current v2 documentation specifically recommends feeding the router returned by the simulation into dexFactory() for mainnet-facing integrations rather than hardcoding the router contract.

Next, prepare the fields shared by the swap variants:

const sharedTxParams = {
  userWalletAddress: userAddress,
  offerAmount: simulationResult.offerUnits,
  minAskAmount: simulationResult.minAskUnits,
};

The exact builder depends on what you are swapping.

TON to jetton

const swapParams =
  await router.getSwapTonToJettonTxParams({
    ...sharedTxParams,
    proxyTon,
    askJettonAddress: simulationResult.askAddress,
  });

Jetton to TON

const swapParams =
  await router.getSwapJettonToTonTxParams({
    ...sharedTxParams,
    proxyTon,
    offerJettonAddress: simulationResult.offerAddress,
  });

Jetton to jetton

const swapParams =
  await router.getSwapJettonToJettonTxParams({
    ...sharedTxParams,
    offerJettonAddress: simulationResult.offerAddress,
    askJettonAddress: simulationResult.askAddress,
  });

The important result is the same in each case: you receive the destination, attached TON value, and payload needed for the contract call. STON.fi documents separate transaction builders for TON-to-jetton, jetton-to-TON, and jetton-to-jetton swaps.

Send the transaction through the TON wallet

Now the STON.fi-specific construction work is finished.

The remaining step is to hand the message to the wallet through TON Connect:

const result = await tonConnectUI.sendTransaction({
  validUntil: Math.floor(Date.now() / 1000) + 300,
  network: "-239",
  messages: [
    {
      address: swapParams.to.toString(),
      amount: swapParams.value.toString(),
      payload: swapParams.body?.toBoc().toString("base64"),
    },
  ],
});

This is the point where the wallet UI should appear and ask the user to review and approve the transaction.

There are several details here that are easy to overlook.

address comes directly from the STON.fi transaction parameters. Do not replace it with the address of the asset, pool, or some router address stored elsewhere in your UI.

amount is the TON value attached to the contract message. Pass the SDK-generated value rather than manually reconstructing the gas requirement.

payload is the contract body serialized as a Bag of Cells and encoded in base64 so TON Connect can include it in the outgoing message.

validUntil is a Unix timestamp in seconds. Current TON Connect documentation defines it in seconds and shows the pattern Math.floor(Date.now() / 1000) + 600. Some older examples in the ecosystem use Date.now() directly, which produces milliseconds, so this is a field worth checking carefully when adapting existing code.

network should be set explicitly. TON Connect currently identifies TON mainnet as -239 and testnet as -3. If the requested network conflicts with the wallet's connected network, the wallet can reject the request.

STON.fi's transaction-sending guide uses the same underlying pattern: obtain to, value, and body from the SDK, then pass them to the wallet implementation.

Put the full handler together

Here is the essential flow in one React handler:

import { StonApiClient } from "@ston-fi/api";
import { Client, dexFactory } from "@ston-fi/sdk";
import {
  useTonAddress,
  useTonConnectUI,
} from "@tonconnect/ui-react";

const stonApi = new StonApiClient();

export function SwapButton({
  fromAsset,
  toAsset,
  simulationResult,
}) {
  const userAddress = useTonAddress();
  const [tonConnectUI] = useTonConnectUI();

  const handleSwap = async () => {
    if (!userAddress) {
      throw new Error("Connect a wallet first");
    }

    if (!simulationResult) {
      throw new Error("Simulate the swap first");
    }

    const tonClient = new Client({
      endpoint: "https://toncenter.com/api/v2/jsonRPC",
    });

    const routerInfo = simulationResult.router;
    const dexContracts = dexFactory(routerInfo);

    const router = tonClient.open(
      dexContracts.Router.create(routerInfo.address)
    );

    const proxyTon = dexContracts.pTON.create(
      routerInfo.ptonMasterAddress
    );

    const sharedTxParams = {
      userWalletAddress: userAddress,
      offerAmount: simulationResult.offerUnits,
      minAskAmount: simulationResult.minAskUnits,
    };

    let swapParams;

    if (fromAsset.kind === "Ton") {
      swapParams =
        await router.getSwapTonToJettonTxParams({
          ...sharedTxParams,
          proxyTon,
          askJettonAddress: simulationResult.askAddress,
        });
    } else if (toAsset.kind === "Ton") {
      swapParams =
        await router.getSwapJettonToTonTxParams({
          ...sharedTxParams,
          proxyTon,
          offerJettonAddress:
            simulationResult.offerAddress,
        });
    } else {
      swapParams =
        await router.getSwapJettonToJettonTxParams({
          ...sharedTxParams,
          offerJettonAddress:
            simulationResult.offerAddress,
          askJettonAddress:
            simulationResult.askAddress,
        });
    }

    const result = await tonConnectUI.sendTransaction({
      validUntil:
        Math.floor(Date.now() / 1000) + 300,
      network: "-239",
      messages: [
        {
          address: swapParams.to.toString(),
          amount: swapParams.value.toString(),
          payload:
            swapParams.body
              ?.toBoc()
              .toString("base64"),
        },
      ],
    });

    console.log("Wallet response:", result);
  };

  return (
    <button onClick={handleSwap}>
      Swap
    </button>
  );
}

This code intentionally keeps quote generation separate from transaction sending. In a real application, you should also disable the button while a request is in progress, handle rejected wallet requests separately from network failures, refresh stale simulations, and display useful status feedback.

TON Connect documents USER_REJECTS_ERROR separately from malformed requests and unsupported methods, so a user pressing "Cancel" should not be presented as a protocol failure.

What happens after the wallet approves?

sendTransaction() asks the connected wallet to sign and broadcast the outgoing message. Current TON Connect documentation says the response can contain the base64 BoC of the broadcast external message, which can then be used as part of an on-chain lookup or tracking flow.

A resolved wallet promise should therefore not be treated as "the swap is definitely complete."

There are several different states your interface may need to distinguish:

the wallet request was opened
the user approved the request
the wallet broadcast the external message
the relevant contract received and processed the internal message
the swap completed successfully on-chain
the resulting token balances became visible in your application

TON transactions are produced as contracts process messages, so wallet authorization and smart contract execution are related but not identical events.

For a production interface, update the UI only when you have enough evidence for the state you are displaying. "Transaction submitted" is more accurate immediately after wallet submission than "Swap completed."

Common mistakes when sending STON.fi swaps

Most integration failures around this final step come from a small number of mismatches.

Building from stale simulation data. If the amount or asset changes after simulation, create a new simulation before building the transaction.

Hardcoding a production router. Current STON.fi v2 guidance favors the router metadata returned by its mainnet API.

Recreating the payload manually. Let the STON.fi SDK produce the contract body unless you have a specific low-level reason to construct the message yourself.

Using the wrong time unit for validUntil. TON Connect currently expects Unix seconds, not JavaScript milliseconds.

Assuming wallet approval equals swap completion. Submission still has to result in successful on-chain contract execution.

Treating cancellation as an execution error. A user can simply reject the wallet prompt, and TON Connect exposes a specific rejection error for that case.

Testing copied mainnet addresses or amounts blindly. TON's current documentation explicitly warns that mainnet transfers are irreversible and recommends replacing sample values and testing appropriately before using real funds.

Practical takeaway: keep the integration boundary simple. Use the STON.fi API to simulate the current swap, let dexFactory() and the relevant router helper produce the exact transaction parameters, then pass those parameters almost unchanged into TON Connect. Your dApp should coordinate the process, not sign on behalf of the user and not guess the contract payload.

Frequently Asked Questions

Does my dApp need the user's TON wallet seed phrase to send a STON.fi swap?

No. A normal client-side TON Connect integration should not obtain the user's seed phrase or private key. Your application constructs the requested transaction, while the connected wallet handles approval, signing, and broadcasting. This separation is one of the main reasons to integrate through TON Connect rather than importing wallet credentials into the application.

What does the STON.fi SDK actually provide to TON Connect?

The SDK provides the information required for the contract message, including its destination, attached TON value, and payload cell. Your application serializes the payload to a base64 BoC and places these values inside the messages array passed to sendTransaction().

Why should I simulate the swap before sending it?

Simulation gives you the swap-specific values needed to review and build the transaction, including the minimum output and router information used by the current API-driven v2 workflow. It also gives your interface a natural point to show the expected result before asking the wallet for authorization.

Should `validUntil` use milliseconds or seconds?

Use Unix seconds. Current TON Connect documentation defines validUntil as Unix seconds and demonstrates it with Math.floor(Date.now() / 1000) + .... This is important because JavaScript's Date.now() alone returns milliseconds.

What does `network: "-239"` mean?

It identifies TON mainnet in the current TON Connect transaction request format. Testnet is identified as -3. Setting the network explicitly lets the wallet reject a transaction request if the connected account is on an incompatible network.

Can the same wallet flow handle TON-to-jetton and jetton-to-jetton swaps?

Yes, but the STON.fi SDK method used to construct the transaction differs by swap type. The final TON Connect step still follows the same basic model: take the resulting destination, attached value, and payload, then request wallet approval through sendTransaction().

Does a successful `sendTransaction()` response prove that the STON.fi swap finished?

Not by itself. It proves that the wallet-side transaction request reached the submission stage represented by TON Connect's response. Contract processing happens on-chain afterward, so a production dApp should track or verify the resulting operation before presenting the swap as completed.

What should I verify immediately before sending a STON.fi swap from a TON wallet?

Verify that the wallet is still connected, the simulation still matches the selected assets and amount, the minimum output reflects the intended slippage setting, the router comes from the current simulation, and the transaction parameters were generated by the matching STON.fi SDK helper. Only then transform those parameters into the TON Connect request shown to the wallet for approval.

Sources and Further Reading

STON.fi Swap Guide (React) - Official end-to-end React example covering wallet connection, swap simulation, router selection, transaction construction, and TonConnect execution
STON.fi Swap v2 documentation - Official v2 swap documentation describing the API-driven mainnet workflow and dynamic router construction
STON.fi Transaction Sending - Official explanation of the to, value, and body transaction parameters returned by SDK transaction builders
STON.fi Via TonConnect - Official STON.fi example for converting SDK transaction parameters into a TonConnect transaction request
TON Connect Get Started - Official TON documentation for manifests, React integration, wallet connection, providers, and the TON Connect SDK choices
TON Connect Send a Transaction - Official current specification for sendTransaction, validUntil, network identifiers, raw messages, responses, and wallet errors
TON Messages and Transactions Overview - Official TON explanation of how messages are processed and how contract state changes become transactions
STON.fi API Client Source - Official STON.fi API implementation showing the API client and router-related methods used by developer integrations

How to Connect TON Connect to a STON.fi dApp

Ivan “Crypto Vazima” Zimanov — Thu, 06 Aug 2026 06:34:41 +0000

A practical React integration that connects a TON wallet, reads the wallet state, builds a STON.fi swap, and hands the transaction back to the wallet for approval.

Connecting TON Connect to a STON.fi dApp means giving your application a standard way to discover the user's TON wallet, read the connected address, and request transaction signatures without ever handling the user's private keys.

For a STON.fi swap interface, the flow is straightforward: TON Connect manages the wallet session, the STON.fi API simulates the swap, the STON.fi SDK builds the contract message, and TON Connect asks the wallet to sign and broadcast it. The dApp coordinates these pieces, but the wallet remains the signing authority throughout the process.

What TON Connect actually does in a STON.fi dApp

It helps to separate wallet connectivity from DEX logic.

STON.fi does not need your application to obtain a seed phrase or private key. Instead, TON Connect creates a communication layer between the dApp and a compatible wallet. After the person chooses a wallet and approves the connection, your frontend receives account information that can be used when preparing STON.fi transactions.

A typical integration has four responsibilities:

TON Connect manages connection, reconnection, wallet selection, and transaction requests.
STON.fi API supplies current asset and swap simulation information.
STON.fi SDK converts swap parameters into contract transaction data.
The wallet reviews, signs, and broadcasts the transaction.

The official STON.fi React quickstart uses exactly this division of responsibilities, combining @tonconnect/ui-react, @ston-fi/api, and @ston-fi/sdk.

The wallet connection therefore does not perform a swap by itself. It gives your STON.fi integration the address and signing channel needed to perform one.

Set up the React dependencies

For a React dApp, install the TON Connect React package together with the STON.fi SDK and API client.

npm install @tonconnect/ui-react @ston-fi/sdk @ston-fi/api

Depending on the rest of your application, you may also use TON libraries for blockchain utilities and amount conversion.

The important architectural point is to keep the responsibilities separate. Avoid implementing wallet-specific connection code for Tonkeeper, MyTonWallet, or other individual wallets when TON Connect already provides a common interface.

The official TON documentation describes @tonconnect/ui-react as the React binding around TON Connect UI. It provides the application provider, the standard wallet button, and hooks for accessing the connection and wallet state.

Create the TON Connect manifest first

Every TON Connect dApp needs a manifest that tells wallets which application is requesting the connection.

Create:

public/tonconnect-manifest.json

A minimal version looks like this:

{
  "url": "https://your-dapp.example",
  "name": "My STON.fi dApp",
  "iconUrl": "https://your-dapp.example/icon-180.png"
}

You can also provide privacy policy and terms URLs when appropriate.

The manifest is not just decoration. Wallets fetch it to identify your application before presenting the connection request. The URL and icon should therefore point to real public resources when you deploy the dApp.

Before debugging your React code, open the manifest URL directly in a browser:

https://your-dapp.example/tonconnect-manifest.json

If it cannot be fetched there, a wallet may not be able to fetch it either.

A useful deployment checklist is:

Serve the manifest over HTTPS in production.
Use your real dApp domain.
Make the icon publicly accessible.
Keep the application name recognizable.
Do not copy another project's manifest unchanged.

For local development, STON.fi's React guide demonstrates serving the manifest from the application's public directory and pointing the provider at the current origin.

Add TON Connect to the React component tree

The next step is to wrap the application in TonConnectUIProvider.

For a Vite-based React project, your entry file can look like this:

import React from "react";
import ReactDOM from "react-dom/client";
import { TonConnectUIProvider } from "@tonconnect/ui-react";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <TonConnectUIProvider
      manifestUrl={`${window.location.origin}/tonconnect-manifest.json`}
    >
      <App />
    </TonConnectUIProvider>
  </React.StrictMode>
);

Everything that calls TON Connect React hooks must be rendered beneath this provider.

You can then add the standard connection button:

import { TonConnectButton } from "@tonconnect/ui-react";

export function Header() {
  return (
    <header>
      <TonConnectButton />
    </header>
  );
}

Clicking it opens the TON Connect wallet picker. After a successful connection, the same component reflects the connected state automatically.

You can build your own button and call openModal() if your design requires a custom interface, but starting with TonConnectButton removes unnecessary connection logic while you build the rest of the STON.fi integration.

Read the connected wallet correctly

A STON.fi swap needs the connected wallet address because that address becomes part of the transaction parameters.

TON Connect exposes it through hooks:

import {
  useIsConnectionRestored,
  useTonAddress,
  useTonWallet
} from "@tonconnect/ui-react";

export function WalletStatus() {
  const restored = useIsConnectionRestored();
  const wallet = useTonWallet();
  const address = useTonAddress();

  if (!restored) {
    return <p>Restoring wallet connection...</p>;
  }

  if (!wallet) {
    return <p>Connect a wallet to continue.</p>;
  }

  return <p>Connected: {address}</p>;
}

useIsConnectionRestored() deserves special attention. TON Connect attempts to restore an existing session when the application loads. Until that process finishes, a missing wallet does not necessarily mean that the person is disconnected. Redirecting or disabling your interface too early can create a visible connection flicker or incorrect state. TON's documentation specifically recommends waiting for restoration before making that decision.

For your swap interface, that gives you a simple state model:

Connection state is still being restored.
No wallet is connected.
A wallet is connected and the swap interface can use its address.

Do not confuse wallet connection with authentication. If your backend needs cryptographic proof that a person controls an address, TON Connect also supports ton_proof. A plain connected address is useful for transaction construction, but it should not automatically become a trusted login credential for a sensitive backend session.

Connect the wallet state to a STON.fi swap

Now the two systems meet.

For production STON.fi swaps, the current v2 documentation recommends an API-driven approach rather than hardcoding a router address. Your dApp first simulates the swap, receives router metadata, creates the matching SDK contracts, and then builds the transaction parameters.

Conceptually, the flow is:

Connected wallet
      |
      v
STON.fi swap simulation
      |
      v
Router metadata
      |
      v
STON.fi SDK builds transaction
      |
      v
TON Connect sendTransaction()
      |
      v
Wallet approval
      |
      v
TON blockchain

Here is a focused example for a TON-to-jetton swap:

import { useTonAddress, useTonConnectUI } from "@tonconnect/ui-react";
import { StonApiClient } from "@ston-fi/api";
import { Client, dexFactory, toUnits } from "@ston-fi/sdk";

const stonApi = new StonApiClient();

const tonClient = new Client({
  endpoint: "https://toncenter.com/api/v2/jsonRPC"
});

export function SwapButton() {
  const userAddress = useTonAddress();
  const [tonConnectUI] = useTonConnectUI();

  const swap = async () => {
    if (!userAddress) {
      throw new Error("Connect a wallet first");
    }

    const simulation = await stonApi.simulateSwap({
      offerAddress: "ton",
      askAddress: "<jetton-master-address>",
      offerUnits: toUnits("1", 9).toString(),
      slippageTolerance: "0.01"
    });

    const routerInfo = simulation.router;
    const dexContracts = dexFactory(routerInfo);

    const router = tonClient.open(
      dexContracts.Router.create(routerInfo.address)
    );

    const proxyTon = dexContracts.pTON.create(
      routerInfo.ptonMasterAddress
    );

    const txParams = await router.getSwapTonToJettonTxParams({
      userWalletAddress: userAddress,
      offerAmount: simulation.offerUnits,
      askJettonAddress: simulation.askAddress,
      minAskAmount: simulation.minAskUnits,
      proxyTon,
      queryId: BigInt(Date.now())
    });

    await tonConnectUI.sendTransaction({
      validUntil: Math.floor(Date.now() / 1000) + 300,
      network: "-239",
      messages: [
        {
          address: txParams.to.toString(),
          amount: txParams.value.toString(),
          payload: txParams.body?.toBoc().toString("base64")
        }
      ]
    });
  };

  return (
    <button disabled={!userAddress} onClick={swap}>
      Swap with STON.fi
    </button>
  );
}

The exact token addresses and input amounts should come from your interface rather than hardcoded production values.

The current STON.fi v2 guidance is especially important here: the REST API returns router information with the simulation result, and dexFactory() lets the SDK construct contracts appropriate for that router. This avoids making your integration depend on one manually selected production router.

What happens when `sendTransaction()` runs?

The STON.fi SDK does not need to sign anything.

Its job is to produce parameters such as the destination address, attached TON value, and serialized payload. Your code converts those values into a TON Connect transaction request.

TON Connect then presents that request to the wallet.

For raw transaction messages, the important fields are:

Field	Purpose
`address`	Contract or wallet receiving the message
`amount`	TON value attached in the smallest unit
`payload`	Base64 encoded contract message body
`validUntil`	Unix timestamp after which the request is invalid
`network`	TON network expected by the dApp

According to the current TON Connect transaction specification, validUntil uses Unix seconds. For mainnet, the network identifier is -239; testnet uses -3. TON also recommends specifying the network explicitly so a request is rejected if the connected wallet is on a different network.

When the wallet approves the request, it signs and broadcasts the transaction. Your frontend never receives the private key.

That boundary is one of the most important design principles in the integration:

STON.fi prepares the DEX action. TON Connect transports the signing request. The wallet authorizes it.

Avoid the integration mistakes that cause most problems

The basic connection takes only a small amount of code. Most problems appear around state management, transaction construction, or assumptions about the network.

Before shipping, check these areas.

Do not hardcode production routing when the STON.fi API can provide it. Current STON.fi v2 documentation recommends simulating first and using the router object returned by the API with dexFactory().

Do not treat a stale simulation as a guaranteed execution price. Pool conditions can change between simulation and wallet confirmation. Use the minimum output calculated for the swap and refresh quotes when appropriate.

Do not mix milliseconds and Unix seconds in validUntil. The current TON Connect request format expects seconds.

Do not enable the swap while the wallet state is unresolved. Wait for connection restoration and require an address before generating transaction parameters.

Do not manually ask for a seed phrase. A normal TON Connect integration has no reason to request one.

Do not assume sendTransaction() means the complete swap succeeded. It means the wallet accepted the request and broadcast the signed message. Your interface should separately track the resulting on-chain execution if it needs a final success state.

There is another TON-specific detail worth remembering. Smart contract interactions can involve multiple messages, and execution across recipient contracts is not automatically equivalent to one atomic operation. STON.fi documentation also describes refund behavior for swaps when execution conditions are not satisfied.

For a production interface, show transaction states such as submitted, processing, completed, and failed instead of changing the button directly from "Swap" to "Success" as soon as the wallet returns.

A practical STON.fi integration checklist

At this point, you can test the entire connection as one continuous workflow.

Load the dApp and wait for TON Connect session restoration.
Connect a compatible TON wallet.
Confirm that your application receives the correct address.
Select a source asset, destination asset, and amount.
Request a fresh STON.fi swap simulation.
Review the expected output and minimum output in your interface.
Build the matching transaction through the STON.fi SDK.
Pass the resulting message to tonConnectUI.sendTransaction().
Review the transaction inside the wallet before signing.
Track the resulting blockchain operation rather than relying only on the frontend request state.

STON.fi's official developer documentation recommends using its SDK together with TON Connect for production application interaction instead of manually constructing low-level contract BOCs unless you have a specialized reason to do so.

The practical takeaway is simple: keep wallet connection, quote generation, transaction construction, and transaction signing as separate layers. Once those boundaries are clear, TON Connect becomes a small but critical bridge between your STON.fi frontend and the wallet that actually authorizes the swap.

Frequently Asked Questions

Does STON.fi require TON Connect?

A frontend can interact with TON contracts through other technical signing setups, but TON Connect is the standard wallet connection approach for user-facing TON dApps. STON.fi's own React swap quickstart integrates @tonconnect/ui-react with the STON.fi API and SDK, making it the natural approach for a browser-based application where users sign transactions with their own wallets.

Does TON Connect give my dApp the user's private key?

No. TON Connect creates a connection with the wallet and lets the dApp submit signing requests. The private key remains under the wallet's control. Your application receives account information and transaction responses, not the seed phrase or private signing key. A dApp asking users to enter their seed phrase is not following the normal TON Connect model.

Do I need a `tonconnect-manifest.json` file?

Yes. The manifest identifies your dApp to compatible wallets and includes information such as the application URL, name, and icon. Host it at a publicly accessible URL and pass that URL to TonConnectUIProvider. Optional fields can also point to your terms of use and privacy policy.

Should I use `useTonAddress()` or `useTonWallet()`?

Use whichever matches the information you need. A STON.fi transaction often needs the connected address, so useTonAddress() is convenient. useTonWallet() gives you the broader connected wallet object. It is also useful to combine them with useIsConnectionRestored() so your interface does not mistake an unfinished restoration attempt for a disconnected wallet.

Is connecting a wallet the same as authenticating a user?

No. A wallet connection gives your frontend an account and a communication session. If you need secure backend authentication, TON Connect supports ton_proof, where the wallet signs proof data that your server verifies. You generally do not need to introduce backend authentication merely to let a connected wallet review and sign a normal STON.fi transaction.

Why should a STON.fi dApp simulate the swap before building the transaction?

Simulation gives your application current execution information, including expected amounts, minimum output, and router metadata. Current STON.fi v2 documentation recommends an API-driven production flow in which the simulation result determines the router passed to dexFactory(). That is safer for maintainability than tying the integration permanently to one hardcoded router address.

Can I use the STON.fi REST API for testnet swaps?

The current STON.fi v2 SDK documentation states that the REST API at api.ston.fi serves mainnet data. You can test TON Connect itself and lower-level contract integrations separately, but do not assume the production API-driven STON.fi simulation flow automatically maps to testnet. Follow the specific STON.fi testnet documentation when testing contract operations there.

What should I verify before letting someone sign a STON.fi swap?

Check that the wallet is connected, the simulation is fresh, the source and destination assets are correct, the amount uses the correct token decimals, the minimum output reflects the intended slippage tolerance, and the transaction is being sent on the expected network. Then let the wallet provide the final approval step instead of attempting to sign anything inside your frontend.

Sources and Further Reading

TON Connect, Get started - Official introduction to manifests and TON Connect integration paths
TON Connect, Connect a wallet - Official documentation for the provider, wallet button, connection restoration, wallet state, and ton_proof
TON Connect, Send a transaction - Official request format for sendTransaction(), including validUntil, network selection, and raw messages
TON Connect React API - Reference for TonConnectUIProvider, TonConnectButton, useTonConnectUI, useTonAddress, and wallet hooks
STON.fi Swap Guide (React) - Official end-to-end example combining TON Connect, the STON.fi API, and the STON.fi SDK
STON.fi SDK v2 Swap - Official production guidance for simulation, dynamic router selection, dexFactory(), and v2 swap construction
STON.fi SDK - Overview of the TypeScript and JavaScript SDK and current DEX contract integration tools
STON.fi REST API Reference - Official API overview covering swap simulation, swap status, pools, assets, and related DEX data
STON.fi DEX v2 Smart Contracts - Contract-level documentation and the recommendation to use the official SDK with TON Connect for production application integrations

How to Build a Basic STON.fi Swap Interface

Ivan “Crypto Vazima” Zimanov — Mon, 03 Aug 2026 09:25:49 +0000

A practical React guide to wallet connection, token selection, swap simulation, transaction building, and on-chain execution on TON.

A basic STON.fi swap interface needs to do much more than place two token selectors next to a Swap button. A useful implementation has to connect a TON wallet, load supported assets, convert human-readable amounts into blockchain units, simulate the trade, preserve the resulting slippage protection, build the correct STON.fi transaction, and finally ask the wallet to sign it.

The cleanest architecture separates those responsibilities. STON.fi provides a REST API for asset data and swap simulation, its TypeScript SDK builds the contract transaction, and TON Connect handles wallet interaction. Your frontend coordinates the three without ever taking custody of the user's private keys.

What the interface actually needs to do

For a minimal React application, think of the swap as five connected states:

Wallet state: Is a TON wallet connected, and what is its address?
Asset state: Which token is being sold and which token is being received?
Amount state: How many blockchain units does the entered amount represent?
Simulation state: What route, minimum output, and Router should the transaction use?
Transaction state: Has the wallet received, rejected, or submitted the transaction?

That division matters because a swap quote is not permanent. If the user changes the source token, destination token, or amount, the previous simulation should immediately become invalid.

A minimal interface therefore needs only a few visible controls:

Connect Wallet
From token selector
To token selector
Amount input
Simulated output
Minimum received
Swap button
Loading, rejection, and transaction status messages

You can add charts, token balances, price impact displays, routing information, or transaction history later. They are useful improvements, but they are not required to understand the core STON.fi flow.

Set up the React project

STON.fi's official React quickstart uses its API client, DEX SDK, and TON Connect together. The essential dependencies are:

npm install @ston-fi/sdk @ston-fi/api @tonconnect/ui-react @ton/ton

The roles are intentionally different.

@ston-fi/api gives the frontend access to STON.fi data and simulation methods. @ston-fi/sdk converts the selected swap into contract-ready transaction parameters. @tonconnect/ui-react connects the application to the user's wallet and submits the transaction for approval.

A simple component tree might look like this:

App
├── TonConnectButton
└── SwapForm
    ├── FromAssetSelect
    ├── AmountInput
    ├── ToAssetSelect
    ├── QuotePanel
    └── SwapButton

You do not need to split the first prototype into that many files. One App.jsx component is perfectly reasonable while learning the flow. The important part is keeping the logical stages separate in your state.

Connect a TON wallet first

TON Connect is the standard wallet connection protocol for TON applications. The dApp receives the connected account and can request signatures or transactions, but the wallet retains control of the keys.

Wrap the React application with TonConnectUIProvider:

import { TonConnectUIProvider } from "@tonconnect/ui-react";

<TonConnectUIProvider
  manifestUrl={`${window.location.origin}/tonconnect-manifest.json`}
>
  <App />
</TonConnectUIProvider>

Then place a connect button somewhere visible:

import {
  TonConnectButton,
  useTonAddress,
  useTonConnectUI,
} from "@tonconnect/ui-react";

const walletAddress = useTonAddress();
const [tonConnectUI] = useTonConnectUI();

The manifest is not an optional branding detail. Wallets use it to identify your application. Host tonconnect-manifest.json from your own domain and provide your real application name, URL, and icon.

A basic file looks like this:

{
  "url": "https://example.com",
  "name": "My STON.fi Swap",
  "iconUrl": "https://example.com/icon.png"
}

For production, avoid copying another project's manifest or permanently pointing to a demo manifest. The wallet approval screen should identify the application the user is actually interacting with.

Load assets without assuming every token has nine decimals

The next job is populating the two asset selectors.

STON.fi exposes asset information through its REST API, including an asset query endpoint. The official API client wraps those calls, so you can initialize it directly:

import { StonApiClient } from "@ston-fi/api";

const api = new StonApiClient();

You can then fetch assets when the application loads and keep the result in React state.

One implementation detail deserves more attention than it usually gets: do not assume every asset uses nine decimal places.

A wallet might display 1.25 TOKEN, while the blockchain and STON.fi API work with integer base units. The conversion depends on that token's metadata.

For example, with nine decimals:

1.25 TOKEN = 1,250,000,000 units

With six decimals:

1.25 TOKEN = 1,250,000 units

STON.fi's own swap quickstart reads the decimal precision dynamically from asset metadata for exactly this reason.

For production code, avoid converting large token values with floating-point arithmetic such as Number(amount) * 10 ** decimals. A string-to-BigInt parser is safer:

function toUnits(value, decimals) {
  const [whole = "0", fraction = ""] = value.trim().split(".");
  const padded = (fraction + "0".repeat(decimals)).slice(0, decimals);

  return (
    BigInt(whole) * 10n ** BigInt(decimals) +
    BigInt(padded || "0")
  ).toString();
}

You should also reject negative amounts, malformed decimals, excessive precision, and zero before calling the API.

Simulate before allowing the user to sign

The swap button should not construct a trade from an old displayed price or a hardcoded pool.

STON.fi provides simulateSwap, which lets the application calculate the swap before execution. Its REST API exposes a dedicated swap simulation endpoint for expected output, fees, and transaction-related data.

A simplified request looks like this:

const simulation = await api.simulateSwap({
  offerAddress: fromAsset.contractAddress,
  askAddress: toAsset.contractAddress,
  offerUnits,
  slippageTolerance: "0.01",
});

Here, 0.01 represents a 1 percent slippage tolerance.

Simulation is not merely a cosmetic price preview. It connects the UI state to the transaction you will eventually build. In the current DEX v2 integration pattern, the result also supplies routing information that should be reused during transaction construction.

Your quote panel should show enough information for a meaningful decision. At minimum, display:

amount being sold
expected or quoted output
minimum acceptable output
selected slippage tolerance
source and destination assets

Most importantly, clear the simulation whenever the user changes an input.

function resetQuote() {
  setSimulation(null);
}

function onAmountChange(value) {
  setAmount(value);
  resetQuote();
}

Otherwise, a user can simulate 10 tokens, change the field to 100, and still see a Swap button associated with the stale 10-token result.

Let the STON.fi API choose the Router

One of the most important implementation details in the current STON.fi DEX v2 documentation is that a production application should not hardcode a Router simply because an example contract address worked previously.

The recommended mainnet flow is:

Simulate the swap.
Read the Router metadata returned by the simulation.
Pass that Router metadata into dexFactory().
Build the transaction with the resulting Router contract.

STON.fi explicitly recommends this API-driven approach so integrations can follow Router changes without being tied to a manually embedded contract address. Its REST API currently serves mainnet data, while testnet integration requires a different, manually configured approach.

The central setup is compact:

import { dexFactory, Client } from "@ston-fi/sdk";

const tonClient = new Client({
  endpoint: "https://toncenter.com/api/v2/jsonRPC",
});

const routerInfo = simulation.router;
const contracts = dexFactory(routerInfo);

const router = tonClient.open(
  contracts.Router.create(routerInfo.address)
);

const proxyTon = contracts.pTON.create(
  routerInfo.ptonMasterAddress
);

The simulation and transaction should remain one logical operation. Reuse fields such as offerUnits, minAskUnits, token addresses, and Router metadata from the simulation rather than independently reconstructing the swap from UI values.

That keeps the transaction you ask the wallet to sign aligned with the trade the interface just showed.

Build the right transaction for the asset pair

STON.fi exposes different Router helpers because TON and jettons do not enter the swap through exactly the same path.

Your interface therefore needs three branches:

const common = {
  userWalletAddress: walletAddress,
  offerAmount: simulation.offerUnits,
  minAskAmount: simulation.minAskUnits,
};

let txParams;

if (fromAsset.kind === "Ton") {
  txParams = await router.getSwapTonToJettonTxParams({
    ...common,
    proxyTon,
    askJettonAddress: simulation.askAddress,
  });
} else if (toAsset.kind === "Ton") {
  txParams = await router.getSwapJettonToTonTxParams({
    ...common,
    proxyTon,
    offerJettonAddress: simulation.offerAddress,
  });
} else {
  txParams = await router.getSwapJettonToJettonTxParams({
    ...common,
    offerJettonAddress: simulation.offerAddress,
    askJettonAddress: simulation.askAddress,
  });
}

The Router helper returns the information the wallet needs, including the destination, attached TON value, and message body.

At the protocol level, the Router acts as the DEX entry point and directs token operations toward the appropriate pool. The pool contains the AMM state used for the swap. In DEX v2, the swap payload can also carry parameters such as minimum output, receiver, refund information, and an execution deadline.

For a basic interface, you do not need to manually construct those low-level cells. That is exactly the problem the official SDK is designed to solve.

Send the transaction through TON Connect

Once txParams exists, convert it into a TON Connect transaction request.

await tonConnectUI.sendTransaction({
  validUntil: Math.floor(Date.now() / 1000) + 300,
  network: "-239",
  messages: [
    {
      address: txParams.to.toString(),
      amount: txParams.value.toString(),
      payload: txParams.body?.toBoc().toString("base64"),
    },
  ],
});

There is one small detail here that can prevent a surprisingly confusing bug: validUntil uses a Unix timestamp in seconds, not JavaScript milliseconds. Five minutes from now is therefore calculated with Math.floor(Date.now() / 1000) + 300. TON's current TON Connect documentation defines mainnet as network -239.

Calling sendTransaction() does not expose the wallet's private key to your React application. Instead, the wallet presents the transaction to the user for approval and then signs and broadcasts it if they accept.

Your UI should distinguish at least four outcomes:

waiting for wallet approval
rejected by the user
submitted to TON
execution confirmed or failed on-chain

Do not interpret the successful return of sendTransaction() as proof that every downstream contract action completed successfully. TON transactions can generate chains of asynchronous messages, so broadcast and final swap settlement are different stages.

STON.fi exposes swap status and transaction-related API endpoints that can help an application follow the operation after submission.

Following one swap from input to settlement

Consider a user opening your interface to exchange TON for a jetton.

They connect a wallet through TON Connect and choose TON in the first selector. Your application loads the destination asset metadata and converts the entered TON amount into blockchain units.

Next, simulateSwap() asks STON.fi what the trade currently looks like. Instead of merely taking a displayed number from that result, the application stores the entire simulation object.

The simulation gives the frontend the values that matter for execution, including the minimum acceptable output and Router metadata. dexFactory() uses that Router description to instantiate the corresponding contracts. Because TON is the source asset, the frontend calls the TON-to-jetton Router helper and receives the prepared transaction parameters.

Only then does the application open the wallet approval flow.

The user's decision therefore occurs after the following chain:

Choose assets
   |
Enter amount
   |
Convert to base units
   |
Simulate through STON.fi API
   |
Review minimum output
   |
Create Router from simulation metadata
   |
Build swap transaction with STON.fi SDK
   |
Request signature through TON Connect
   |
Track on-chain execution

That is the core of a basic STON.fi swap interface. The UI is small because STON.fi's API and SDK handle much of the protocol-specific construction, but the frontend still has an important responsibility: it must preserve the relationship between what was simulated, what was displayed, and what was actually signed.

Common mistakes that make a basic swap unsafe or unreliable

A prototype can appear functional while still containing several subtle integration problems.

Hardcoding the Router. For current DEX v2 mainnet integrations, use Router metadata supplied by the STON.fi simulation and dexFactory() instead.

Using floating-point arithmetic for token amounts. Convert decimal strings into integer blockchain units using token-specific metadata.

Keeping an old quote after an input changes. Clear simulation state whenever the asset pair, amount, or relevant swap setting changes.

Setting minimum output to an arbitrary tiny value. minAskAmount is the user's execution protection. Reuse the simulation result rather than replacing it with a convenient placeholder.

Treating wallet submission as final settlement. A signed and broadcast TON transaction can still lead to later contract messages, failures, or refunds.

Sending transactions from an unidentified dApp. Serve a correct TON Connect manifest from your own application domain.

Ignoring user rejection. Declining a wallet request is a normal outcome, not an exceptional application failure. Give the user a clean way to retry.

A solid first version does not need professional trading features. It needs faithful state management and a transaction that corresponds to the quote on screen.

Practical takeaway: build the interface around the simulation object, not around the Swap button. Once a trade has been simulated, treat that result as the source for Router selection, offered units, minimum output, and transaction construction. If anything affecting the trade changes, discard the simulation and request a new one before enabling execution.

Frequently Asked Questions

Do I need a backend to build a basic STON.fi swap interface?

Not necessarily. A basic React implementation can call the STON.fi API, build the transaction with the SDK, and ask a connected wallet to sign through TON Connect directly from the frontend. A backend becomes useful for application-specific analytics, caching, access control, monitoring, or other services, but it should never require collecting the user's wallet private key.

Why should a swap be simulated before execution?

Simulation tells the application what the trade currently looks like before the wallet signs anything. It also produces values such as the minimum acceptable output and, in the current STON.fi DEX v2 workflow, Router metadata used to build the actual transaction. If inputs change after simulation, request a new simulation rather than executing the old one.

What is the difference between expected output and minimum received?

Expected output describes the result indicated by the current quote or simulation. Minimum received is the lower execution boundary created by the selected slippage tolerance. If execution would produce less than that minimum, the swap should not simply proceed at any price. Your interface should make that protection visible instead of hiding it behind the Swap button.

Can I assume every TON token uses nine decimals?

No. Token amounts displayed to people must be converted into integer blockchain units using that asset's own decimal metadata. Hardcoding nine decimals can make an interface submit a radically different amount for tokens with another precision. Read the metadata supplied for the selected asset and use integer-safe conversion logic.

Should I hardcode a STON.fi v2 Router address?

Not for the recommended production mainnet flow. Current STON.fi documentation advises developers to simulate the swap first, use the Router metadata contained in that result, and instantiate the corresponding contracts through dexFactory(). This reduces the chance that an integration becomes tied to an obsolete Router configuration.

Does TON Connect execute the STON.fi swap itself?

No. TON Connect is the wallet communication layer. Your application builds the STON.fi transaction, then TON Connect asks the user's wallet to approve, sign, and broadcast it. STON.fi smart contracts process the resulting on-chain messages. Keeping those roles separate makes the integration easier to reason about and prevents the frontend from handling private keys.

How can I verify that a STON.fi swap actually completed?

Do not rely only on the fact that the wallet accepted the transaction request. Treat submission and settlement as separate states. Track the resulting on-chain activity or use STON.fi transaction and swap-status facilities where appropriate. Update the interface only when you have evidence of the final result, including a possible failure or refund path.

Sources and Further Reading

STON.fi Swap Guide (React) - Official end-to-end example for building a React swap interface with the STON.fi API, SDK, and TON Connect
STON.fi DEX v2 Swap - Current API-driven production pattern, Router discovery, dexFactory(), and v2 transaction construction
STON.fi REST API Reference - Swap simulation, asset queries, Router information, transaction queries, and swap status endpoints
STON.fi REST API - Overview of the official HTTP interface used alongside the DEX contracts
STON.fi DEX Architecture - Explanation of the Router, Pool, and contract roles involved in swaps
STON.fi Router v2 Reference - Low-level swap payload fields, minimum output behavior, deadlines, routing, and refund mechanics
TON Connect Get Started - Official React setup for the provider, wallet connection, manifest, and connection state
TON Connect Send Transaction - Official transaction request format, validUntil, network selection, message format, response, and wallet errors

How to Request a Swap Quote from the STON.fi API

Ivan “Crypto Vazima” Zimanov — Sat, 01 Aug 2026 14:01:11 +0000

A practical guide to simulating a TON swap, reading the returned price data, and carrying the quote safely into transaction construction.

If your application needs to ey sign a swap, STON.fi exposes a direct way to request that information: POST https://api.ston.fi/v1/swap/simulate. STON.fi calls the operation a swap simulation, but in a wallet, trading interface, bot, or backend it serves the role of a swap quote. You provide the asset being sold, the asset being bought, the amount in blockchain units, and a slippage tolerance. The API returns the expected output together with minimum output, fees, price impact, gas information, pool data, and the Router that should be used if you continue to execution.

The critical detail is that the quote is not just a price. It is routing and execution context for a specific swap at a specific moment.

What a STON.fi swap quote actually gives you

A DEX quote answers a more useful question than "What is token A worth in token B?" It asks, "If I sell this exact amount through the liquidity available now, what should the swap produce?"

STON.fi's DEX API exposes this through /v1/swap/simulate. The official API reference describes the endpoint as a pre-execution simulation that calculates expected output, fees, and gas costs. The current response schema also includes price_impact, min_ask_units, recommended_min_ask_units, recommended_slippage_tolerance, pool information, and a complete router object. ion matters because an AMM quote depends on the input size and pool state. Two requests for the same pair can return different results if the amount changes or if liquidity changes between requests.

For a typical interface, the quote should give you enough data to display:

expected amount received
minimum acceptable amount received
swap rate
price impact
protocol or swap fee information
estimated gas parameters
selected pool and Router

A simulation does not execute anything on-chain. No wallet signature is required merely to ask the API for the quote.

The four inputs you need

For a direct swap simulation, four values are essential: the asset you are selling, the asset you want to receive, the amount being sold, and the slippage tolerance. The raw REST endpoint uses snake_case query parameters, while the official TypeScript client exposes camelCase properties. The client then maps them to the REST request.

Purpose	Raw REST parameter	`@ston-fi/api` property
Asset to sell	`offer_address`	`offerAddress`
Asset to receive	`ask_address`	`askAddress`
Amount to sell	`units`	`offerUnits`
Slippage tolerance	`slippage_tolerance`	`slippageTolerance`

The REST endpoint also supports optional parameters such as pool_address, referral settings, and DEX version restrictions. For a basic quote request, start with the four required values and add optional routing constraints only when your application has a reason to control them.

One implementation detail is easy to miss: this is a POST endpoint, but the documented swap inputs are query parameters. The official @ston-fi/api client does the same internally when it calls /v1/swap/simulate. The amount to blockchain units first

units does not mean a human-readable amount such as "1.5" unless the token happens to use zero decimals. It means the smallest indivisible units of the offered asset.

TON jettons can use different decimal precision. TON documentation explicitly warns developers not to assume that every jetton has the same decimals value. For example, many assets use 9 decimals, while USDT on TON uses 6. An incorrect decimal conversion can change the intended amount by orders of magnitude. And is conceptually:

blockchain units = display amount * 10^decimals

For production code, avoid ordinary JavaScript floating-point arithmetic for token amounts. A simple string-based conversion can keep the calculation exact:

function toUnits(amount, decimals) {
  const [whole, fraction = ""] = amount.split(".");
  const padded = (fraction + "0".repeat(decimals)).slice(0, decimals);

  return (
    BigInt(whole) * 10n ** BigInt(decimals) +
    BigInt(padded || "0")
  ).toString();
}

const offerUnits = toUnits("1.5", 9);
// "1500000000"

Fetch the asset's real decimal precision from trusted metadata rather than hardcoding 9. If your project already uses STON.fi tooling, use the metadata returned for the selected asset and keep amounts as strings or integers until you format them for display.

Request the quote with the raw REST API

At the HTTP level, the request is small. You can call the production API directly with fetch, curl, or any HTTP client.

A generic curl request looks like this:

curl -X POST \
  "https://api.ston.fi/v1/swap/simulate?offer_address=<OFFER_ASSET>&ask_address=<ASK_ASSET>&units=<OFFER_UNITS>&slippage_tolerance=0.01" \
  -H "accept: application/json"

In JavaScript, building the query parameters explicitly makes the request easier to inspect:

const offerAddress = "<OFFER_ASSET>";
const askAddress = "<ASK_ASSET>";
const offerUnits = "<AMOUNT_IN_SMALLEST_UNITS>";

const params = new URLSearchParams({
  offer_address: offerAddress,
  ask_address: askAddress,
  units: offerUnits,
  slippage_tolerance: "0.01",
});

const response = await fetch(
  `https://api.ston.fi/v1/swap/simulate?${params.toString()}`,
  { method: "POST" }
);

if (!response.ok) {
  throw new Error(`STON.fi quote failed: ${response.status}`);
}

const quote = await response.json();
console.log(quote);

The 0.01 value represents 1 percent slippage tolerance. STON.fi's official TypeScript client currently documents 0.01 as a recommended value, while the simulation response can also return a recommended_slippage_tolerance. Treat slippage as a transaction protection setting, not as another name for price impact. plication, wrap the call in normal network error handling, validate the response shape, and reject zero or malformed amounts before sending the request.

Use the official TypeScript client when possible

If you are already working in TypeScript or JavaScript, @ston-fi/api removes most of the raw HTTP plumbing. The package is the official TypeScript client for the STON.fi HTTP API and exposes simulateSwap() directly.

npm install @ston-fi/api

Then request a quote:

`ts
import { StonApiClient } from "@ston-fi/api";

const client = new StonApiClient();

const quote = await client.simulateSwap({
offerAddress: "",
askAddress: "",
offerUnits: "",
slippageTolerance: "0.01",
});

console.log({
expectedOutput: quote.askUnits,
minimumOutput: quote.minAskUnits,
priceImpact: quote.priceImpact,
swapRate: quote.swapRate,
router: quote.router,
});

There is one naming difference worth remembering. The raw REST response uses fields such as ask_units and min_ask_units; the client normalizes API responses into camelCase, so your TypeScript code reads askUnits and minAskUnits. The official client source and response types make this mapping visible. applications, this client is the cleaner option because it gives you a stable application-facing interface while still using the same STON.fi REST API underneath.

Read the response as execution data, not just a number

Suppose your UI only prints ask_units. You have technically displayed an expected output, but you have thrown away much of the information that makes the quote useful.

The most important raw REST fields to inspect are:

ask_units: the simulated output amount.
min_ask_units: the minimum output associated with the supplied slippage tolerance.
recommended_min_ask_units: the API's recommended minimum output.
price_impact: the effect of this swap size on the execution price.
swap_rate: the simulated exchange rate.
fee_units and fee_percent: fee information returned for the route.
gas_params: estimated gas-related values.
pool_address: the pool selected for the simulation.
router: the Router metadata returned with the route.

The response type in the official client includes all of these fields. use expected output with guaranteed output.** A quote reflects a simulation against current state. If pool reserves change before the transaction executes, the final conditions can differ. That is why the minimum output and slippage protection exist.

A useful quote review in your interface can therefore be compact:

"You receive" from expected output
"Minimum received" from the minimum output
"Price impact" as a separate risk signal
fee estimate
a warning when the quote is old or conditions have materially changed

If a quote is going to sit on screen for a while, request it again before constructing or submitting the transaction.

Carry the returned Router into the swap

The most important production pattern appears after the quote is returned.

STON.fi's current v2 SDK documentation explicitly recommends an API-driven workflow: simulate first, take the router object from the simulation result, pass it into dexFactory(), and then build the transaction against the returned Router rather than hardcoding a Router contract address. The documentation says this approach keeps integrations compatible with Router upgrades. It also states that api.ston.fi serves mainnet data. off looks like this:

`
ts
import { dexFactory, Client } from "@ston-fi/sdk";
import { StonApiClient } from "@ston-fi/api";

const apiClient = new StonApiClient();

const simulationResult = await apiClient.simulateSwap({
offerAddress: "",
askAddress: "",
offerUnits: "",
slippageTolerance: "0.01",
});

const { router: routerInfo } = simulationResult;
const dexContracts = dexFactory(routerInfo);

const tonClient = new Client({
endpoint: "",
});

const router = tonClient.open(
dexContracts.Router.create(routerInfo.address)
);
` `

At that point, you have moved from "What would this swap look like?" to "Which contract configuration should build this swap?" The quote and transaction are two stages of the same workflow.

STON.fi's swap documentation also recommends reusing values from the simulation result when constructing the actual transaction. That reduces the chance that your signed payload describes a different route or minimum output from the one your interface just showed.

Common mistakes to avoid

Most integration bugs around quoting are not exotic smart contract failures. They are data-handling mistakes before a transaction is ever built.

Passing display amounts as **units***.* "1" and "1000000000" can represent the same human amount for a 9-decimal token, but they are very different API inputs.

Assuming every jetton has 9 decimals. Read the token metadata. TON's jetton documentation specifically warns that decimals vary. SON body to the raw simulation endpoint and ignoring its documented query parameters.** If you call REST directly, follow the current OpenAPI schema. If you use @ston-fi/api, let the client handle the mapping. ice impact and slippage as the same value.** Price impact describes how the trade affects the quoted rate through available liquidity. Slippage tolerance defines how much unfavorable movement you are willing to accept between quote and execution.

Hardcoding the Router. Use the Router returned by the simulation for the mainnet execution flow recommended by STON.fi. uote indefinitely.** A simulation is a snapshot, not a reservation. Refresh it when enough time has passed or when the amount, pair, or slippage setting changes.

A good practical rule is simple: treat the quote as disposable data that must stay synchronized with the transaction you are about to ask the wallet to sign.

Frequently Asked Questions

Is `/v1/swap/simulate` a real swap?

No. It simulates the swap and returns expected execution data without moving funds or requiring a wallet signature. Execution is a separate step in which your application builds the appropriate TON transaction and asks the wallet to sign it. The simulation is therefore ideal for price previews, validation, and transaction preparation.

What does `units` mean in the STON.fi quote request?

It is the amount of the offered asset in its smallest blockchain units. You must convert the human-readable amount using that asset's decimals metadata. For a token with 9 decimals, 1.5 tokens is 1,500,000,000 units. Do not assume every TON jetton has 9 decimals.

Is slippage tolerance the same as price impact?

No. Price impact reflects how the size of the requested swap affects the quoted execution price through pool liquidity. Slippage tolerance is the maximum adverse change your transaction is prepared to accept. STON.fi returns price impact separately and uses the slippage setting when calculating minimum output values.

Can I quote an exact output amount instead?

Use POST /v1/reverse_swap/simulate. The normal /v1/swap/simulate endpoint starts with a known amount to sell and estimates what you receive. The reverse endpoint starts with the amount you want to receive and calculates the required input. STON.fi exposes both flows in the REST API and in @ston-fi/api.

Should I hardcode a STON.fi Router address after getting a quote?

No for the normal mainnet integration pattern. STON.fi's current v2 documentation recommends taking the Router metadata from the simulation response and constructing the SDK contracts dynamically with dexFactory(). That keeps the transaction builder aligned with the route selected by the API and avoids depending on a manually fixed Router address.

Can I use `api.ston.fi` to request testnet swap quotes?

The current STON.fi v2 swap documentation states that the REST API at api.ston.fi serves mainnet data. Its testnet instructions use a manual contract setup instead of the mainnet API-driven routing workflow. If you are building a production mainnet integration, use the API-driven pattern; treat testnet as a separate setup.

What should my app check immediately before using a STON.fi quote?

Confirm that the pair, input amount, token decimals, slippage setting, expected output, minimum output, and returned Router still match what the user sees. If the quote is stale, request a fresh simulation. Then build the transaction from that simulation data instead of reconstructing the route from hardcoded values. That keeps the visible quote and the transaction as closely aligned as possible.

DEV Community: Ivan “Crypto Vazima” Zimanov

How to Handle a Failed STON.fi Swap in an App

Start by separating the failure stages

Design the swap as a state machine

Prevent avoidable failures before the wallet opens

Handle wallet errors without lying to the user

Verify the outcome on-chain after broadcast

Read STON.fi refund signals correctly

Following one failed swap from start to finish

Frequently Asked Questions

Does sendTransaction() succeeding mean my STON.fi swap succeeded?

Should I automatically retry every failed swap?

Why can a swap fail after the wallet approved it?

What should I do when a swap fails because of slippage?

Can a failed STON.fi swap return a different token?

Should I hardcode the STON.fi Router address in my app?

What is the safest flow for handling a failed STON.fi swap in an app?

Sources and Further Reading

How to Estimate Gas for a STON.fi Transaction

Why TON gas is different from the Ethereum mental model

What actually contributes to a TON transaction cost

Budget is not the same as final cost

Start with the exact STON.fi operation

Use STON.fi swap simulation as the primary estimate

How to interpret the three fields

Let the SDK build the transaction budget

Be careful when TON itself is the asset being swapped

When should you calculate fees yourself?

How to validate your estimate after the swap

Common mistakes to avoid

Frequently Asked Questions

Does every STON.fi swap use the same amount of gas?

Does a larger swap require proportionally more gas?

Is the TON attached for gas the same as the final transaction fee?

What happens if too little TON is attached?

Can I use TON's estimateFee API for a STON.fi swap?

What is forwardGas in a STON.fi simulation?

Should developers hardcode STON.fi gas values?

What is the safest way to estimate gas before a STON.fi transaction?

Sources and Further Reading

How to Calculate Minimum Received for a STON.fi Swap

The formula behind minimum received

Quick reference

Expected output and minimum received are different numbers

Do not subtract price impact twice

Why can the quote move before your swap executes?

How STON.fi enforces minimum received

Calculating minimum received from a STON.fi quote

1. Start with the current expected output

2. Convert slippage into decimal form

3. Subtract the tolerance from 1

4. Multiply the quote by the result

For developers, use minAskUnits from the simulation

Practical developer checklist

What minimum received does not include

A practical STON.fi example

Frequently Asked Questions

What is minimum received in a crypto swap?

How do I calculate minimum received from slippage?

Is price impact included in minimum received?

Does higher slippage increase minimum received?

What is min_out on STON.fi?

What is minAskUnits in the STON.fi API?

Should I calculate STON.fi minimum received manually before every swap?

What should I check before confirming a STON.fi swap?

Sources and Further Reading

How to Build a STON.fi Pool Explorer

What a useful STON.fi pool explorer should show

Model the data around pools, assets, and routers

Fetch and join the STON.fi API data

Turn raw blockchain values into readable metrics

Build the pool list and detail views

Handle pricing and pool types correctly

Add on-chain verification and production hardening

Frequently Asked Questions

Do I need to run a TON node to build a STON.fi pool explorer?

Which STON.fi endpoint should I start with?

Can I calculate a token's price directly from pool reserves?

What should I use as the pool's liquidity or TVL figure?

Why do I need the router endpoint if I already have the pool?

Does `sendTransaction()` succeeding mean my STON.fi swap succeeded?

Can I use TON's `estimateFee` API for a STON.fi swap?

What is `forwardGas` in a STON.fi simulation?

For developers, use `minAskUnits` from the simulation

What is `min_out` on STON.fi?

What is `minAskUnits` in the STON.fi API?

Should I use `getAssets()` or `queryAssets()`?

What should I do if `meta.imageUrl` or `meta.displayName` is missing?

Do I need `@ston-fi/sdk` to fetch liquidity pools?

What does `GET /v1/pools` return?