DEV Community: Ivan “Crypto Vazima” Zimanov

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 Install and Configure the STON.fi SDK

Key takeaways

What the STON.fi SDK actually provides

Choose the right project setup

Create the project and install the packages

1. Create the application

2. Install the STON.fi and TON packages

Configure TypeScript and the browser runtime

Handling browser polyfills

Add environment variables

Configure the blockchain and STON.fi clients

Discover the Router dynamically

Work with integer blockchain units

Add TON Connect for wallet approval

Verify the installation before building a swap

Common configuration mistakes and production checks

Practical takeaway

Frequently Asked Questions

Is the STON.fi SDK only for TypeScript?

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

Why should I install @ton/ton?

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

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

Why does Vite report that Buffer is undefined?

Does the SDK connect to the user's wallet?

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

Sources and Further Reading

How to Integrate STON.fi Swaps with the TypeScript SDK

The integration has four separate layers

Set up the TypeScript project

Connect the wallet without handling private keys

Treat token amounts as integer units

Simulate the swap before building anything

Let dexFactory() select the Router

Send the generated message through TON Connect

Production checks that prevent expensive mistakes

Frequently Asked Questions

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

Why does the application need to simulate the swap first?

Can I hardcode the STON.fi Router address?

Should I use toNano() for every swap amount?

How should slippage be handled in the interface?

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

Does a successful TON Connect response mean the swap finished?

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

Sources and Further Reading

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

What you will build

What connecting a wallet actually authorizes

Create the React project

Publish the TON Connect manifest

Mount the TON Connect provider

Add the wallet connection interface

Validate the network before using STON.fi

Connect the wallet state to the STON.fi SDK

Send the STON.fi transaction through TON Connect

Production checks and common failures

Frequently Asked Questions

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

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

Which TON Connect package should a React application use?

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

How can the application tell whether a wallet uses mainnet?

Is connecting a wallet the same as authenticating a user?

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

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

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?

Let `dexFactory()` select the Router

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