Current version: 0.6, released Aug 2023

Documentation for older versions of the STON.fi SDK.

Available Versions

• Introduced modular structure (dex, farm, transaction-sending)

• Improved error handling

• Better TypeScript support

• Original SDK implementation

• Basic swap and liquidity operations

• Custom router revision support

Migration

These versions are deprecated. We strongly recommend upgrading to the latest version:

1. Review the

2. Update to

Why Upgrade?

• Better Performance: Newer versions have optimized gas usage

• More Features: Single-sided liquidity, vault operations

• Active Support: Only latest versions receive updates

Archived Documentation

These docs are maintained for reference only. For new integrations, always use the latest SDK version.

Security is fundamental to STON.fi. Below are the public audits, continuous monitoring resources, and our active bug bounty program for responsible disclosure.

Audits and Reviews

• Trail of Bits — STON.fi TON AMM DEX v2 Security Review (Jan 2025)

  • PDF:

• Omniston escrow contracts audit — no critical issues found

  • Blog post:

  • Summary: Initial audit of Omniston’s escrow contracts completed with no critical issues found (per the STON.fi blog; reviewed by the TonTech team).

• Continuous monitoring — CertiK Skynet

  • Project page:

Bug Bounty

• Program: STON.fi DEX Smart Contracts v2 on HackenProof

  • Program page:

  • Notes: Public, severity-based rewards. Please submit findings via HackenProof following their responsible disclosure process and scope.

If you discover a potential vulnerability, please report it through the HackenProof program above. Avoid sharing sensitive details publicly until the issue is triaged and resolved.

Welcome to the STON.fi Quickstart Guides section. These guides provide step-by-step instructions for implementing STON.fi features in your applications with minimal effort.

Each guide is designed to be beginner-friendly and focuses on practical implementation. The guides include complete code examples that you can use as a starting point for your own projects.

Available Guides

Currently, we offer the following quickstart guides:

The remaining sections of the documentation will demonstrate specific examples of the DEX usage:

What Is STON.fi?

STON.fi is the leading decentralized automated market maker (AMM) exchange on the TON blockchain, employing the Constant Product Market Maker algorithm. The web-based app (app.ston.fi) provides a visual interface for interacting with smart contracts deployed on TON.

Key Features

• Fully Decentralized - Non-custodial exchange with funds held in permissionless smart contracts

• Near-zero fees - Minimal transaction costs leveraging TON's efficiency

• Low slippage - Deep liquidity pools ensure optimal trading rates

🚀 Quick Start for Developers

Embed a swap feature and earn fees - in minutes

The is a ready-to-use swap interface for your app or website. Simply embed our lightweight script and get full swap functionality instantly — while you earn fees from every swap. Start with the default config or customize colors and token lists to match your brand.

Whether you're building on STON.fi or integrating our protocol, here's where to begin. If you are new to TON development or just want the fastest integration path, start with our for a drop-in swap experience, then explore the guides below.

Getting Started Guides

• - Integrate token swaps into your dApp

• - Use our cross-chain aggregator for best rates

• - Add and manage liquidity pools

Developer Resources

• - Cross-chain swaps and aggregation

• - TypeScript/JavaScript SDK for easy integration

• - Direct contract interaction

STON.fi Products

STON.fi builds user‑centric DeFi on TON. Our main products are the STON.fi DEX and Omniston aggregator, supported by SDKs, APIs, and a production web app.

What Is the STON.fi DEX?

A permissionless automated market maker (AMM) enabling token swaps and liquidity provision on TON.

• Constant Product (x*y=k) pools with deep liquidity

• Non‑custodial contracts and time‑locked router upgrades

• Liquidity provision and yield farming

What Is Omniston?

Omniston is STON.fi’s aggregation layer that finds best rates by combining on‑chain liquidity sources and RFQ resolvers.

• Optimal routing across pools and resolvers

• Referral fee support and advanced features

• SDKs for seamless integration

📚 Documentation Structure

This documentation provides:

• Technical specifications for protocol integration — ,

• Code examples for common operations — ,

• API references for all contracts and endpoints — ,

🔗 Quick Links

Main Resources:

• Website:

• Web App:

• User Guide:

Community:

• X (Twitter):

• Telegram:

• Discord:

What Is an AMM?

An Automated Market Maker (AMM) is a decentralized trading protocol that:

• Uses liquidity pools instead of order books

• Provides instant trades without counterparties

• Allows anyone to become a liquidity provider

Why Build on STON.fi?

For Developers:

• Comprehensive SDKs and documentation

• Battle-tested smart contracts

• Active developer community

• Direct team support

For Users:

• Largest liquidity on TON

• Best rates through aggregation

• Seamless Telegram integration

• Trusted by millions

Ready to start building? Jump to our or explore the !

Provide liquidity for a pool

Jetton/Jetton pool deposit

To execute the transaction, you need to send a transaction with these parameters to the blockchain. This code will be different based on the wallet you are using to send the tx from, so please check our with examples for different libraries.

Refund tokens that were sent to LP account but weren't added to a liquidity pool yet

import { TonClient } from "@ton/ton";
import { DEX } from "@ston-fi/sdk";

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

const router = client.open(new DEX.v1.Router());

const pool = client.open(await router.getPool({
  token0: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  token1: "EQBX6K9aXVl3nXINCyPPL86C4ONVmQ8vK360u6dykFKXpHCa", // GEMSTON
}));

const lpAccount = client.open(await pool.getLpAccount({
  ownerAddress: "", // ! replace with your address
}));

const txParams = await lpAccount.getRefundTxParams({
  queryId: 12345,
});

To execute the transaction, you need to send a transaction with these parameters to the blockchain. This code will be different based on the wallet you are using to send the tx from, so please check our doc section about transaction sending guide with examples for different libraries.

Current Model

• Per‑pool configurable: Trading fees are set per liquidity pool.

Unstake funds from Farm NFT

To execute the transaction, you need to send a transaction with these parameters to the blockchain. This code will be different based on the wallet you are using to send the tx from, so please check our with examples for different libraries.

The remaining sections of the documentation will demonstrate specific examples of the DEX usage:

Destroy of the Farm NFT is a transfer of the Farm NFT from the user wallet to the zero address.

To execute the transaction, you need to send a transaction with these parameters to the blockchain. This code will be different based on the wallet you are using to send the tx from, so please check our with examples for different libraries.

The remaining sections of the documentation will demonstrate specific examples of the SDK usage:

Refund tokens deposited on liquidity pool account but not added to a liquidity pool yet.

import TonWeb from 'tonweb';

import { Router, ROUTER_REVISION, ROUTER_REVISION_ADDRESS } from '@ston-fi/sdk';

/**
 * This example shows how to refund liquidity from the your lp-account
 */
(async () => {
  const WALLET_ADDRESS = ''; // ! replace with your address
  const JETTON0 = 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO'; // STON
  const JETTON1 = 'EQBynBO23ywHy_CgarY9NK9FTz0yDsG82PtcbSTQgGoXwiuA'; // jUSDT

  const provider = new TonWeb.HttpProvider();

  const router = new Router(provider, {
    revision: ROUTER_REVISION.V1,
    address: ROUTER_REVISION_ADDRESS.V1,
  });

  const pool = await router.getPool({
    jettonAddresses: [JETTON0, JETTON1],
  });

  if (!pool) {
    throw Error(`Pool for ${JETTON0}/${JETTON1} not found`);
  }

  const lpAccount = await pool.getLpAccount({ ownerAddress: WALLET_ADDRESS });

  if (!lpAccount) {
    throw Error(
      `LpAccount for ${WALLET_ADDRESS} at ${JETTON0}/${JETTON1} pool not found`,
    );
  }

  // transaction to refund all tokens from JETTON0/JETTON1 lp-account contract
  const refundTxParams = await lpAccount.buildRefundTxParams({
    // query id to identify your transaction in the blockchain (optional)
    queryId: 12345,
  });

  // to execute the transaction you need to send transaction to the blockchain
  // (replace with your wallet implementation, logging is used for demonstration purposes)
  console.log({
    to: refundTxParams.to,
    amount: refundTxParams.gasAmount,
    payload: refundTxParams.payload,
  });
})();

Burn all liquidity tokens to free liquidity from a pool

import { TonClient } from "@ton/ton";
import { DEX } from "@ston-fi/sdk";

const USER_WALLET_ADDRESS = ""; // ! replace with your address

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

const router = client.open(new DEX.v1.Router());

const pool = client.open(await router.getPool({
  token0: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  token1: "EQBX6K9aXVl3nXINCyPPL86C4ONVmQ8vK360u6dykFKXpHCa", // GEMSTON
}));

const lpTokenWallet = client.open(await pool.getJettonWallet({
  ownerAddress: USER_WALLET_ADDRESS,
}));

const lpTokenWalletData = await lpTokenWallet.getWalletData();

const txParams = await pool.getBurnTxParams({
  amount: lpTokenWalletData.balance,
  responseAddress: USER_WALLET_ADDRESS,
  queryId: 12345,
});

To execute the transaction, you need to send a transaction with these parameters to the blockchain. This code will be different based on the wallet you are using to send the tx from, so please check our doc section about transaction sending guide with examples for different libraries.

Claim rewards from Farm NFT

import { TonClient } from "@ton/ton";
import { FARM } from "@ston-fi/sdk";

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

const farmNft = client.open(FARM.v3.NftItem.create(
  "EQA18JnBVNZZ8Wz-Kn6Mc5cy9pv798Pn8tfScjKw9NLPK3U2", // Farm v3 nft address
));

// Unstake all staked funds from Farm NFT back to the owner's wallet
const txParams = await farmNft.getClaimRewardsTxParams({
  queryId: 12345,
});

To execute the transaction, you need to send a transaction with these parameters to the blockchain. This code will be different based on the wallet you are using to send the tx from, so please check our doc section about transaction sending guide with examples for different libraries.

The STON.fi DEX (Decentralized Exchange) is a fully decentralized automated market maker (AMM) protocol on the TON blockchain.

Overview

STON.fi DEX implements the Constant Product Market Maker algorithm, providing:

• Permissionless token swaps

• Liquidity provision

• Yield farming opportunities

• Non-custodial trading

Key Components

Technical overview of the DEX smart contract system including Router, Pool, Account, and Wallet contracts.

TypeScript/JavaScript SDK for integrating STON.fi DEX functionality into your applications.

Direct smart contract interaction documentation for advanced integrations.

HTTP API for querying DEX data, simulating operations, and retrieving statistics.

Yield farming functionality for liquidity providers to earn additional rewards.

Version Support

The DEX currently supports two major versions:

• v2 (Latest) - Enhanced features including single-sided liquidity provision

• v1 - Original implementation, still supported for backward compatibility

Choose the appropriate version based on your integration requirements.

Yield farming functionality for STON.fi liquidity providers.

Overview

STON.fi farming allows LP token holders to earn additional rewards by staking their tokens in farming pools. This provides an extra incentive for liquidity providers beyond trading fees.

How It Works

1. Provide Liquidity: Add tokens to a DEX pool to receive LP tokens

2. Stake LP Tokens: Deposit LP tokens into a farming pool

3. Earn Rewards: Accumulate farming rewards over time

Key Features

• Multiple farming pools with different reward rates

• Flexible staking and unstaking

• Real-time reward accumulation

SDK Integration

The farming functionality is integrated into the STON.fi SDK:

Available Operations

This is a standard Jetton token wallet for holding liquidity tokens. Only specific modifications for this implementation will be described.

User message handlers

burn (0x595f07bc)

Burn an amount of liquidity tokens.

TL-B

Message body

Outgoing messages

Sends a message with burn_notification op code to the router contract with the amount of token burnt.

Important: This API reference documents low-level smart contract methods and opcodes. For production applications, we strongly recommend using the official SDK + TonConnect instead of manually compiling BOCs and sending transactions. The SDK provides better developer experience, handles edge cases, and receives official support. Custom BOC compilation should only be used for specialized/advanced use cases.

Overview

The section contains separate documents for each smart contract used in AMM:

Source code of all smart contracts can be found in this

Note: Protocol fees in DEX v1 are collected in ASK jetton.

Referral Fees

DEX v1 pays the referrer share of a swap fee directly inside the swap transaction. The rate is fixed at 0.1 % and the amount is transferred to the provided referrer_address automatically. See the (note: although the guide is Omniston-centric, the referenced paragraph specifically covers DEX V1 referral fees).

You can monitor referral payouts using the Stats & Vaults REST API:

• GET /v1/stats/fee_accruals – shows all operations that led to fee accrual for the referrer, filterable by period

• GET /v1/stats/fee_withdrawals – lists all fee withdrawals from the referrer's vaults by period

• GET /v1/stats/fees

The full specification is available in the .

Simple swap with referral

Simple swap of one token to another.

Bob is user doing the swap, Alice is referrer, Send is send token, Receive is receive token.

Cross-swap on the same Router

Swap of one token to another using an intermediary token. This method is used if there's no available pool for a pair of tokens but there're pools for each token and some other (the same for both) intermediary token. This type of swap is not limited to 1 intermediary: in practice an arbitrary amount of intermediaries can be used. This type of swap can be combined with cross-swap using multiple Routers.

Bob is user doing the swap, Send is send token, Mid is intermediary token, Receive is receive token.

Cross-swap using multiple Routers

Swap of one token to another using different Routers. This method is used if there's no available pool for a pair of tokens on the same Router but there're pools for each token and some other (the same for both) intermediary token on both Routers. This type of swap is not limited to 1 intermediary: in practice an arbitrary amount of intermediaries can be used. This type of swap can be combined with cross-swap on the same Router.

Bob is user doing the swap, Send is send token, Mid is intermediary token, Receive is receive token.

Refund swap

Refund swap if there's not enough liquidity in the pool or the expected amount of receive tokens is less than expected minimum. Since multi-contract transactions in TON are not atomic it is not possible to fully refund cross swap (on the same router or multiple), in such event the user will receive some intermediate token based on the pool used to route the swap.

Bob is user doing the swap, Send is send token, Receive is receive token.

Token vault is used to store referral fees on a separate contract similar to lp account. This will allow us to decrease tx fees for swaps since users won't have to pay for additional jetton transfer tx.

Vault address is defined by router_address, owner_address and router_token_Wallet_address, so for each token each user can have a dedicated vault contract.

Swap diagram with referral

Bob is user doing the swap, Alice is referrer, Send is send token, Receive is receive token.

Withdraw from vault

Withdraw op can be called by anyone, not only the Vault owner. All excesses are sent to the owner.

Notes:

• the Vault contract is deleted on withdraw in order to not pay storage fees (each deposit sends state init so it will be redeployed as soon as any new deposit occurs)

For broader details on collecting referral fees, see the (note: while the guide is Omniston-centric, the specified section covers DEX V2 referral mechanics thoroughly).

Alongside contracts, we provide REST API to simplify interactions with the STON.fi protocol.

The DEX API provides data from the STON.fi contracts over time and organizes data about pools, jettons, STON.fi protocol as a whole, and more.

Limits

Currently, there are no limits for DEX API use.

API Viewers

You can explore the full schema and try requests via:

SDK

To simplify DEX API integration in your projects, we also have a tiny

API Reference

For a complete list of all available endpoints with brief descriptions, please refer to our .

Referral Fee Endpoints

If you use Omniston referral fees with STON.fi pools, the DEX API exposes several helper endpoints:

• Wallet-level vaults: GET /v1/wallets/{address}/fee_vaults Lists referral fee vaults for STON.fi DEX v2 for a given referrer.

• Fee statistics:

  • GET /v1/stats/fee_accruals

These endpoints only cover STON.fi DEX v1/v2 pools. Omniston-level referral fees for external DEXes such as DeDust and Tonco are not yet available via REST and must be tracked on-chain.

For a full description of how referral fees are calculated and settled across DEX v1, DEX v2, DeDust, and Tonco, see the guide.

Follow us on Twitter

Join our community on Telegram

Join our community on Discord

Join our community on Reddit

Browse STON.fi

The STON.fi SDK provides a high-level TypeScript/JavaScript interface for interacting with the DEX protocol.

Installation

Direct smart contract interaction documentation for the STON.fi DEX protocol.

Important: These docs describe the low-level smart contract architecture, methods, and opcodes. For production applications, we strongly recommend using the + instead of manually compiling BOCs and sending transactions. The SDK provides better developer experience, handles edge cases, and receives official support. Custom BOC compilation should only be used for specialized/advanced use cases.

Step-by-step guides for upgrading between SDK versions.

Available Guides

Liquidity aggregation protocol for optimal swap execution on TON.

Documentation

Ton package uses the sendTransfer method to send a transaction to the blockchain. An example of the usage is on their .

Staking of the LP tokens in Farm

To execute the transaction, you need to send a transaction with these parameters to the blockchain. This code will be different based on the wallet you are using to send the tx from, so please check our with examples for different libraries.

The remaining sections of the documentation will demonstrate specific examples of the DEX usage:

Refund tokens that were sent to LP account but weren't added to a liquidity pool yet

Tonweb package uses the transfer method to send a transaction to the blockchain. An example of the usage is on their .

Free liquidity by buring liquidity pool tokens.

Shared functionality and utilities used across STON.fi products.

Transaction Sending

Common patterns and utilities for sending transactions on TON:

Burn all liquidity tokens to free liquidity from a pool

This is a standard Jetton token wallet for holding liquidity tokens. Only specific modifications for this implementation will be described.

User message handlers

Overview

Omniston is a decentralized liquidity aggregation protocol designed specifically for TON Blockchain. It aggregates liquidity from various sources, including:

• AMM DEXs

What are Resolvers?

Resolvers provide quotes and execute trades for the Omniston aggregation protocol. They compete to offer the best prices for token swaps.

As a result of the SDK get*TxParams methods calls, you will get the object with the following structure

This object describes to what address the transaction should be sent and what amount of TON to pay for the gas. And body contains information for the contract of what action you want to perform.

Now, to actually send the transaction to the blockchain we need to use some king of sendTransaction method provided by a TON SDK you are using in your project. There is an extensive , and everyone has a slightly different syntax for sending transactions. Usually, you can find the information about how to send the tx on each TON SDK docs, but for a few of them, we got examples right here:

STON.fi DEX is a decentralized exchange protocol that enables permissionless token swaps and liquidity provision on the TON blockchain.

Core Features

Example of usage of various get methods of the SDK.

import TonWeb from 'tonweb';

import { Router, ROUTER_REVISION, ROUTER_REVISION_ADDRESS } from '@ston-fi/sdk';

(async () => {
  const OWNER_ADDRESS = '';

  const JETTON0 = 'EQDQoc5M3Bh8eWFephi9bClhevelbZZvWhkqdo80XuY_0qXv';
  const JETTON1 = 'EQC_1YoM8RBixN95lz7odcF3Vrkc_N8Ne7gQi7Abtlet_Efi';

  const provider = new TonWeb.HttpProvider();

  const router = new Router(provider, {
    revision: ROUTER_REVISION.V1,
    address: ROUTER_REVISION_ADDRESS.V1,
  });

  const routerData = await router.getData();

  const {
    isLocked,
    adminAddress,
    tempUpgrade,
    poolCode,
    jettonLpWalletCode,
    lpAccountCode,
  } = routerData;

  const pool = await router.getPool({ jettonAddresses: [JETTON0, JETTON1] });

  if (!pool) {
    throw Error(`Pool for ${JETTON0}/${JETTON1} not found`);
  }

  const poolAddress = await pool.getAddress();

  const poolData = await pool.getData();
  const {
    reserve0,
    reserve1,
    token0WalletAddress,
    token1WalletAddress,
    lpFee,
    protocolFee,
    refFee,
    protocolFeeAddress,
    collectedToken0ProtocolFee,
    collectedToken1ProtocolFee,
  } = poolData;

  const expectedLiquidityData = await pool.getExpectedLiquidity({
    jettonAmount: new TonWeb.utils.BN(500000000),
  });

  const { amount0, amount1 } = expectedLiquidityData;

  const expectedLpTokensAmount = await pool.getExpectedTokens({
    amount0: new TonWeb.utils.BN(500000000),
    amount1: new TonWeb.utils.BN(200000000),
  });

  if (token0WalletAddress) {
    const expectedOutputsData = await pool.getExpectedOutputs({
      amount: new TonWeb.utils.BN(500000000),
      jettonWallet: token0WalletAddress,
    });

    const { jettonToReceive, protocolFeePaid, refFeePaid } =
      expectedOutputsData;
  }

  const lpAccountAddress = await pool.getLpAccountAddress({
    ownerAddress: OWNER_ADDRESS,
  });

  const lpAccount = await pool.getLpAccount({ ownerAddress: OWNER_ADDRESS });

  if (lpAccount) {
    const lpAccountData = await lpAccount.getData();
    const { userAddress, poolAddress, amount0, amount1 } = lpAccountData;
  }
})();

Create a custom router revision.

import TonWeb from 'tonweb';
import {
  LpAccountRevisionV1,
  PoolRevision,
  PoolRevisionV1,
  Router,
  RouterRevision,
  RouterRevisionV1,
} from '@ston-fi/sdk';

/**
 * This example shows how to create custom revision
 * for the router, pool, and lp-account classes
 */

class MyRouterRevision extends RouterRevisionV1 {
  // here you can override any method from default revision with your own implementation

  // if you will need custom pool revision, you need to override constructPoolRevision method
  public override constructPoolRevision: RouterRevision['constructPoolRevision'] = (
    router,
  ) => new MyPoolRevision();
}

class MyPoolRevision extends PoolRevisionV1 {
  // here you can override any method from default revision with your own implementation

  // if you will need custom lp account revision, you need to override constructLpAccountRevision method
  public override constructLpAccountRevision: PoolRevision['constructLpAccountRevision'] =
    (pool) => new MyLpAccountRevision();
}

class MyLpAccountRevision extends LpAccountRevisionV1 {
  // here you can override any method from default revision with your own implementation
}

const customRouter = new Router(new TonWeb.HttpProvider(), {
  revision: new MyRouterRevision(),
  address: 'EQB3ncyBUTjZUA5EnFKR5_EnOMI9V1tTEAAPaiU71gc4TiUt',
});

Tonconnect package uses the sendTransaction method to send a transaction to the blockchain. An example of the usage is on their DOCs.

import React from "react";
import { TonClient, toNano } from "@ton/ton";
import { DEX, pTON } from "@ston-fi/sdk";
import { useTonConnectUI, useTonAddress } from "@tonconnect/ui-react";

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

const dex = client.open(new DEX.v1.Router());

export const Example = () => {
  const wallet = useTonAddress();
  const [tonConnectUI] = useTonConnectUI();

  return (
    <button
      onClick={async () => {
        const txParams = await dex.getSwapTonToJettonTxParams({
          offerAmount: toNano("1"), // swap 1 TON
          askJettonAddress: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // for a STON
          minAskAmount: toNano("0.1"), // but not less than 0.1 STON
          proxyTon: new pTON.v1(),
          userWalletAddress: wallet,
        });

        await tonConnectUI.sendTransaction({
          validUntil: Date.now() + 1000000,
          messages: [
            {
              address: txParams.to.toString(),
              amount: txParams.value.toString(),
              payload: txParams.body?.toBoc().toString("base64"),
            },
          ],
        });
      }}
    >
      Swap 1 TON to STON
    </button>
  );
};

Practical examples for interacting with STON.fi v2 smart contracts.

Available Examples

• Basic token swaps

• Multi-hop swaps

• Slippage protection

• Custom routes

• Balanced liquidity provision

• Single-sided liquidity

• Optimal amounts calculation

• Gas optimization

• Fee collection

• Vault withdrawals

• Permission management

• Batch operations

Usage Guidelines

Best Practices

1. Always simulate transactions first

2. Use appropriate gas limits

3. Handle all error cases

4. Validate inputs thoroughly

Common Patterns

Testing

• Use testnet for development

• Test edge cases thoroughly

• Monitor gas consumption

• Verify state changes

Integration Tips

1. Start Simple: Begin with basic examples

2. Add Complexity: Gradually add features

3. Error Handling: Implement comprehensive error handling

Need Help?

• Review the

• Check

• Ask in

Provide liquidity for a pool

Jetton/Jetton pool deposit

import TonWeb from "tonweb";
import { DEX } from "@ston-fi/sdk";

const USER_WALLET_ADDRESS = ""; // ! replace with your address
const JETTON_0_ADDRESS = "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO"; // STON
const JETTON_1_ADDRESS = "EQBX6K9aXVl3nXINCyPPL86C4ONVmQ8vK360u6dykFKXpHCa"; // GEMSTON

const router = new DEX.v1.Router({
  tonApiClient: new TonWeb.HttpProvider(),
});

const txsParams = await Promise.all([
  // deposit 5 STON to the STON/GEMSTON pool and get at least 1 nano LP token
  router.buildProvideLiquidityJettonTxParams({
    userWalletAddress: USER_WALLET_ADDRESS,
    sendTokenAddress: JETTON_0_ADDRESS,
    sendAmount: new TonWeb.utils.BN("500000000"),
    otherTokenAddress: JETTON_1_ADDRESS,
    minLpOut: new TonWeb.utils.BN("1"),
    queryId: 12345,
  }),
  // deposit 2 GEMSTON to the STON/GEMSTON pool and get at least 1 nano LP token
  router.buildProvideLiquidityJettonTxParams({
    userWalletAddress: USER_WALLET_ADDRESS,
    sendTokenAddress: JETTON_1_ADDRESS,
    sendAmount: new TonWeb.utils.BN("200000000"),
    otherTokenAddress: JETTON_0_ADDRESS,
    minLpOut: new TonWeb.utils.BN("1"),
    queryId: 123456,
  }),
]);

// To execute the transaction, you need to send a transaction to the blockchain.
// This code will be different based on the wallet you are using to send the tx from
// logging is used for demonstration purposes
txsParams.map((txParams) => console.log({
  to: txParams.to,
  amount: txParams.gasAmount,
  payload: txParams.payload,
}));

TON/Jetton pool deposit

Actors

Router

The router is the contract that acts as an entrypoint for all DEX calls. It is responsible for routing all Jetton calls with transfer_notification op to the correct pool contract.

It acts as a sovereign over the DEX, and can be used to lock/unlock trading on all pools, to change fees on a certain pool or to upgrade its own contract. The router is the only contract that can be upgraded. Each Jetton that goes through the DEX is owned by the router. The router does not store anything about pairs.

Pool

The pool is the contract that stores the AMM data for a certain pair and is responsible for handling "swaps" or providing liquidity for a certain pool. For each pair (e.g. TOKEN/USDT), there is only a single pool contract. The pool is also a Jetton Minter, and handles minting/burning of Liquidity Provider Jettons. All the swap/lp calculations are done in the pool contract.

Account

The account contract holds information about the liquidity provided by the user before minting new liquidity. It interacts only with a single pool contract. For each user, there is single account contract for each pool. The router "routes" the temporary liquidity to the correct account contract. Then the account contract calls the pool contract again to mint new liquidity (once it satisfies some requirements).

Wallet (for LP jettons)

The wallet contract is a standard Jetton wallet and is used to hold the LP Jetton minted by Pools.

Calls descriptions

Swap

Lets assume that Alice wants to buy TOKEN using USDT. She should initialize a simple transfer to her own USDT Wallet with a custom payload. Once the Router receives the confirmation of the transfer, it will call the Pool contract to perform the real swap. Then the Pool contract will return the TOKEN Jetton calling pay_to op to the Router.

Providing liquidity (both amounts)

Now Alice wants to provide liquidity to the TOKEN/USDT pair. This process must be done via two different calls. Obviously, since wallets support up to 4 transactions at same time, it is possible to call both calls at the same time (at least, from the user's perspective).

At the beginning, she should start a transfer to her own USDT Wallet with a custom payload. Once the Router receives the confirmation of the transfer, it will call the Pool contract, and then the Pool contract will route the request to her own Account contract. Once the request arrives to the Account contract, the first phase ends here. This time the Account contract doesn't generate any transactions.

In Dex v1 it is possible to provide liquidity using a different ratio than the current one in the pool, thus the unbalanced part will be lost to the user and distributed across all liquidity providers. In Dex v2 always a max amount of liquidity is minted to the user, meaning the unbalanced amount of a tokens is automatically swapped using the current token ratio in the pool.

Now, Alice makes another transfer of the other Jetton (in our case, TOKEN) in the same way as before. This time, the Account contract will generate a new message to the Pool contract to mint new liquidity.

Providing liquidity (single side provision)

Dex v2 supports liquidity provision using only one token by automatically performing a swap before minting liquidity

Creating a pool

V1

To create a new Pool, just provide the minimum amount of liquidity to pair (1001 Jettons). This initial liquidity will be sent to null address. Any LP calls after this will mint LP Jettons to a user.

V2

To create a new Pool, just provide the minimum amount of liquidity to pair (1001 Jettons). A basic amount of 1001 lp tokens will be reserved on pool on initial liquidity deposit with the rest going to the user.

Stableswap

Creation of a stableswap pool is handled directly by STON.fi and cannot be done by users.

Software Development Kits for integrating Omniston liquidity aggregation.

Available SDKs

Full-featured SDK for backend integration:

• TypeScript support

• RxJS Observable-based API

• Comprehensive error handling

• WebSocket subscriptions

React hooks for frontend integration:

• Ready-to-use React hooks

• TanStack Query integration

• Real-time price updates

• Transaction building and sending

Installation

Node.js

React

Quick Start

Node.js

React

Features

• Best Price Discovery: Automatically finds optimal swap routes

• Multi-source Aggregation: Combines liquidity from multiple DEXs

• Real-time Quotes: Live price updates via WebSocket

Documentation

See individual SDK documentation for detailed usage:

This guide will walk you through creating a basic token swap app using the STON.fi SDK and API in a React project. We'll integrate wallet connectivity with TonConnect (via @tonconnect/ui-react) to allow users to connect their TON wallet and perform a swap. The guide is beginner-friendly and assumes minimal React experience.

Note: In this demo, we will leverage Tailwind CSS for styling instead of using custom CSS. The setup for Tailwind CSS is already included in the instructions below, so you don't need to set it up separately.

Note: You can use any package manager (npm, yarn, pnpm, or bun) to set up your React project. In this tutorial, we'll demonstrate with pnpm.

Burn all liquidity tokens to release the underlying assets from a pool.

The production-ready approach is API-driven. Query pool information through @ston-fi/api, let the API return the router metadata, and then build the on-chain contracts with dexFactory. This keeps your integration compatible with future router upgrades and avoids hardcoding contract addresses.

Refund tokens that were sent to an LP account but were not added to the pool.

The production-ready approach is API-driven. Use the STON.fi API to resolve router metadata, construct contracts via dexFactory, and let the SDK derive the correct on-chain calls. This avoids hardcoding addresses and remains forward-compatible with router updates.

Mainnet workflow

In this section, to illustrate all three possible types of a swap, we will do following exchange chain

1. swap 1 TON to STON (ton to jetton swap)

2. swap STON to GEMSTON (jetton to jetton swap)

Check for in-depth message flow.

Off-chain get methods

In this section, to illustrate all three possible types of a swap, we will do following exchange chain

1. swap 1 TON to STON (ton to jetton swap)

2. swap STON to GEMSTON (jetton to jetton swap)

Deposit liquidity (both tokens)

Liquidity provision is done via 2 transactions: deposit of the first token and deposit of the second token.