DEV Community: Ivan “Crypto Vazima” Zimanov

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.

How to Install and Configure the STON.fi SDK

Ivan “Crypto Vazima” Zimanov — Wed, 29 Jul 2026 06:51:27 +0000

Set up a TypeScript project, connect the required STON.fi and TON components, and prepare a reliable foundation for swaps and liquidity operations.

Installing the STON.fi SDK requires more than adding one npm package. The SDK creates and opens the smart contract wrappers your application needs, but a complete integration usually also requires a TON RPC client, the STON.fi API, and a wallet connection layer.

For a production swap application, these components work together. The STON.fi API discovers assets, simulates the trade, and returns the correct Router metadata. The SDK converts that information into contract instances and transaction parameters. TON Connect then asks the user's wallet to approve and send the transaction.

The official SDK is written for JavaScript and TypeScript applications and acts as a thin wrapper around STON.fi contracts, including Router, Pool, LP Account, Vault, and pTON contracts.

Key takeaways

Install @ston-fi/sdk together with @ston-fi/api and @ton/ton.
Add a TON Connect package when users will sign transactions through a wallet.
Use the STON.fi API to simulate operations and discover the appropriate Router.
Avoid hardcoding mainnet Router addresses in production integrations.
Keep blockchain units, RPC access, wallet signing, and API data as separate layers.

What the STON.fi SDK actually provides

The SDK is the contract interaction layer of a STON.fi integration. It gives your application TypeScript classes and helper functions for working with STON.fi smart contracts without manually constructing cells, operation codes, and message bodies.

Its main responsibilities include:

creating Router and Pool contract wrappers
preparing swap transaction parameters
preparing liquidity deposit and withdrawal parameters
opening LP Account and Vault contracts
representing pTON when the native TON asset is involved
converting API Router metadata into the correct contract classes

The current v2 documentation covers newer contract functionality such as single-sided liquidity provision, Vault operations, additional pool types, and improved gas handling. The repository still includes v1 classes because existing pools and integrations may continue to use them.

The SDK does not replace every other component in your application. It does not provide a token search interface, store private keys, choose a wallet for the user, or guarantee that a proposed transaction is economically suitable.

A useful mental model is:

Component	Main responsibility
`@ston-fi/api`	Assets, pools, Router metadata, simulations, and protocol data
`@ston-fi/sdk`	Smart contract wrappers and transaction parameters
`@ton/ton` or the SDK `Client`	Reading TON blockchain state through an RPC endpoint
TON Connect	Connecting a wallet and requesting transaction approval
Your application	Validation, interface, error handling, and transaction monitoring

Keeping these responsibilities separate makes the integration easier to test and upgrade.

Choose the right project setup

Before installing packages, decide where the SDK will run.

A browser dApp normally needs the SDK, the STON.fi API client, and TON Connect. A backend service may use the SDK and a TON RPC client without TON Connect, but it then needs a separate and carefully secured signing method if it sends transactions.

For a React application, a practical starting stack is:

React with TypeScript
Vite or Next.js
@ston-fi/sdk
@ston-fi/api
@ton/ton
@tonconnect/ui-react

For a Node.js script, bot, or backend service, you can start with:

TypeScript
tsx for local execution
@ston-fi/sdk
@ston-fi/api
@ton/ton

Do not install @ston-fi/omniston-sdk as a substitute for @ston-fi/sdk. Omniston is a separate aggregation protocol and package. It is appropriate when your application needs aggregated or cross-DEX execution, not when the goal is direct interaction with STON.fi DEX contracts.

Create the project and install the packages

The following example uses React, TypeScript, and Vite because it provides a small project that is easy to inspect.

1. Create the application

npm create vite@latest stonfi-sdk-starter -- --template react-ts
cd stonfi-sdk-starter
npm install

Start the untouched project once:

npm run dev

Opening the starter page before adding blockchain dependencies helps separate project setup problems from SDK configuration problems.

2. Install the STON.fi and TON packages

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

The official SDK installation command is npm install @ston-fi/sdk. The additional packages provide API data, TON primitives, blockchain access, and wallet connection support required by a practical frontend integration.

The equivalent pnpm command is:

pnpm add @ston-fi/sdk @ston-fi/api @ton/ton @tonconnect/ui-react

For a backend-only TypeScript project, create a simpler environment:

mkdir stonfi-sdk-service
cd stonfi-sdk-service
npm init -y

npm install @ston-fi/sdk @ston-fi/api @ton/ton
npm install --save-dev typescript tsx @types/node

Add scripts to package.json:

{
  "scripts": {
    "dev": "tsx src/index.ts",
    "typecheck": "tsc --noEmit",
    "build": "tsc"
  }
}

Package versions should normally be committed through your lockfile. Avoid copying old version numbers from tutorials because SDK examples can change when Router classes, factory helpers, or peer dependencies are updated.

Configure TypeScript and the browser runtime

The STON.fi SDK is designed for TypeScript, so strict compiler settings are useful. They catch incorrect addresses, missing transaction fields, and incompatible contract types before runtime.

A Vite React project already includes a suitable TypeScript configuration. For a standalone Node.js project, you can use:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

Handling browser polyfills

TON libraries may use Node-compatible primitives such as Buffer. Some browser bundlers provide the required compatibility automatically, while others need an explicit polyfill.

For Vite, install:

npm install --save-dev vite-plugin-node-polyfills

Then update vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { nodePolyfills } from "vite-plugin-node-polyfills";

export default defineConfig({
  plugins: [
    react(),
    nodePolyfills({
      include: ["buffer"],
      globals: {
        Buffer: true,
      },
    }),
  ],
});

The official STON.fi React quickstart uses a Buffer polyfill in its Vite configuration. Add it when your build reports that Buffer is undefined or cannot be resolved, rather than adding unrelated Node polyfills without a reason.

Add environment variables

Create .env.local:

VITE_TON_RPC_ENDPOINT=https://toncenter.com/api/v2/jsonRPC

Add a type declaration in src/vite-env.d.ts if your project does not already provide one:

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_TON_RPC_ENDPOINT: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Anything prefixed with VITE_ becomes visible in the browser bundle. Never place a private key, wallet mnemonic, or secret RPC credential in a Vite environment variable.

A public frontend can use a public endpoint or a restricted browser-safe credential. Sensitive API keys belong on a backend that your frontend accesses through controlled application endpoints.

Configure the blockchain and STON.fi clients

Create src/lib/stonfi.ts:

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

const endpoint = import.meta.env.VITE_TON_RPC_ENDPOINT;

if (!endpoint) {
  throw new Error("VITE_TON_RPC_ENDPOINT is not configured");
}

export const tonClient = new Client({
  endpoint,
});

export const stonApiClient = new StonApiClient();

These two clients solve different problems.

Client opens contract wrappers and reads data from TON through the configured RPC endpoint. StonApiClient talks to the STON.fi HTTP API and requires no configuration for its standard public endpoint. The API client can retrieve assets, pools, Routers, wallet positions, and simulation results.

Keeping both instances in one module prevents every component from creating its own client.

Discover the Router dynamically

Older examples often instantiate a specific Router class or copy a known contract address. That can work for controlled tests, but production applications should not assume that every asset pair uses the same Router version or pool type.

The current mainnet-first pattern is:

Ask the STON.fi API to simulate the operation.
Read the Router metadata returned by the simulation.
Pass that metadata into dexFactory().
Open the generated Router contract with the blockchain client.
Build transaction parameters from the same simulation values.

Create src/lib/prepareSwap.ts:

import { dexFactory } from "@ston-fi/sdk";
import { stonApiClient, tonClient } from "./stonfi";

type PrepareSwapInput = {
  offerAddress: string;
  askAddress: string;
  offerUnits: string;
  slippageTolerance?: string;
};

export async function prepareSwap({
  offerAddress,
  askAddress,
  offerUnits,
  slippageTolerance = "0.01",
}: PrepareSwapInput) {
  const simulation = await stonApiClient.simulateSwap({
    offerAddress,
    askAddress,
    offerUnits,
    slippageTolerance,
  });

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

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

  const proxyTon = contracts.pTON.create(
    routerInfo.ptonMasterAddress,
  );

  return {
    simulation,
    router,
    proxyTon,
  };
}

The simulation result includes values such as the offered asset, requested asset, offered units, protected minimum output, and Router information. Reusing those values helps ensure that the transaction being constructed matches the route the application displayed to the user.

This file deliberately stops before building or sending a transaction. Installation and configuration should first prove that API access, Router discovery, contract creation, and TypeScript compilation all work.

Work with integer blockchain units

Do not pass human-readable decimal values directly into contract methods unless a specific helper explicitly accepts them.

A token interface might display 1.25, but the blockchain operation needs an integer based on that token's decimals. A token with six decimals represents 1.25 as 1250000 units, while a token with nine decimals represents it as 1250000000.

The asset metadata should determine the conversion. Avoid assuming that every jetton uses nine decimals.

Also avoid normal JavaScript floating-point arithmetic for financial amounts. Convert the user's string input into integer units, keep transaction amounts as strings or bigint, and only format them back into decimals for display.

Add TON Connect for wallet approval

The SDK prepares transaction parameters, but it should not receive a user's seed phrase or private key in a normal browser dApp. TON Connect provides the wallet connection and approval layer.

Create public/tonconnect-manifest.json:

{
  "url": "https://your-domain.example",
  "name": "STON.fi SDK Starter",
  "iconUrl": "https://your-domain.example/icon-180.png"
}

For production, the manifest must be available through a public HTTPS URL. The wallet retrieves it to display the application's identity during connection. The icon should use a wallet-supported format such as PNG.

Wrap the application in src/main.tsx:

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { TonConnectUIProvider } from "@tonconnect/ui-react";
import App from "./App";
import "./index.css";

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

Add a connection button:

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

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

TON Connect is the standard wallet connection protocol for TON dApps. It lets an application read the connected address and request transaction approval without taking possession of the wallet's keys. It does not replace the STON.fi SDK or the blockchain data client.

Verify the installation before building a swap

A useful first test is an API request that does not send a transaction.

Replace src/App.tsx temporarily:

import { useState } from "react";
import { TonConnectButton } from "@tonconnect/ui-react";
import { stonApiClient } from "./lib/stonfi";

export default function App() {
  const [status, setStatus] = useState("Not tested");

  const testConfiguration = async () => {
    try {
      setStatus("Loading STON.fi assets...");

      const response = await stonApiClient.getAssets();

      console.log("STON.fi asset response:", response);
      setStatus("SDK environment is configured");
    } catch (error) {
      console.error(error);
      setStatus(
        error instanceof Error
          ? error.message
          : "Configuration test failed",
      );
    }
  };

  return (
    <main>
      <h1>STON.fi SDK Starter</h1>

      <TonConnectButton />

      <button type="button" onClick={testConfiguration}>
        Test configuration
      </button>

      <p>{status}</p>
    </main>
  );
}

Run the checks:

npm run dev
npm run build

The development server proves that the browser can load the modules. The production build is equally important because missing polyfills, module resolution problems, and environment variable mistakes sometimes appear only during bundling.

Before continuing, confirm that:

the application compiles without TypeScript errors
the asset request returns a response
the wallet connection button opens
the manifest loads from its expected URL
no private data appears in the frontend bundle
the production build completes successfully

Common configuration mistakes and production checks

One frequent mistake is treating the STON.fi API and the SDK as interchangeable. The API provides indexed data and simulations. The SDK creates smart contract objects and transaction messages. A production application normally needs both.

Another problem is mixing examples from different SDK generations. A v1 example may use DEX.v1.Router, while a current v2 workflow can use API Router metadata and dexFactory(). Check the documentation section and package version before copying a method name.

Watch for these additional issues:

Hardcoded Router addresses: Resolve the mainnet Router from API metadata whenever possible.
Mainnet and testnet mixing: The public STON.fi API serves mainnet data, so its Router information should not be combined with testnet assets or contracts.
Unsafe decimal arithmetic: Convert display amounts into integer token units before simulation or transaction construction.
Exposed secrets: Never place mnemonics, private keys, or unrestricted API credentials in browser code.
Missing simulation: Generate and review a current simulation before constructing the transaction.
Unverified token addresses: Symbols and names can be duplicated, so use verified asset addresses and metadata.
No expiration strategy: Transaction requests should not remain valid indefinitely.
No post-transaction tracking: A wallet acceptance response is not the same as confirmed on-chain execution.

A production-ready project should also log operation identifiers, display the minimum protected output, handle RPC and API timeouts, prevent duplicate submissions, and explain wallet rejection separately from blockchain failure.

Practical takeaway

A correct STON.fi SDK installation has four working layers: the STON.fi API can return current protocol data, the TON client can open the dynamically selected contracts, the SDK can build typed transaction parameters, and TON Connect can request wallet approval. Test each layer independently before combining them into a real swap. That approach makes configuration errors easier to identify and reduces the risk of signing a transaction built from stale or mismatched data.

Frequently Asked Questions

Is the STON.fi SDK only for TypeScript?

The SDK is written in TypeScript but can also be imported into JavaScript projects. TypeScript is preferable because contract methods contain many address, amount, and configuration fields that benefit from static checking. Even in a JavaScript application, the package's included type declarations can improve editor suggestions and reveal incorrect method usage.

Do I need `@ston-fi/api` to use `@ston-fi/sdk`?

Not for every low-level operation, but it is strongly recommended for production applications. The API provides asset information, pool data, simulations, and Router metadata. Without it, you may need to hardcode contract information and independently calculate or retrieve values that the API already exposes in a consistent format.

Why should I install `@ton/ton`?

The STON.fi SDK is built around TON contract primitives and blockchain client behavior. The @ton/ton package provides core types and utilities used across TON integrations. Installing it explicitly also helps the package manager resolve compatible peer dependencies and makes TON-specific imports available to the rest of your application.

Should a new integration use STON.fi v1 or v2?

A new integration should normally begin with the current v2 documentation and an API-driven Router selection flow. However, the Router returned for a particular operation should determine the contract classes your application opens. Do not force every operation through a manually selected version when dexFactory() can interpret the Router metadata.

Can the STON.fi SDK be tested on TON testnet?

Yes, but testnet configuration is more manual. The public STON.fi API provides mainnet protocol data, so its simulations and Router metadata should not be reused for testnet transactions. Testnet development may require known test contracts, suitable jettons, funded wallets, and pools with enough liquidity to exercise the intended operation.

Why does Vite report that `Buffer` is undefined?

Some TON dependencies use Node-compatible binary utilities, while browsers do not provide every Node global automatically. In a Vite project, adding vite-plugin-node-polyfills and enabling the Buffer polyfill usually resolves this specific issue. Add only the compatibility features your build needs rather than exposing a complete Node environment in the browser.

Does the SDK connect to the user's wallet?

No. The SDK prepares contract calls and transaction parameters. TON Connect, a wallet-specific SDK, or another signer sends those parameters for approval. In a standard non-custodial frontend, TON Connect allows the wallet to sign without revealing private keys to your application.

What is the minimum reliable setup for a STON.fi swap?

Use @ston-fi/api to simulate the swap, take the Router metadata from that result, pass it to dexFactory(), open the Router through the configured TON client, and generate transaction parameters from the simulated amounts. Finally, send those parameters through TON Connect and monitor the resulting on-chain operation instead of treating wallet approval as final settlement.

Sources and Further Reading

STON.fi DEX SDK documentation - Installation, supported SDK generations, and links to version-specific contract guides
STON.fi SDK v2 swap documentation - API-driven Router discovery, dexFactory(), simulation data, and transaction preparation
STON.fi React swap quickstart - Complete frontend setup using the SDK, STON.fi API, TON Connect, Vite, and browser polyfills
STON.fi SDK GitHub repository - Source code, package structure, supported contract wrappers, and the official Next.js demo application
STON.fi API GitHub repository - Installation, zero-configuration client setup, and examples for assets, pools, Routers, farms, and operations
STON.fi SDK npm package - Published package information and the official installation command
TON Connect getting started guide - Manifest requirements, React packages, provider configuration, and wallet connection setup
TON Connect overview - Wallet connection architecture, available packages, and the separation between wallet communication and blockchain integration

How to Integrate STON.fi Swaps with the TypeScript SDK

Ivan “Crypto Vazima” Zimanov — Tue, 28 Jul 2026 06:55:06 +0000

Build a production-minded swap flow with the STON.fi API, SDK v2, React, and TON Connect.

Integrating a STON.fi swap is not just a matter of calling one SDK function. A reliable application first requests a simulation from the STON.fi API, uses the returned routing information to select the correct smart contracts, builds the transaction through the TypeScript SDK, and finally asks the connected wallet to sign it through TON Connect.

The SDK never needs access to a seed phrase or private key. It prepares the blockchain message, while the wallet remains responsible for authorization and broadcasting. That separation lets you add non-custodial swaps to a wallet, Telegram Mini App, game, payment interface, or DeFi dashboard without taking custody of user funds.

The integration has four separate layers

A common source of confusion is treating the STON.fi SDK as a complete swapping service. It is more accurate to think of the integration as a pipeline with four components.

Component	Main responsibility	Signs transactions?
`@ston-fi/api`	Loads assets, simulates swaps, and returns routing metadata	No
`@ston-fi/sdk`	Creates the correct Router, pTON, and transaction parameters	No
TON RPC client	Reads contract data and opens contract wrappers	No
TON Connect	Sends the prepared message to the connected wallet	The wallet does

The STON.fi API should normally be the starting point. Its simulation response includes the expected amounts, minimum protected output, asset addresses, and the complete Router object. You pass that Router object to dexFactory(), which selects the correct contract implementation for the route.

This API-driven approach is safer than copying a Router address from an old tutorial. STON.fi supports different Router versions and contract types, so an address or class that works for one pool may not be suitable for another. The official v2 documentation recommends allowing the simulation response to dictate which Router should be used.

The complete flow looks like this:

Connect a wallet with TON Connect.
Select the offer and ask assets.
Convert the entered amount into blockchain units.
Simulate the swap through @ston-fi/api.
Create the correct DEX contracts with dexFactory().
Build the appropriate swap transaction parameters.
Send the generated message through TON Connect.
Track the submitted transaction separately.

Set up the TypeScript project

The examples below use React and Vite, but the same SDK flow works with Next.js, Vue, Svelte, a Telegram Mini App, or a backend service that only prepares unsigned transaction messages.

Install the required packages:

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

For a Vite application, you may also need a browser polyfill for Buffer, which TON libraries use when serializing a cell into a base64 Bag of Cells, or BoC:

npm install --save-dev vite-plugin-node-polyfills

A minimal Vite configuration can expose only the required buffer polyfill:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { nodePolyfills } from "vite-plugin-node-polyfills";

export default defineConfig({
  plugins: [
    react(),
    nodePolyfills({
      include: ["buffer"],
      globals: {
        Buffer: true,
      },
    }),
  ],
});

The official STON.fi quickstart uses the SDK for transaction construction, the API client for asset discovery and simulation, and TON Connect UI for wallet communication.

Connect the wallet without handling private keys

Wrap the application with TonConnectUIProvider:

// src/main.tsx
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>
);

Create public/tonconnect-manifest.json:

{
  "url": "https://your-app.example",
  "name": "STON.fi Swap Demo",
  "iconUrl": "https://your-app.example/icon.png"
}

Use your real production domain and a publicly accessible icon before deployment. The wallet reads this manifest to identify the application requesting a connection.

Inside the swap component, add the wallet button and hooks:

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

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

  return (
    <section>
      <TonConnectButton />
      <p>{userAddress || "Connect a wallet to continue"}</p>
    </section>
  );
}

TON Connect creates an encrypted connection between the application and wallet. Your application can read the connected address and request a transaction, but it does not receive the wallet's private key.

Treat token amounts as integer units

Smart contracts do not receive values such as 1.25 directly. They receive integers expressed in the asset's smallest units.

An asset with nine decimals represents 1.25 as 1250000000. An asset with six decimals represents the same displayed amount as 1250000.

Do not automatically apply toNano() to every jetton. That helper assumes nine decimals, while some TON assets use another precision. The SDK provides decimal-aware utilities, and the STON.fi API also supplies token metadata that your interface can use.

A small string-based parser avoids the rounding problems that can occur when a decimal amount is first converted to a JavaScript number:

type SwapAsset = {
  contractAddress: string;
  kind: "Ton" | "Jetton";
  decimals: number;
  symbol: string;
};

export function parseUnits(value: string, decimals: number): string {
  const normalized = value.trim();

  if (!/^\d+(\.\d+)?$/.test(normalized)) {
    throw new Error("Enter a valid positive decimal amount");
  }

  const [whole, fraction = ""] = normalized.split(".");

  if (fraction.length > decimals) {
    throw new Error(
      `This asset supports no more than ${decimals} decimal places`
    );
  }

  const units = `${whole}${fraction.padEnd(decimals, "0")}`.replace(
    /^0+(?=\d)/,
    ""
  );

  return units || "0";
}

function getApiAddress(asset: SwapAsset): string {
  return asset.kind === "Ton" ? "ton" : asset.contractAddress;
}

The user-facing name of the native network coin may be displayed as Gram, but current contract and API identifiers can still contain names such as Ton, "ton", and pTON. Those values are part of the integration interface and should not be replaced with display labels.

Simulate the swap before building anything

Simulation is the quote stage. It tells the application which route is available and provides the values needed to create a protected transaction.

Initialize the API client and request a simulation:

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

const stonApi = new StonApiClient();

export async function simulateStonSwap(params: {
  fromAsset: SwapAsset;
  toAsset: SwapAsset;
  amount: string;
}) {
  const { fromAsset, toAsset, amount } = params;

  if (fromAsset.contractAddress === toAsset.contractAddress) {
    throw new Error("Select two different assets");
  }

  const offerUnits = parseUnits(amount, fromAsset.decimals);

  if (BigInt(offerUnits) <= 0n) {
    throw new Error("The swap amount must be greater than zero");
  }

  return stonApi.simulateSwap({
    offerAddress: getApiAddress(fromAsset),
    askAddress: getApiAddress(toAsset),
    offerUnits,
    slippageTolerance: "0.01",
  });
}

In this example, "0.01" represents a 1 percent slippage tolerance. It is an example rather than a universal recommendation. Your interface should explain the setting and allow the product to choose an appropriate default.

Several fields from the response are especially important:

offerUnits is the input amount in blockchain units.
minAskUnits is the minimum protected amount that the transaction may accept.
offerAddress and askAddress identify the assets used by the route.
router contains the version and contract information required by the SDK.

Do not calculate minAskUnits independently after receiving a simulation. Use the value returned for that exact quote. If the amount, assets, or slippage setting changes, discard the previous simulation and request a new one.

A production interface should display the expected output as well as the minimum protected output. These values answer different questions: expected output describes the estimate, while minimum output defines the transaction's on-chain protection.

STON.fi's current v2 workflow is mainnet-first. Its public REST API supplies mainnet routing data, so it should not be combined with a testnet RPC endpoint or testnet wallet when constructing a real swap.

Let `dexFactory()` select the Router

After simulation, avoid manually choosing DEX.v2_1, DEX.v2_2, a constant-product Router, or another contract class. Feed the returned Router information into dexFactory().

The resulting factory output contains contract classes compatible with that Router, including the appropriate pTON implementation when the native coin participates in the route.

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

type SwapSimulation = Awaited<
  ReturnType<StonApiClient["simulateSwap"]>
>;

type BuildSwapParams = {
  simulation: SwapSimulation;
  fromAsset: SwapAsset;
  toAsset: SwapAsset;
  userAddress: string;
  rpcEndpoint: string;
};

export async function buildStonSwapMessage({
  simulation,
  fromAsset,
  toAsset,
  userAddress,
  rpcEndpoint,
}: BuildSwapParams) {
  const tonClient = new Client({
    endpoint: rpcEndpoint,
  });

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

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

  const commonParams = {
    userWalletAddress: userAddress,
    offerAmount: simulation.offerUnits,
    minAskAmount: simulation.minAskUnits,
  };

  if (fromAsset.kind === "Ton") {
    const proxyTon = dex.pTON.create(
      routerInfo.ptonMasterAddress
    );

    return router.getSwapTonToJettonTxParams({
      ...commonParams,
      proxyTon,
      askJettonAddress: simulation.askAddress,
    });
  }

  if (toAsset.kind === "Ton") {
    const proxyTon = dex.pTON.create(
      routerInfo.ptonMasterAddress
    );

    return router.getSwapJettonToTonTxParams({
      ...commonParams,
      proxyTon,
      offerJettonAddress: simulation.offerAddress,
    });
  }

  return router.getSwapJettonToJettonTxParams({
    ...commonParams,
    offerJettonAddress: simulation.offerAddress,
    askJettonAddress: simulation.askAddress,
  });
}

The three branches exist because the native coin is not a jetton. STON.fi uses a compatible pTON contract when the route begins or ends with the native asset. A jetton-to-jetton swap does not require that parameter.

dexFactory() also protects the integration from a broader compatibility problem. New Router and pool types do not always expose identical contract behavior. Selecting a generic or hardcoded class may compile while still producing a transaction that fails for a specific route.

Send the generated message through TON Connect

The SDK returns transaction parameters containing three values your wallet request needs:

to, the destination contract address
value, the native amount attached for execution and gas
body, the serialized contract payload

Convert the body to a base64 BoC and send it through TON Connect:

type SendSwapParams = {
  simulation: SwapSimulation;
  fromAsset: SwapAsset;
  toAsset: SwapAsset;
  userAddress: string;
  rpcEndpoint: string;
  tonConnectUI: {
    sendTransaction: (request: {
      validUntil: number;
      network?: string;
      messages: Array<{
        address: string;
        amount: string;
        payload?: string;
      }>;
    }) => Promise<{ boc: string }>;
  };
};

export async function sendStonSwap({
  simulation,
  fromAsset,
  toAsset,
  userAddress,
  rpcEndpoint,
  tonConnectUI,
}: SendSwapParams) {
  const txParams = await buildStonSwapMessage({
    simulation,
    fromAsset,
    toAsset,
    userAddress,
    rpcEndpoint,
  });

  const payload = txParams.body
    ?.toBoc()
    .toString("base64");

  if (!payload) {
    throw new Error("The SDK did not create a transaction payload");
  }

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

  return result.boc;
}

validUntil must be a Unix timestamp in seconds. Adding 300 gives the user five minutes to review the wallet request. Passing Date.now() + 300000 would produce milliseconds instead of seconds and should be avoided.

The network value "-239" identifies TON mainnet. Setting the network explicitly helps prevent a mainnet transaction from being submitted through a wallet connected to another network.

A resolved sendTransaction() call means the wallet accepted and broadcast the signed external message. It does not prove that every subsequent smart contract message completed successfully. Save the returned BoC or another correlation identifier and use a blockchain indexer, explorer service, or backend reconciliation process to determine the final result.

Production checks that prevent expensive mistakes

A demo can stop after opening the wallet. A production integration needs stronger validation, state management, and transaction tracking.

Invalidate stale simulations. Clear the simulation whenever the amount, token pair, wallet, or slippage setting changes. Consider requesting a fresh simulation immediately before opening the wallet.

Keep decimal handling asset-specific. Read decimals from verified asset metadata and use integer or string arithmetic. Do not convert large blockchain-unit values through JavaScript floating-point numbers.

Do not hardcode Router and pTON addresses. Use simulation.router, dexFactory(), and the Router's ptonMasterAddress.

Keep the network consistent. The STON.fi API route, RPC endpoint, connected wallet, and transaction request must all refer to mainnet for the production DEX flow.

Validate the wallet request. Before calling TON Connect, verify that the destination, attached amount, and payload came from the current SDK result rather than from editable form data.

Distinguish rejection from execution failure. A user can close the wallet prompt, a request can expire, an RPC call can fail, or the on-chain route can fail after broadcasting. These outcomes need different interface messages.

Protect infrastructure credentials. Do not expose a privileged RPC key in a public frontend bundle. Use a restricted browser-safe endpoint or proxy sensitive infrastructure through your backend.

Test the complete route matrix. Exercise Gram-to-jetton, jetton-to-Gram, and jetton-to-jetton swaps. Also test assets with different decimals, small balances, insufficient gas, stale simulations, wallet rejection, and invalid token pairs.

The most useful first production exercise is a minimal swap with a limited amount. Log the simulation response, selected Router type, generated destination, attached value, returned BoC, and final on-chain result. Once that lifecycle is reliable, connect it to the rest of your application rather than debugging the complete product and swap flow at the same time.

Frequently Asked Questions

Does the STON.fi TypeScript SDK perform the swap by itself?

No. The SDK creates contract wrappers and transaction parameters, but it does not sign on behalf of the wallet holder. Your application passes the generated destination, amount, and payload to TON Connect. The connected wallet displays the request, receives authorization from its owner, signs it, and broadcasts it to TON.

Why does the application need to simulate the swap first?

Simulation returns more than an output estimate. It supplies the minimum protected output, asset addresses, and Router metadata needed to build the correct transaction. Without a current simulation, the application may use an outdated price, an incompatible contract, or a minimum output that no longer reflects current pool conditions.

Can I hardcode the STON.fi Router address?

You technically can for a tightly controlled contract integration, but it is not the recommended production pattern. STON.fi routes can use different Router versions and types. Using simulation.router with dexFactory() lets the API select the contracts compatible with the current route and reduces maintenance when the protocol introduces new contract implementations.

Should I use `toNano()` for every swap amount?

No. toNano() assumes nine decimal places. That is correct for the native coin and many jettons, but not for every asset. Read the asset's decimals from metadata and convert the displayed value into integer units accordingly. Incorrect precision can make the submitted amount much larger or smaller than the amount shown in your interface.

How should slippage be handled in the interface?

Treat slippage as a visible product setting rather than a hidden constant. Explain that it affects minAskUnits, validate the permitted range, and request a new simulation whenever it changes. Extremely loose tolerance can expose the swap to an unexpectedly poor result, while extremely tight tolerance can cause execution to fail as pool conditions move.

Can I test the same API-driven swap flow on TON testnet?

Not directly with production routing data. The current STON.fi REST API workflow described in the v2 documentation serves mainnet routes. Combining its simulation result with a testnet RPC endpoint or testnet wallet creates a network mismatch. Separate unit tests and message-building tests from small, carefully reviewed mainnet integration tests.

Does a successful TON Connect response mean the swap finished?

No. The response confirms that the wallet created and broadcast the signed external message. TON processes smart contract messages asynchronously, so the application should still verify the resulting on-chain activity. Store the returned BoC or another tracking identifier and update the interface only after your monitoring layer determines the final outcome.

What should I verify before enabling STON.fi swaps for real users?

Verify token addresses and decimals, all three swap directions, Router selection, pTON compatibility, quote invalidation, mainnet configuration, wallet rejection, request expiration, insufficient gas, and final transaction tracking. Start with limited values and review the complete message lifecycle before allowing larger transactions or connecting swaps to automated product actions.

Sources and Further Reading

STON.fi SDK overview - installation, SDK versions, and available DEX capabilities
STON.fi Swap v2 guide - API-driven Router selection and the mainnet-first transaction flow
STON.fi Swap Quickstart - complete React example using the API, SDK, and TON Connect
STON.fi SDK GitHub repository - official TypeScript source code and Next.js demonstration application
STON.fi SDK changelog - Router types, dexFactory(), contract migrations, and decimal-aware utilities
STON.fi API GitHub repository - official TypeScript client for assets, pools, simulations, and Router information
TON Connect transaction guide - current request format, Unix expiration time, network selection, and returned BoC
TON Connect overview - wallet connection architecture and private-key separation
STON.fi integration article - official overview of adding swaps to a React application

How Do You Connect a TON Wallet to STON.fi?

Ivan “Crypto Vazima” Zimanov — Sat, 11 Jul 2026 09:16:31 +0000

Build a React wallet connection with TON Connect, read the connected account, and pass STON.fi transactions to the wallet for approval.

Connecting a TON wallet to STON.fi does not require importing a private key or giving an application control over the wallet. The connection is created through TON Connect, the standard wallet communication protocol for TON.

For someone using the official STON.fi interface, the process is simple: open the application, select Connect Wallet, choose a compatible wallet, and approve the connection. For developers, the same process can be integrated into a React application with @tonconnect/ui-react.

Once connected, the application can read the public wallet address and request transactions. The wallet still holds the private keys and asks the owner to approve every transaction.

This tutorial builds that connection and then demonstrates how it fits into a STON.fi swap integration.

What you will build

By the end of the tutorial, the application will be able to:

Display a TON Connect wallet selector.
Restore an existing wallet session after a page reload.
Read the connected wallet address and network.
Reject a testnet wallet when the application targets mainnet.
Request STON.fi swap data through the official API.
Build a STON.fi transaction with the SDK.
Send the transaction to the connected wallet for approval.

The integration uses three separate layers:

Layer	Package	Responsibility
Wallet connection	`@tonconnect/ui-react`	Opens the wallet selector and manages the session
STON.fi data	`@ston-fi/api`	Retrieves assets, pools, simulations, and routing data
STON.fi transactions	`@ston-fi/sdk`	Builds the transaction parameters sent to the wallet

The wallet connection and the DEX integration are related, but they serve different purposes. TON Connect communicates with the wallet. The STON.fi API and SDK prepare the operation that the wallet will sign.

What connecting a wallet actually authorizes

A wallet connection is not a token approval and does not move funds.

After the user approves the connection, the application normally receives information such as:

The selected TON account address.
The network used by the account.
The wallet application name.
Supported wallet features.
A session that can be restored later.

The application may then prepare a transaction and send a signing request. The wallet displays that request separately, allowing the user to review and reject it.

A secure integration should therefore treat these as two distinct events:

Connect: establish a communication session and obtain the public address.
Transact: ask the wallet to sign and send a specific blockchain message.

Never ask users to enter a seed phrase or private key. A normal TON Connect integration does not need either one.

Create the React project

This tutorial uses React, TypeScript, and Vite.

Create the project:

npm create vite@latest ston-wallet-demo -- --template react-ts
cd ston-wallet-demo
npm install

Install TON Connect and the STON.fi packages:

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

Start the development server:

npm run dev

The basic wallet connection only requires @tonconnect/ui-react. The STON.fi packages become necessary when the application starts loading DEX information and building transactions.

Some browser builds may also require a Buffer polyfill when serializing a transaction body into a base64 Bag of Cells, or BOC. Add one only when your build reports that Buffer is unavailable:

npm install --save-dev vite-plugin-node-polyfills

Then update vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { nodePolyfills } from "vite-plugin-node-polyfills";

export default defineConfig({
  plugins: [
    react(),
    nodePolyfills({
      include: ["buffer"],
      globals: {
        Buffer: true,
        global: true,
        process: false,
      },
    }),
  ],
});

Publish the TON Connect manifest

Before a wallet connects, it needs to know which application is requesting the connection. TON Connect provides this information through tonconnect-manifest.json.

Create the following file:

public/tonconnect-manifest.json

Add your application metadata:

{
  "url": "https://your-domain.example",
  "name": "STON.fi Wallet Demo",
  "iconUrl": "https://your-domain.example/icon-180.png",
  "termsOfUseUrl": "https://your-domain.example/terms",
  "privacyPolicyUrl": "https://your-domain.example/privacy"
}

Only url, name, and iconUrl are required. The legal document fields are optional.

For production, the manifest must be available through a public HTTPS URL. It cannot require authentication or sit behind a browser challenge. The icon should be a publicly accessible PNG or ICO file, with a 180 by 180 pixel PNG being the recommended option. SVG icons are not supported by the documented manifest flow.

You should be able to open the final URL directly:

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

A desktop extension may sometimes work with a local manifest, but a mobile wallet cannot reliably fetch a file from your computer's localhost. Use a public preview deployment or an HTTPS development tunnel when testing the QR flow on a phone.

Mount the TON Connect provider

The TonConnectUIProvider makes the TON Connect client available to every component below it.

Update src/main.tsx:

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

const manifestUrl =
  import.meta.env.VITE_TONCONNECT_MANIFEST_URL ??
  `${window.location.origin}/tonconnect-manifest.json`;

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <TonConnectUIProvider manifestUrl={manifestUrl}>
      <App />
    </TonConnectUIProvider>
  </React.StrictMode>,
);

For production, define the manifest URL explicitly:

VITE_TONCONNECT_MANIFEST_URL=https://your-domain.example/tonconnect-manifest.json

Using an environment variable makes accidental domain mismatches less likely when the application has development, staging, and production deployments.

Add the wallet connection interface

TON Connect provides a ready-made button that opens the wallet selection modal and reflects the current connection state.

Replace src/App.tsx with:

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

export default function App() {
  const wallet = useTonWallet();
  const address = useTonAddress();
  const restored = useIsConnectionRestored();
  const [tonConnectUI] = useTonConnectUI();

  if (!restored) {
    return <main>Restoring wallet session...</main>;
  }

  return (
    <main>
      <header>
        <h1>STON.fi Wallet Integration</h1>
        <TonConnectButton />
      </header>

      {!wallet ? (
        <section>
          <p>Connect a TON wallet to continue.</p>

          <button type="button" onClick={() => tonConnectUI.openModal()}>
            Open wallet selector
          </button>
        </section>
      ) : (
        <section>
          <h2>Connected wallet</h2>

          <dl>
            <dt>Address</dt>
            <dd>{address}</dd>

            <dt>Wallet</dt>
            <dd>{wallet.device.appName}</dd>

            <dt>Network</dt>
            <dd>
              {wallet.account.chain === "-239" ? "Mainnet" : "Testnet"}
            </dd>
          </dl>
        </section>
      )}
    </main>
  );
}

useTonAddress() returns an empty string while disconnected and a user-friendly TON address after connection. useTonWallet() returns the full wallet object, while useIsConnectionRestored() tells the application whether TON Connect has finished checking for a previously saved session.

The restoration check is important. Before restoration finishes, a missing wallet does not necessarily mean that the user is disconnected. Redirecting or disabling features too early can create a visible flash of incorrect state.

Validate the network before using STON.fi

TON mainnet and testnet use different chain identifiers:

Mainnet: -239
Testnet: -3

The current network is available through:

wallet.account.chain

A mainnet STON.fi integration should block the action when the connected account is not on mainnet:

function requireMainnet(chain: string): void {
  if (chain !== "-239") {
    throw new Error("Connect a TON mainnet wallet before continuing.");
  }
}

You should also include the expected network in every transaction request. The wallet can then reject a transaction when the connected account is on a different network. TON Connect does not provide a conventional runtime network-switch event, so separate deployments are preferable when an application needs both mainnet and testnet experiences.

Connect the wallet state to the STON.fi SDK

At this point, the application is connected to a wallet, but it has not interacted with STON.fi.

A production STON.fi v2 swap should be API-driven:

Simulate the requested swap.
Receive the router metadata from the simulation.
Create the appropriate router through dexFactory().
Build transaction parameters for the selected swap type.
Pass those parameters to TON Connect.

This avoids hardcoding a router that may no longer be appropriate for the requested operation. STON.fi's current v2 documentation recommends using the router information returned by the API simulation.

The following helper prepares a TON-to-jetton transaction:

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

const tonClient = new Client({
  endpoint: import.meta.env.VITE_TON_RPC_URL,
});

const stonApi = new StonApiClient();

type BuildSwapInput = {
  walletAddress: string;
  askJettonAddress: string;
  offerUnits: string;
};

export async function buildTonToJettonSwap({
  walletAddress,
  askJettonAddress,
  offerUnits,
}: BuildSwapInput) {
  const simulation = await stonApi.simulateSwap({
    offerAddress: "ton",
    askAddress: askJettonAddress,
    offerUnits,
    slippageTolerance: "0.01",
  });

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

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

  const proxyTon = contracts.pTON.create(
    routerInfo.ptonMasterAddress,
  );

  return router.getSwapTonToJettonTxParams({
    userWalletAddress: walletAddress,
    offerAmount: simulation.offerUnits,
    minAskAmount: simulation.minAskUnits,
    askJettonAddress: simulation.askAddress,
    proxyTon,
  });
}

offerUnits must use blockchain units, not a human-readable decimal string. Token precision is not universal. Some TON assets use nine decimal places, while others use a different value, so retrieve the asset metadata and convert the entered amount according to that asset's decimals. Do not apply nine decimals to every token.

The simulation also provides minAskUnits. Reusing it in the transaction ensures that the signed operation reflects the minimum output calculated for the selected slippage tolerance.

Send the STON.fi transaction through TON Connect

The STON.fi SDK returns transaction parameters containing the destination contract, attached value, and serialized message body.

Convert them into the shape expected by TON Connect:

type StonTransactionParams = {
  to: {
    toString(): string;
  };
  value: {
    toString(): string;
  };
  body?: {
    toBoc(): {
      toString(encoding: "base64"): string;
    };
  };
};

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

You can now use it inside a React component:

import { useState } from "react";
import {
  useTonAddress,
  useTonConnectUI,
  useTonWallet,
} from "@tonconnect/ui-react";
import { buildTonToJettonSwap } from "./stonSwap";

type SwapButtonProps = {
  askJettonAddress: string;
  offerUnits: string;
};

export function SwapButton({
  askJettonAddress,
  offerUnits,
}: SwapButtonProps) {
  const wallet = useTonWallet();
  const walletAddress = useTonAddress();
  const [tonConnectUI] = useTonConnectUI();
  const [pending, setPending] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleSwap = async () => {
    setError(null);

    if (!wallet || !walletAddress) {
      await tonConnectUI.openModal();
      return;
    }

    if (wallet.account.chain !== "-239") {
      setError("A TON mainnet wallet is required.");
      return;
    }

    try {
      setPending(true);

      const txParams = await buildTonToJettonSwap({
        walletAddress,
        askJettonAddress,
        offerUnits,
      });

      await tonConnectUI.sendTransaction(
        toTonConnectRequest(txParams),
      );
    } catch (unknownError) {
      const message =
        unknownError instanceof Error
          ? unknownError.message
          : "The transaction could not be prepared or sent.";

      setError(message);
    } finally {
      setPending(false);
    }
  };

  return (
    <div>
      <button type="button" onClick={handleSwap} disabled={pending}>
        {pending ? "Preparing transaction..." : "Review swap in wallet"}
      </button>

      {error && <p role="alert">{error}</p>}
    </div>
  );
}

Calling sendTransaction() does not silently execute the swap. It opens the wallet approval flow. The wallet owner can inspect and reject the request before it is broadcast. STON.fi documents the same boundary: the SDK generates txParams, and TON Connect sends the resulting message to the wallet.

Production checks and common failures

Before enabling real swaps, add a review screen that displays:

The input asset and amount.
The output asset.
The expected output.
The minimum output.
The selected slippage tolerance.
The connected address and network.
Any estimated network or protocol costs available to the interface.

Do not prepare a quote once and reuse it indefinitely. Market conditions and pool reserves can change. Request a fresh simulation shortly before building the transaction.

Common integration problems include:

Problem	Likely cause	What to check
Wallet modal opens but connection fails	Manifest unavailable	Public HTTPS URL, valid JSON, icon URL, and unrestricted access
Mobile wallet cannot load the app identity	Manifest points to localhost	Deploy the manifest or use a public HTTPS development URL
UI briefly says disconnected	Session restoration is unfinished	Wait for `useIsConnectionRestored()`
Wallet rejects the transaction network	Mainnet and testnet mismatch	Check `wallet.account.chain` and set `network: "-239"`
Browser reports `Buffer is not defined`	BOC serialization lacks a polyfill	Add a targeted Buffer polyfill
Quote works but transaction fails	Quote is stale, balance changed, or TON for fees is insufficient	Simulate again and recheck balances
Swap uses an unexpected router	Contract address was hardcoded	Use the router returned by the latest STON.fi simulation

STON.fi's REST API currently serves the documented production workflow from mainnet. The v2 testnet path requires manually configured contracts and liquidity, so it should not be treated as a full mirror of the mainnet API-driven experience.

A practical final test is to connect a separate wallet with a small balance, simulate a modest transaction, review every wallet field, and confirm the resulting operation on-chain before expanding the integration.

Frequently Asked Questions

Can I connect a wallet directly to the official STON.fi application?

Yes. Open the official STON.fi application, select Connect Wallet, choose a compatible TON wallet, and approve the connection. The developer steps in this tutorial are for applications that want to integrate TON Connect and STON.fi functionality into their own interface.

Does connecting a wallet give STON.fi access to the private key?

No. TON Connect establishes a communication session with the wallet, but the private key remains inside the wallet application. A dApp can request a transaction, but the wallet owner must review and approve that request separately.

Which TON Connect package should a React application use?

Use @tonconnect/ui-react for React and Next.js applications. It provides the provider, connection button, modal, and React hooks. Non-React browser applications can use @tonconnect/ui, while headless or highly customized integrations can use @tonconnect/sdk.

Why does the TON Connect manifest need a public HTTPS URL?

The wallet fetches the manifest independently to identify the requesting application. A local file, protected endpoint, authentication wall, or browser challenge can prevent the wallet from reading it. HTTPS also gives the wallet a stable origin for displaying the application identity.

How can the application tell whether a wallet uses mainnet?

Read wallet.account.chain. TON mainnet uses "-239" and testnet uses "-3". For a mainnet STON.fi application, validate the value after connection and include network: "-239" in transaction requests.

Is connecting a wallet the same as authenticating a user?

Not necessarily. A public wallet address can identify a connected account, but an application that needs secure backend authentication should request and verify ton_proof. A connection alone should not be treated as proof that an HTTP request came from the wallet owner.

Can STON.fi v2 swaps be fully tested through the public API on testnet?

Not through the same production API-driven path. STON.fi documents its REST API as mainnet-focused. Testnet swaps require manually selected contracts, test assets, and funded liquidity pools. Use that environment for controlled development rather than assuming it matches mainnet liquidity or routing.

What should be checked before requesting a STON.fi swap signature?

Check the connected network, wallet balance, asset addresses, token decimals, expected output, minimum received, slippage tolerance, transaction destination, and attached TON value. Build the transaction from a fresh STON.fi simulation and let the wallet display the final approval request.

DEV Community: Ivan “Crypto Vazima” Zimanov

How to Track STON.fi Swap Status with an Indexer

Why one transaction hash is not enough

What an indexer adds to swap tracking

Build a status model for your application

Start with the message returned by TON Connect

Follow the transaction into its trace

Verify the STON.fi result, not only TON execution

What changes when the swap uses Omniston?

Polling or streaming?

A practical STON.fi tracking checklist

Frequently Asked Questions

What is an indexer in TON?

Why can a STON.fi swap involve multiple transactions?

Does finding the wallet transaction mean the swap succeeded?

What should I store after sending the swap?

Should I poll an indexer continuously?

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

How should I track an Omniston swap?

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

Sources and Further Reading

How to Decode a STON.fi Swap Transaction

Start with the trace, not a single transaction

What should you collect before decoding?

Which accounts matter in a STON.fi swap?

Message op codes turn the trace into a readable story

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

1. Your wallet starts the operation

2. Your offer jetton wallet moves Token A

3. The STON.fi Router recognizes the swap request

4. The Pool executes the exchange

5. The Router settles the output

6. Your destination jetton wallet receives Token B

How do you prove the swap actually succeeded?

Do not confuse attached TON with swap value or total fees

Use the STON.fi action tree and raw trace together

A compact STON.fi swap decoding checklist

Frequently Asked Questions

Does a STON.fi swap have one transaction hash?

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

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

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

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

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

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

Sources and Further Reading

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

What are you actually sending?

Set up TON Connect first

Simulate before building the transaction

Build the STON.fi swap message

TON to jetton

Jetton to TON

Jetton to jetton

Send the transaction through the TON wallet

Put the full handler together

What happens after the wallet approves?

Common mistakes when sending STON.fi swaps

Frequently Asked Questions

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

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

Why should I simulate the swap before sending it?

Should validUntil use milliseconds or seconds?

What does network: "-239" mean?

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

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

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

Sources and Further Reading

How to Connect TON Connect to a STON.fi dApp

What TON Connect actually does in a STON.fi dApp

Set up the React dependencies

Create the TON Connect manifest first

Add TON Connect to the React component tree

Read the connected wallet correctly

Connect the wallet state to a STON.fi swap

What happens when sendTransaction() runs?

Avoid the integration mistakes that cause most problems

A practical STON.fi integration checklist

Frequently Asked Questions

Does STON.fi require TON Connect?

Should `validUntil` use milliseconds or seconds?

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

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

What happens when `sendTransaction()` runs?

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

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

Is `/v1/swap/simulate` a real swap?

What does `units` mean in the STON.fi quote request?

Can I use `api.ston.fi` to request testnet swap quotes?

Do I need `@ston-fi/api` to use `@ston-fi/sdk`?

Why should I install `@ton/ton`?

Why does Vite report that `Buffer` is undefined?