Unstake funds from Farm NFT

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

const farm = new FARM.v3.NftItem({
  tonApiClient: new TonWeb.HttpProvider(),
  address: "EQA18JnBVNZZ8Wz-Kn6Mc5cy9pv798Pn8tfScjKw9NLPK3U2", // Farm v3 nft address
});

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

// 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
console.log({
  to: txParams.to,
  amount: txParams.gasAmount,
  payload: txParams.payload,
});

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

• stake in farm

• claim farm rewards

• unstake from farm

• destroy farm NFT

Current version: 0.6, released Aug 2023

is a decentralized automated market maker (AMM) built on the TON blockchain providing virtually zero fees, low slippage, an extremely easy interface, and direct integration with TON wallets.

Website:

Web App:

Github:

Twitter:

Telegram:

Reddit:

This documentation describes the design of the system, provides an explanation of the core concepts, and documents the technical details to enable integration with the protocol.

What is an Automated Market Maker (AMM)?

You could think of an Automated Market Maker (AMM) as a robot always willing to quote you a price so that you can swap from one asset to another.

You can swap without trust or reliance upon a central party.

Anyone can provide liquidity to a liquidity pool, earning fees in exchange for usage of these assets.

This is a shift from conventional markets and centralized exchanges, which typically offer a central limit order book mechanism of exchange.

As a result, AMMs are a fundamental and critical part of any broader Decentralized Finance (DeFi) ecosystem.

Why STON.fi

STON.fi was founded in 2022. It aims at building a user-friendly crypto exchange for mass-adoption through access to Telegram audience. Putting a high premium on the Community, STON.fi represents a DEX with a human face, providing users with fast support and taking into account their opinions.

An architecture of TON blockchain with sharding allows STON.fi DEX users conduct millions of transactions per second.

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:

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 Farm usage:

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

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

Swap fees

While doing a swap, thus a trade of your tokens, on STON.fi, you will interact with liquidity pools. This will lead to Price Impact and Slippage and trading fees being charged on your swap.

The trading fee for basic Constant Product Pools is 0.3%:

• 0.2% fee goes to the liquidity providers as a payment by increasing the size of the pools.

• 0.1% fee goes to the protocol.

Staking of the LP tokens in Farm

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.

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

Free liquidity by buring liquidity pool tokens.

As a result of the SDK build*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 payload 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:

Follow us on

Join our community on

Join our community on

Join our community on

Browse

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.

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

• methods reference

• perform a swap operation

• provide liquidity

• refund liquidity

• burn liquidity tokens

Referral Fees

DEX v1 pays the referrer fee directly inside each swap transaction. The rate is fixed at 0.1 % and the specified referrer_address receives the tokens immediately.

Track payouts using the Stats & Vaults REST API:

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

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

• GET /v1/stats/fees – returns aggregated referral fee information such as total accrued USD value

See the Omniston referral fees guide (remember: although the guide focuses on Omniston, the linked paragraph explains DEX V1 referral fees in detail). Full API docs are available in the Swagger UI.

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://testnet.toncenter.com/api/v2/jsonRPC",
});

const router = client.open(
  DEX.v2_1.Router.CPI.create(
    "kQALh-JBBIKK7gr0o4AVf9JZnEsFndqO0qTCyT-D-yBsWk0v" // CPI Router v2.1.0
  )
);

const pool = client.open(
  await router.getPool({
    token0: "kQDLvsZol3juZyOAVG8tWsJntOxeEZWEaWCbbSjYakQpuYN5", // TestRED
    token1: "kQB_TOJSB7q3-Jm1O8s0jKFtqLElZDPjATs5uJGsujcjznq3", // TestBLUE
  })
);

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.

Automated Market Maker / "AMM"

An automated market maker is a smart contract on TON Blockchain that holds liquidity reserves. Users can trade against these reserves at prices determined by a fixed formula. Anyone may contribute liquidity to these smart contracts, earning pro-rata trading fees in return.

Asset

While a digital asset can take many forms, the STON.fi Protocol supports jetton pairs.

Liquidity Provider / "LP"

A liquidity provider is someone who deposits jettons into a given liquidity pool. Liquidity providers take on price risk and are compensated with trading fees.

Liquidity

Digital assets that are stored in a STON.fi pool contract, and are able to be traded against by traders.

Pair

A smart contract deployed from a STON.fi that enables trading between two jettons.

Pool

A contract deployed by the STON.fi protocol that pairs two assets.

Mid Price

The price between the available buy and sell prices. In STON.fi protocol, this is the ratio of the two jettons reserves.

Price Impact

The difference between the mid-price and the execution price of a trade.

Protocol Fees

Fees that are rewarded to the protocol itself, rather than to liquidity providers.

Swap Fees

Fees collected upon swapping which are rewarded to liquidity providers.

Slippage

An amount the price moves in a trading pair between when a transaction is submitted and when it is executed.

Basic token unit

A basic token unit is a minimum amount of a certain token, e.g. for $TON a basic token unit is nanoTon. In order to convert an amount of tokens to their representation in basic token units one must multiply an amount of tokens and 10 to the power of number of decimal places used for the token: 1 $TON = 1000000000 nanoTons, 1 $USDC = 1000000 basic USDC token units, etc.

Impermanent loss

Impermanent loss happens when you provide liquidity to a liquidity pool and the price of your deposited assets changes compared to when you deposited them. The bigger this change is, the more you are exposed to impermanent loss. In this case, the loss means less dollar value at the time of withdrawal than at the time of deposit. Pools that contain assets that remain in a relatively small price range will be less exposed to impermanent loss. Stablecoins or different wrapped (pegged) versions of a token, for example, will stay in a relatively contained price range. Impermanent Loss (IL) is a risk associated with providing liquidity to an Automated Market Maker (AMM). As a result, the AMM compensates liquidity providers with fees generated from trades from the pool.

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

const router = client.open(
  DEX.v2_1.Router.CPI.create(
    "kQALh-JBBIKK7gr0o4AVf9JZnEsFndqO0qTCyT-D-yBsWk0v" // CPI Router v2.1.0
  )
);

const vault = client.open(
  await router.getVault({
    tokenMinter: "kQDLvsZol3juZyOAVG8tWsJntOxeEZWEaWCbbSjYakQpuYN5", // TestRED
    user: "" // ! replace with your address
  })
);

const txParams = await vault.getWithdrawFeeTxParams({
  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.

For a comprehensive overview of referral fees, see the Omniston referral fees guide (remember: it is an Omniston-focused guide, but the highlighted paragraph details the DEX V2 referral process).

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://testnet.toncenter.com/api/v2/jsonRPC",
});

const router = client.open(
  DEX.v2_1.Router.CPI.create(
    "kQALh-JBBIKK7gr0o4AVf9JZnEsFndqO0qTCyT-D-yBsWk0v" // CPI Router v2.1.0
  )
);

const pool = client.open(
  await router.getPool({
    token0: "kQDLvsZol3juZyOAVG8tWsJntOxeEZWEaWCbbSjYakQpuYN5", // TestRED
    token1: "kQB_TOJSB7q3-Jm1O8s0jKFtqLElZDPjATs5uJGsujcjznq3", // TestBLUE
  })
);

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

const lpWalletData = await lpWallet.getWalletData();

const txParams = await pool.getBurnTxParams({
  amount: lpWalletData.balance,
  userWalletAddress: 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.

Claim rewards from Farm NFT

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

const farm = new FARM.v3.NftItem({
  tonApiClient: new TonWeb.HttpProvider(),
  address: "EQA18JnBVNZZ8Wz-Kn6Mc5cy9pv798Pn8tfScjKw9NLPK3U2", // Farm v3 nft address
});

// Claim occurred farming rewards from the NFT to the owner's wallet
const txParams = farm.buildClaimRewardsTxParams({
  queryId: 12345,
});

// 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
console.log({
  to: txParams.to,
  amount: txParams.gasAmount,
  payload: txParams.payload,
});

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

import TonWeb from "tonweb";
import { TonClient, WalletContractV4, internal, toNano, Cell } from "@ton/ton";
import { mnemonicToPrivateKey } from "@ton/crypto";
import { DEX, pTON } from "@ston-fi/sdk";

const MNEMONIC = Array.from({ length: 24 }, (_, i) => `your mnemonic word ${i + 1}`); // replace with your mnemonic
const TON_API_URL = "https://toncenter.com/api/v2/jsonRPC";

const client = new TonClient({
    endpoint: TON_API_URL,
});

const keyPair = await mnemonicToPrivateKey(MNEMONIC);

const wallet = WalletContractV4.create({
    workchain: 0,
    publicKey: keyPair.publicKey,
});

const contract = client.open(wallet);

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

const swapTxParams = await dex.buildSwapTonToJettonTxParams({
    offerAmount: toNano('1'), // swap 1 TON
    askJettonAddress: 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO', // for a STON
    minAskAmount: toNano('0.1'), // but not less than 0.1 STON
    proxyTonAddress: pTON.v1.address.toString(),
    userWalletAddress: wallet.address.toString(),
});

await contract.sendTransfer({
    seqno: await contract.getSeqno(),
    secretKey: keyPair.secretKey,
    messages: [internal({
        to: swapTxParams.to.toString(),
        value: BigInt(swapTxParams.gasAmount.toString()),
        body: Cell.fromBase64(TonWeb.utils.bytesToBase64(await swapTxParams.payload.toBoc())),
    })]
});

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',
});

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

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 pool = await router.getPool({
  token0: JETTON_0_ADDRESS,
  token1: JETTON_1_ADDRESS,
});

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

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

if (!lpAccount) {
  throw Error(
    `LpAccount for ${USER_WALLET_ADDRESS} at ${JETTON_0_ADDRESS}/${JETTON_1_ADDRESS} pool not found`
  );
}

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

// 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
console.log({
  to: txParams.to,
  amount: txParams.gasAmount,
  payload: txParams.payload,
});

STON.fi SDK

Welcome to the STON.fi SDK docs section.

• SDK source code

• SDK on NPM

Getting Started

Overview

The SDK is written in TypeScript and designed to be a thin wrapper on top of the STON.fi contracts, which will help STON.fi protocol to be used more easily in JS/TS projects

The SDK reflects the structure of contracts so that access to contract methods is possible through the use of the corresponding class from the SDK.

TonWeb

SDK is built based on the TonWeb library, which provides primitives for working with data on the TON blockchain, as well as bare contract instances that our SDK expands with unique contract methods

The TonWeb library allows you to make on-chain requests and for that uses toncenter API with a rate limit of 1 request per second. You can obtain higher limits by:

• requesting an API key from toncenter with a 10 request per minute limit

• use open TON API instance, for example, from ORBS

• found a paid instance of TON API with suitable rate limits for your case

• selfhost an instance of TON API

Installation

To install SDK via npm use:

npm install tonweb @ston-fi/sdk

To install SDK with yarn use:

yarn add tonweb @ston-fi/sdk

To install SDK with pnpm use:

pnpm install tonweb @ston-fi/sdk

Usage

We recommend you check the documentation sections dedicated to the architecture of contracts and their methods to get more context about STON.fi protocol in general before starting to interact with the contracts via the SDK

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

• DEX

• Farm

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

burn#595f07bc query_id:uint64 amount:Grams response_destination:MsgAddress custom_payload:Maybe ^Cell = InternalMsgBody;

Message body

custom_payloads

Outgoing messages

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

Burn all liquidity tokens to free liquidity from a pool

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 pool = await router.getPool({
  token0: JETTON_0_ADDRESS,
  token1: JETTON_1_ADDRESS,
});

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

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

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

// 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
console.log({
  to: txParams.to,
  amount: txParams.gasAmount,
  payload: txParams.payload,
});

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

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

const farm = new FARM.v3.NftItem({
  tonApiClient: new TonWeb.HttpProvider(),
  address: "EQA18JnBVNZZ8Wz-Kn6Mc5cy9pv798Pn8tfScjKw9NLPK3U2", // Farm v3 nft address
});

// Destroy farm NFT from the owner's wallet
const txParams = farm.buildDestroyTxParams({
  queryId: 12345,
});

// 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
console.log({
  to: txParams.to,
  amount: txParams.gasAmount,
  payload: txParams.payload,
});

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

burn#595f07bc query_id:uint64 amount:Grams response_destination:MsgAddress custom_payload:Maybe ^Cell = InternalMsgBody;

Message body

Outgoing messages

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

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

import TonWeb from "tonweb";
import TonWebMnemonic from "tonweb-mnemonic";
import { DEX, pTON } from "@ston-fi/sdk";

const MNEMONIC = Array.from({ length: 24 }, (_, i) => `your mnemonic word ${i + 1}`); // replace with your mnemonic

const tonWeb = new TonWeb();

const client = new TonWeb.HttpProvider();

const keyPair = await TonWebMnemonic.mnemonicToKeyPair(MNEMONIC);

const wallet = new tonWeb.wallet.all.v4R2(client, {
    publicKey: keyPair.publicKey,
});

const dex = new DEX.v1.Router({
    tonApiClient: client,
})

const swapTxParams = await dex.buildSwapTonToJettonTxParams({
    offerAmount: TonWeb.utils.toNano('1'), // swap 1 TON
    askJettonAddress: 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO', // for a STON
    minAskAmount: TonWeb.utils.toNano('0.1'), // but not less than 0.1 STON
    proxyTonAddress: pTON.v1.address.toString(),
    userWalletAddress: (await wallet.getAddress()).toString(),
});

await wallet.methods.transfer({
    secretKey: keyPair.secretKey,
    toAddress: swapTxParams.to,
    amount: swapTxParams.gasAmount,
    seqno: await wallet.methods.seqno().call() ?? 0,
    payload: swapTxParams.payload,
    sendMode: 3,
}).send();

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 TonWeb from 'tonweb';
import { DEX, pTON } from '@ston-fi/sdk';
import { useTonConnectUI, useTonAddress } from '@tonconnect/ui-react';

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

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

  return (
    <button
      onClick={async () => {
        const swapTxParams = await dex.buildSwapTonToJettonTxParams({
          offerAmount: TonWeb.utils.toNano('1'), // swap 1 TON
          askJettonAddress: 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO', // for a STON
          minAskAmount: TonWeb.utils.toNano('0.1'), // but not less than 0.1 STON
          proxyTonAddress: pTON.v1.address.toString(),
          userWalletAddress: wallet,
        });

        await tonConnectUI.sendTransaction({
          validUntil: Date.now() + 1000000,
          messages: [
            {
              address: swapTxParams.to.toString(),
              amount: swapTxParams.gasAmount.toString(),
              payload: TonWeb.utils.bytesToBase64(
                await swapTxParams.payload.toBoc(),
              ),
            },
          ],
        });
      }}
    >
      Swap 1 TON to STON
    </button>
  );
};

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.

Swagger

You can always found detailed information about the DEX API in Swagger documentation

SDK

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

Overview

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

• AMM DEXs

• On-chain RFQ resolvers (TON)

The Request for Quote (RFQ) mechanism allows users to get the most competitive price quote from resolvers, including external DEX platforms.

Key benefits

Omniston offers several advantages:

• Provides users with the best pricing conditions

• Access to a wide range of tokens across different liquidity sources within the ecosystem

• Flexibility to set fees

• Allows seamless integration by providing access to all liquidity sources in one unified platform, eliminating the need for third-party solutions

Use Case

For example, when a user wants to swap Token A for Token B, they initiate a swap request through Omniston. The protocol aggregates quotes from all connected liquidity sources, including external DEX platforms, and presents the user with the most favorable offer.

Swap

For instructions on performing a swap using the Omniston protocol, see the Swap overview.

SDK

Omniston SDK packages for developers:

• Node.js SDK for JavaScript/TypeScript applications.

• React SDK for use in React or Next.js applications.

For information about implementing referral fees in your application, see the Referral Fees guide.

Application

• Source code for the demo App for application developers.

Overview

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

• Pool

• Router

• LpAccount

• LpWallet

Source code of all smart contracts can be found in this Github repo

Definitions of terminology used can be found in Glossary

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 Omniston referral fees guide (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 – returns aggregated referral fee information, such as total accrued USD value, for the selected time frame

The full specification is available in the Swagger UI.

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

• perform a swap operation

• provide liquidity

• refund liquidity

• burn liquidity tokens

• using get methods

• create a custom router revision

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 Omniston referral fees guide (note: while the guide is Omniston-centric, the specified section covers DEX V2 referral mechanics thoroughly).

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.

Introduction

is a decentralized exchange (DEX) on TON blockchain. More specifically it is an Automated Market Maker (AMM) exchange employing the Constant Product Market Maker algorithm. The web based app () is a visual interface for interacting with a set of smart contracts deployed to the TON blockchain.

The exchange is fully decentralized and non-custodian. Funds are held in permissionless smart contract accounts. This means the only methods to withdraw funds from the pool accounts are those encoded in the smart contract. At a high level this code only allows withdrawals in exchange for an appropriate amount of another asset or by liquidity owners in exchange for their Pool Tokens. Furthermore, the contracts are fully permissionless. This means that any account can create a pool by issuing the correct set of transactions and that no account has authority over the pool's assets or functionality. There is no mechanism to revert or adjust transactions even if they are made in error. Contracts, except the router, are immutable. This means no account has the authority to update or delete pool contracts and funds cannot be stolen. For transparency, all router contract upgrades are time-locked for seven days and a user may withdraw their provided liquidity during this period if they find the changes disagreeable.

STON.fi Protocol

• Fully decentralized system. All transactions are made directly between traders, and do not require a third-party. STON.fi doesn’t have access to your coins/tokens and never asks for your personal information, never collect IP or Geo data, or anything else that may be used for user identification.

• Virtually zero trading fees. STON.fi runs on the TON blockchain with much lower transaction costs and higher speed compared to Bitcoin or Ethereum blockchains.

• Low to zero slippage. As an AMM, STON.fi relies on liquidity pools and simple, yet sophisticated algorithms to determine token prices. This guarantees that you get the rates provided before the transaction.

• The front running is not an issue at STON.fi due to advanced sharding and async nature of TON blockchain.

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

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.

Welcome to the docs section.

Getting Started

Overview

The SDK is written in TypeScript and designed to be a thin wrapper on top of the STON.fi contracts, which will help STON.fi protocol to be used more easily in JS/TS projects

The SDK reflects the structure of contracts so that access to contract methods is possible through the use of the corresponding class from the SDK.

@ton package

SDK is built based on the package, which provides primitives for working with data on the TON blockchain, as well as bare contract instances that our SDK expands with unique contract methods

The @ton library allows you to make on-chain requests and for that with a rate limit of 1 request per second. You can obtain higher limits by:

• requesting an API key from with a 10 request per minute limit

• use open TON API instance, for example, from

• found a paid instance of TON API with suitable rate limits for your case

• selfhost an instance of TON API

Installation

Firstly install the package following their

Then, add SDK package using the package manager of your choice.

Installation of release candidate version

Sometimes, we publish a release candidate version of the SDK package to give you early access to the next version. To install this version, you need to expressly specify that you are interested in the next version during the installation.

Usage

We recommend you check the documentation sections dedicated to the architecture of contracts and their methods to get more context about STON.fi protocol in general before starting to interact with the contracts via the SDK

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

Live demo

We are providing a simple but fully functional demo app with the SDK usage in the next.js app to demonstrate the SDK functionality. The source code is open-sourced and can be found . Try this app at

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

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

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:

• - Learn how to build a simple token swap interface using React and the STON.fi SDK

• - Learn how to use STON.fi's liquidity aggregation protocol in your application

• - Learn how to provide liquidity to STON.fi pools

What You'll Learn

Our quickstart guides typically cover:

• Project setup with the necessary dependencies

• Integration with TON wallets using TonConnect

• Fetching data from STON.fi API

• Executing transactions on the TON blockchain

• Building user interfaces for STON.fi features

Prerequisites

While our guides are designed to be accessible, having basic knowledge of the following will be helpful:

• JavaScript/TypeScript

• React (for frontend guides)

• Basic understanding of blockchain concepts

Additional Resources

After completing these quickstart guides, you may want to explore more detailed documentation:

• - For advanced SDK usage

• - For using STON.fi's liquidity aggregation protocol

• - For direct interaction with smart contracts

Feedback

We're constantly working to improve our documentation. If you have suggestions or encounter any issues with these guides, please .

Deposit liquidity (both tokens)

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

Deposit of the first token

The amount of the first token sent is stored on a user's lp account awaiting a transaction of the second token.

Deposit of the second token

When the second token is sent, lp account automatically initiates liquidity addition into the pool. As a result, full amounts of deposited tokens are used as new liquidity and the user receives lp tokens.

Notes:

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

• when depositing initial liquidity 0.000001001 lp tokens will be reserved on pool, the rest of liquidity will be sent to the user

Deposit liquidity (single side provision)

It is possible to deposit liquidity by sending just 1 type of token, the pool will automatically perform a swap and use the resulting amount to mint lp tokens

Deposit liquidity (with payload)

It is possible to specify who will receive lp tokens and to include a payload which will be sent as transfer_notification (e.g. Farm contract)

Refund deposited liquidity

In the event that the issued amount of lp tokens doesn't match the specified minimum value, all deposited liquidity is returned to lp account and can be withdrawn by user.

Liquidity is refunded to lp account

Withdraw refunded liquidity

Withdraw liquidly

Liquidly is withdrawn from a pool by burning lp tokens, a user then receives both pool tokens based on the current exchange rate.

Providing already deposited liquidity

A user can deposit liquidity after it was refunded to lp account without doing a withdraw.

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

Referral Fees

DEX v2 stores each swap's referral portion in a dedicated Vault contract (one per referrer × token pair). The fee percentage can be set between 0.01 % and 1 % and must be withdrawn later by the referrer.

Inspect vault balances and history using the Stats & Vaults REST API:

• GET /v1/wallets/{addr_str}/fee_vaults – lists all known vaults per referrer

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

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

• GET /v1/stats/fees – returns aggregated referral fee information, for example total accrued USD value

See the Omniston (note: although the guide is Omniston-oriented, the referenced paragraph explains DEX V2 referral fees in detail). Full API documentation is available in the .

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.

Provide liquidity for a pool

Jetton/Jetton pool deposit

import { TonClient, toNano } from "@ton/ton";
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 client = new TonClient({
  endpoint: "https://toncenter.com/api/v2/jsonRPC",
});

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

const txsParams = await Promise.all([
  // deposit 0.5 STON to the STON/GEMSTON pool and get at least 1 nano LP token
  router.getProvideLiquidityJettonTxParams({
    userWalletAddress: USER_WALLET_ADDRESS,
    sendTokenAddress: JETTON_0_ADDRESS,
    sendAmount: toNano("0.5"),
    otherTokenAddress: JETTON_1_ADDRESS,
    minLpOut: "1",
    queryId: 12345,
  }),
  // deposit 2 GEMSTON to the STON/GEMSTON pool and get at least 1 nano LP token
  router.getProvideLiquidityJettonTxParams({
    userWalletAddress: USER_WALLET_ADDRESS,
    sendTokenAddress: JETTON_1_ADDRESS,
    sendAmount: toNano("2.0"),
    otherTokenAddress: JETTON_0_ADDRESS,
    minLpOut: "1",
    queryId: 123456,
  }),
]);

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.

TON/Jetton pool deposit

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

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

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

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

const txsParams = await Promise.all([
  // deposit 1 TON to the STON/TON pool and get at least 1 nano LP token
  router.getProvideLiquidityTonTxParams({
    userWalletAddress: USER_WALLET_ADDRESS,
    proxyTon: new pTON.v1(),
    sendAmount: toNano("1"),
    otherTokenAddress: JETTON_0_ADDRESS,
    minLpOut: "1",
    queryId: 12345,
  }),
  // deposit 0.5 STON to the STON/TON pool and get at least 1 nano LP token
  router.getProvideLiquidityJettonTxParams({
    userWalletAddress: USER_WALLET_ADDRESS,
    sendTokenAddress: JETTON_0_ADDRESS,
    sendAmount: toNano("0.5"),
    otherTokenAddress: new pTON.v1().address,
    minLpOut: "1",
    queryId: 123456,
  }),
]);

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.

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

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

const USER_WALLET_ADDRESS = ""; // ! replace with your address
const JETTON_0_ADDRESS = "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO"; // STON
const pTON_ADDRESS = pTON.v1.address;

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

const txsParams = await Promise.all([
  // deposit 1 TON to the STON/TON pool and get at least 1 nano LP token
  router.buildProvideLiquidityTonTxParams({
    userWalletAddress: USER_WALLET_ADDRESS,
    proxyTonAddress: pTON_ADDRESS,
    sendAmount: new TonWeb.utils.BN("100000000"),
    otherTokenAddress: JETTON_0_ADDRESS,
    minLpOut: new TonWeb.utils.BN("1"),
    queryId: 12345,
  }),
  // deposit 5 STON to the STON/TON 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: pTON_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,
}));

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)

3. swap GEMSTON back to TON (jetton to ton swap)

Swap TON to jetton

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

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

// swap 1 TON to STON but not less than 1 nano STON
const txParams = await router.buildSwapTonToJettonTxParams({
  userWalletAddress: "", // ! replace with your address
  proxyTonAddress: pTON.v1.address,
  offerAmount: new TonWeb.utils.BN("1000000000"),
  askJettonAddress: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  minAskAmount: new TonWeb.utils.BN("1"),
  queryId: 12345,
});

// 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
console.log({
  to: txParams.to,
  amount: txParams.gasAmount,
  payload: txParams.payload,
});

Swap jetton to jetton

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

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

// swap 1 STON to GEMSTON but not less than 1 nano GEMSTON
const txParams = await router.buildSwapJettonToJettonTxParams({
  userWalletAddress: "", // ! replace with your address
  offerJettonAddress: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  offerAmount: new TonWeb.utils.BN("1000000000"),
  askJettonAddress: "EQBX6K9aXVl3nXINCyPPL86C4ONVmQ8vK360u6dykFKXpHCa", // GEMSTON
  minAskAmount: new TonWeb.utils.BN("1"),
  queryId: 12345,
});

// 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
console.log({
  to: txParams.to,
  amount: txParams.gasAmount,
  payload: txParams.payload,
});

Swap jetton to TON

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

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

// swap 1 GEMSTON to TON but not less than 1 nano TON
const txParams = await router.buildSwapJettonToTonTxParams({
  userWalletAddress: "", // ! replace with your address
  offerJettonAddress: "EQBX6K9aXVl3nXINCyPPL86C4ONVmQ8vK360u6dykFKXpHCa", // GEMSTON
  offerAmount: new TonWeb.utils.BN("1000000000"),
  proxyTonAddress: pTON.v1.address,
  minAskAmount: new TonWeb.utils.BN("1"),
  queryId: 12345,
});

// 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
console.log({
  to: txParams.to,
  amount: txParams.gasAmount,
  payload: txParams.payload,
});

Recommended gas values

Below are recommended values for TON sent and forward gas for each type of the swap:

Formulas:

pTON -> Jetton

// pton_transfer + (pay_to + jetton_transfer) * 2 + (jetton_notification + swap)
fwd_amount = 0.01 + (0.02 + 0.06) * 2 + 0.045; // = 0.215
// jetton_transfer + fwd_amount
tx_amount = swap_amount + fwd_amount; // = swap_amount + 0.215

Jetton -> Jetton

// (jetton_notification + swap) + (pay_to + jetton_transfer) * 2
fwd_amount = 0.045 + (0.02 + 0.06) * 2; // = 0.205
// jetton_transfer + fwd_amount
tx_amount = 0.06 + fwd_amount; // = 0.265

Jetton -> pTON

// (jetton_notification + swap) + (pay_to + pton_transfer) * 2
fwd_amount = 0.045 + (0.02 + 0.02) * 2; // = 0.125
// jetton_transfer + fwd_amount
tx_amount = 0.06 + fwd_amount; // = 0.185

API reference

Overview

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

• Pool

• Router

• LpAccount

• LpWallet

• Vault

Definitions of terminology used can be found in Glossary

Example schemes

Example schemes can be found here:

• Swap examples

• Lp provide examples

• Vault examples

Op code list

A table with DEX v2 op codes:

• Op Codes

New DEX v2 features:

Swap

• custom payload & nested operations after swaps

• chain multiple swaps on the same Router

• chain multiple swaps on different v2 Routers

• custom refund address and payload on swap failure

• deadline for tx completion

Liquidity

• custom payload after liquidly provision

• improved initial liquidity locking management, no coins are lost anymore

• now always mints a maximum possible amount of lp tokens to user even if provision ratio is different from current one in Pool

• single side liquidity provision

• deadline for tx completion

Referral

• referral fees are stored in Vault contract

• custom referral fee value in each swap (maximum 1%)

Referral Fees

DEX v2 accumulates each swap's referral portion in a dedicated Vault contract (one per referrer × token pair). Fees can be configured in the0.01 %–1 % range and must later be withdrawn by the referrer. See the Omniston referral fees guide (note: although the guide is Omniston-oriented, the referenced paragraph explains in detail how DEX V2 referral fees work).

You can inspect vault balances and accrual history using the Stats & Vaults REST API:

• GET /v1/wallets/{addr_str}/fee_vaults – lists all known vaults per referrer

• 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 withdrawals from the referrer's vaults, filterable by period

• GET /v1/stats/fees – returns aggregated referral fee metrics (for example, total accrued USD value) by time frame

All endpoints are documented in the Swagger UI.

pTON v2

• now uses a custom op code for ton transfers

• ton transfer to user is non-bouncable

• improved gas management

• can chain ton transfers between 2 pTON wallets (to chain pTON swaps on v2 Routers)

Other

• LpAccount and Vault are deleted if they have 0 tokens on balance to avoid paying storage cost

• better error management: no coins are lost if Pool doesn't exist / payload is not correct

• complete refactoring of the codebase and usage of libs in masterchain to make all operations cheaper

• fixed various excesses issues

• fixed some Pools having broken get_jetton_data

Removed

Pool

• off-chain get_expected_outputs

• off-chain get_expected_tokens

• off-chain get_expected_liquidity

• on-chain getter_expected_outputs

• on-chain getter_expected_tokens

• on-chain getter_expected_liquidity

• user-called collect_fees

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;
  }
})();

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.

Check for in-depth message flow.

Off-chain get methods

get_vault_data

Returns Vault data

Arguments

None

Result

Returns VaultData structure containing current state of the Vault.

VaultData structure

Owner operation handlers

Handles calls from the Vault owner

withdraw_fee (0x354bcdf4)

Burn an amount of liquidity tokens.

TL-B

Message body

Outgoing messages

Sends a message with vault_pay_to op code to the router contract with the amount of token to be payed.

Internal message handlers

Handles calls from the Router owner

deposit_ref_fee (0x0490f09b)

Increase ref fee tracker for the user.

TL-B

Message body

Outgoing messages

Sends excesses to excesses_address.

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)

3. swap GEMSTON back to TON (jetton to ton swap)

Swap TON to jetton

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

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

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

// swap 1 TON to STON but not less than 1 nano STON
const txParams = await router.getSwapTonToJettonTxParams({
  userWalletAddress: "", // ! replace with your address
  proxyTon: new pTON.v1(),
  offerAmount: toNano("1"),
  askJettonAddress: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  minAskAmount: "1",
  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.

Swap jetton to jetton

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

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

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

// swap 1 STON to GEMSTON but not less than 1 nano GEMSTON
const txParams = await router.getSwapJettonToJettonTxParams({
  userWalletAddress: "", // ! replace with your address
  offerJettonAddress: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  offerAmount: toNano("1"),
  askJettonAddress: "EQBX6K9aXVl3nXINCyPPL86C4ONVmQ8vK360u6dykFKXpHCa", // GEMSTON
  minAskAmount: "1",
  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.

Swap jetton to TON

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

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

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

// swap 1 GEMSTON to TON but not less than 1 nano TON
const txParams = await router.getSwapJettonToTonTxParams({
  userWalletAddress: "", // ! replace with your address
  offerJettonAddress: "EQBX6K9aXVl3nXINCyPPL86C4ONVmQ8vK360u6dykFKXpHCa", // GEMSTON
  offerAmount: toNano("1"),
  proxyTon: new pTON.v1(),
  minAskAmount: "1",
  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.

Recommended gas values

Below are recommended values for TON sent and forward gas for each type of the swap:

Formulas:

pTON -> Jetton

// pton_transfer + (pay_to + jetton_transfer) * 2 + (jetton_notification + swap)
fwd_amount = 0.01 + (0.02 + 0.045) * 2 + 0.045; // = 0.185
// jetton_transfer + fwd_amount
tx_amount = swap_amount + fwd_amount; // = swap_amount + 0.185

Jetton -> Jetton

// (jetton_notification + swap) + (pay_to + jetton_transfer) * 2
fwd_amount = 0.045 + (0.02 + 0.045) * 2; // = 0.175
// jetton_transfer + fwd_amount
tx_amount = 0.045 + fwd_amount; // = 0.22

Jetton -> pTON

// (jetton_notification + swap) + (pay_to + pton_transfer) * 2
fwd_amount = 0.045 + (0.02 + 0.02) * 2; // = 0.125
// jetton_transfer + fwd_amount
tx_amount = 0.045 + fwd_amount; // = 0.17

This guide describes how to use the Omniston swap functionality over the gRPC API from a trader's perspective. It parallels Swap overview (WebSocket) but shows the gRPC specifics.

Key Differences from WebSocket API

1. Protocol Field For the gRPC API, the protocol field in each swap chunk must be a string:

   • "StonFiV1", "StonFiV2", "DeDust", or "TonCo". In contrast, the WebSocket API uses numeric codes 1, 2, 3, or 4.

2. Extra Version Currently, only extraVersion = 1 is supported.

3. Steps vs. Chunks

   • Each SwapStep moves from one asset to another (e.g., TON → USDC).

   • Each step can have multiple SwapChunk objects, but on TON you typically see exactly one chunk per step.

4. Method Names In the gRPC API, traders use similar calls to requestForQuote, buildTransfer, trackTrade, etc., but these are exposed via protobuf messages, not JSON-RPC. The underlying fields are the same.

Typical Flow (Traders)

A typical gRPC-based swap flow from a trader's viewpoint is:

1. Send a Quote Request Using Omniston.requestForQuote (or the corresponding gRPC call), providing:

   • bidAssetAddress, askAssetAddress

   • The desired amount (either bidUnits or askUnits)

   • Optional referrerAddress and referrerFeeBps

   • settlementMethods = [SETTLEMENT_METHOD_SWAP] if you want a swap

   • settlementParams such as maxPriceSlippageBps or maxOutgoingMessages (for TON)

   You receive an Observable (RxJS style in the SDK) or a stream of QuoteResponseEvent messages over gRPC. The server may update your quote repeatedly if a more favorable price arrives.

2. Build the Transfer When you have a valid Quote, call Omniston.buildTransfer with:

   • The quote you accepted

   • Your sourceAddress (on bidBlockchain)

   • Your destinationAddress (on askBlockchain) The API returns an object with blockchain-specific transaction data (for TON, a list of messages).

3. Sign/Send the Transaction

   • On TON, you typically pass these messages to your wallet (e.g., TonConnect, Tonkeeper, etc.).

   • Wait for the transaction to be mined.

4. Track the Trade You can then call Omniston.trackTrade to receive streaming updates about the trade status. This includes whether the trade was filled, partially filled, or aborted.

Important Data Types

• Blockchain A numeric code following SLIP-044. For TON, this is 607.

• Address An object:

  Copy

  {
    "blockchain": 607,
    "address": "EQDA3..."
  }

• Protocol Must be one of:

  • "StonFiV1"

  • "StonFiV2"

  • "DeDust"

  • "TonCo"

• SettlementMethod For now, typically [0] for swap in numerical form, or (in your SDK) SettlementMethod.SETTLEMENT_METHOD_SWAP.

• SwapStep and SwapChunk

  • Each step is a transition from bidAssetAddress to askAssetAddress.

  • For TON: typically exactly one chunk per step.

  • A chunk includes:

    Copy

    string protocol = 1;       // e.g. "StonFiV2"
    string offer_amount = 2;
    string ask_amount = 3;
    uint64 extra_version = 4;  // must be 1
    bytes extra = 5;           // base64-encoded data for your DEX

• Quote The server provides a quoteId, bidUnits, askUnits, quoteTimestamp, tradeStartDeadline, etc. Includes params with settlement info for the chosen method (SwapSettlementParams).

Rejected Quotes

If you pass extraVersion != 1 (e.g., 3), the quote or the route gets rejected with a message like:

Invalid extra version for step 0: 3

Make sure to use extraVersion = 1.

Next Steps

For a complete, low-level definition of the gRPC service (resolver side, plus the underlying messages), see Resolver Integration Guide. For Node.js or TypeScript usage, see omniston-nodejs.md or the omniston-react.md for React apps. Both rely on the same underlying gRPC/WS backend.

If you have any questions or issues, please reach out in our STON.fi Discord.

Jetton1/Jetton2 pool

Provide liquidity for a liquidity pool of 2 Jettons.

Proxy-ton/Jetton pool

Provide liquidity for a liquidity pool with proxy ton.

Jetton1/Jetton2

Perform a swap operation.

Proxy-ton/Jetton

Perform a swap operation using proxy-ton.

Recommended gas values

Below are recommended values for TON sent and forward gas for each type of the swap:

Formulas:

Jetton -> Jetton

Jetton -> pTON

pTON -> Jetton

Provide liquidity for a pool

Jetton/Jetton pool deposit (two sides)

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

const USER_WALLET_ADDRESS = ""; // ! replace with your address
const JETTON_0_ADDRESS = "kQDLvsZol3juZyOAVG8tWsJntOxeEZWEaWCbbSjYakQpuYN5"; // TestRED
const JETTON_1_ADDRESS = "kQB_TOJSB7q3-Jm1O8s0jKFtqLElZDPjATs5uJGsujcjznq3"; // TestBLUE

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

const router = client.open(
  DEX.v2_1.Router.CPI.create(
    "kQALh-JBBIKK7gr0o4AVf9JZnEsFndqO0qTCyT-D-yBsWk0v" // CPI Router v2.1.0
  )
);

const txParams = await Promise.all([
  // deposit 1 TestRED to the TestRED/TestBLUE pool and get at least 1 nano LP token
  router.getProvideLiquidityJettonTxParams({
    userWalletAddress: USER_WALLET_ADDRESS,
    sendTokenAddress: JETTON_0_ADDRESS,
    sendAmount: toNano("1"),
    otherTokenAddress: JETTON_1_ADDRESS,
    minLpOut: "1",
    queryId: 12345,
  }),
  // deposit 1 TestBLUE to the TestRED/TestBLUE pool and get at least 1 nano LP token
  router.getProvideLiquidityJettonTxParams({
    userWalletAddress: USER_WALLET_ADDRESS,
    sendTokenAddress: JETTON_1_ADDRESS,
    sendAmount: toNano("1"),
    otherTokenAddress: JETTON_0_ADDRESS,
    minLpOut: "1",
    queryId: 123456,
  }),
]);

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.

Jetton/Jetton pool deposit (single sides)

const USER_WALLET_ADDRESS = ""; // ! replace with your address
const JETTON_0_ADDRESS = "kQDLvsZol3juZyOAVG8tWsJntOxeEZWEaWCbbSjYakQpuYN5"; // TestRED
const JETTON_1_ADDRESS = "kQB_TOJSB7q3-Jm1O8s0jKFtqLElZDPjATs5uJGsujcjznq3"; // TestBLUE

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

const router = client.open(
  DEX.v2_1.Router.CPI.create(
    "kQALh-JBBIKK7gr0o4AVf9JZnEsFndqO0qTCyT-D-yBsWk0v" // CPI Router v2.1.0
  )
);

// deposit 1 TestRED to the TestRED/TestBLUE pool and get at least 1 nano LP token
const txParams = await router.getSingleSideProvideLiquidityJettonTxParams({
  userWalletAddress: USER_WALLET_ADDRESS,
  sendTokenAddress: JETTON_0_ADDRESS,
  sendAmount: toNano("1"),
  otherTokenAddress: JETTON_1_ADDRESS,
  minLpOut: "1",
  queryId: 123456,
});

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.

TON/Jetton pool deposit (two sides)

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

const USER_WALLET_ADDRESS = ""; // ! replace with your address
const JETTON_0_ADDRESS = "kQDLvsZol3juZyOAVG8tWsJntOxeEZWEaWCbbSjYakQpuYN5"; // TestRED

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

const router = client.open(
  DEX.v2_1.Router.CPI.create(
    "kQALh-JBBIKK7gr0o4AVf9JZnEsFndqO0qTCyT-D-yBsWk0v" // CPI Router v2.1.0
  )
);

const proxyTon = pTON.v2_1.create(
  "kQACS30DNoUQ7NfApPvzh7eBmSZ9L4ygJ-lkNWtba8TQT-Px" // pTON v2.1.0
);

const txParams = await Promise.all([
  // deposit 1 TON to the TON/TestRED pool and get at least 1 nano LP token
  router.getProvideLiquidityTonTxParams({
    userWalletAddress: USER_WALLET_ADDRESS,
    proxyTon,
    sendAmount: toNano("1"),
    otherTokenAddress: JETTON_0_ADDRESS,
    minLpOut: "1",
    queryId: 12345,
  }),
  // deposit 1 TestRED to the TON/TestRED pool and get at least 1 nano LP token
  router.getProvideLiquidityJettonTxParams({
    userWalletAddress: USER_WALLET_ADDRESS,
    sendTokenAddress: JETTON_0_ADDRESS,
    sendAmount: toNano("1"),
    otherTokenAddress: proxyTon.address,
    minLpOut: "1",
    queryId: 123456,
  }),
]);

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.

TON/Jetton pool deposit (single sides)

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

const USER_WALLET_ADDRESS = ""; // ! replace with your address
const JETTON_0_ADDRESS = "kQDLvsZol3juZyOAVG8tWsJntOxeEZWEaWCbbSjYakQpuYN5"; // TestRED

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

const router = client.open(
  DEX.v2_1.Router.CPI.create(
    "kQALh-JBBIKK7gr0o4AVf9JZnEsFndqO0qTCyT-D-yBsWk0v" // CPI Router v2.1.0
  )
);

const proxyTon = pTON.v2_1.create(
  "kQACS30DNoUQ7NfApPvzh7eBmSZ9L4ygJ-lkNWtba8TQT-Px" // pTON v2.1.0
);

// deposit 1 TON to the TON/TestRED pool and get at least 1 nano LP token
const txParams = await router.getSingleSideProvideLiquidityTonTxParams({
  userWalletAddress: USER_WALLET_ADDRESS,
  proxyTon,
  sendAmount: toNano("1"),
  otherTokenAddress: JETTON_0_ADDRESS,
  minLpOut: "1",
  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.

Introduction

In the SDK v1.0.0 release, we introduce some breaking changes. You can find the complete list of the release changes in the CHANGELOG.md file, but in this docs section, we will be focused on some real code snippet migration from the SDK v0.5.* to v1.0.0

Let's migrate the v0.5.* jetton to TON swap example code to the v1.0.0:

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

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

const tonToJettonTxParams = await router.buildSwapJettonToTonTxParams({
  userWalletAddress: "", // ! replace with your address
  offerJettonAddress: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  offerAmount: new TonWeb.utils.BN("1000000000"),
  proxyTonAddress: pTON.v1.address,
  minAskAmount: new TonWeb.utils.BN("1"),
  queryId: 12345,
});

TonWeb package replacement with @ton/ton

The main source of this release's breaking changes is the migration from the tonweb to the @ton/ton package. So, the first step is to add the @ton/ton package to your project. To do that, follow the installation step from their docs.

As a result of this step, we need to be able to create an instance of TonClient that @ton-ton package uses to make on-chain requests.

import { TonClient } from "@ton/ton";

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

Contract constructor interface change

Since the @ton package makes an on-chain request by injecting the provider into open contract methods, SDK contracts no longer need to require a tonApiClient in constructor parameters. So, the contract's constructor interface has been changed to accept the address as a first parameter and the configuration object as a second parameter.

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

type ContractsConstructorParameters = ConstructorParameters<
  typeof DEX.v1.Router
>;
// ^: [address: Address | string, (RouterV1Options | undefined)?]

That means router contract creation in the code we are migrating needed to be changed to the following:

- import TonWeb from 'tonweb';

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

Router.v1 has a known default address, so the first constructor parameter, in this case, is optional. For other contracts, there is no default address, so it should be specified

const pool = new DEX.v1.Pool(
  "EQCl-ax-5QC06ub096s2bqTbhYZWigZ1-FkJm2IVIMSazp7U" // STON/GEMSTON pool
);

If you specified custom gasConstants for a contract, it is still possible to do so. Only instead of passing them as part of the first constructor parameter object, you need to pass them in a second object

const pool = new DEX.v1.Pool(
+ 'EQCl-ax-5QC06ub096s2bqTbhYZWigZ1-FkJm2IVIMSazp7U',
  {
-    address: 'EQCl-ax-5QC06ub096s2bqTbhYZWigZ1-FkJm2IVIMSazp7U',
    gasConstants: {
        burn: DEX.v1.Pool.gasConstants.burn,
    }
  }
);

"Opening" of the contracts

The @ton/ton package needs to be opened for use in making on-chain requests from the contract.

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

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

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

build*TxParams methods renaming

All contracts build*TxParams methods were renamed to get*TxParams. This was needed to math @ton/ton package convention for methods that could make on-chain request

- const tonToJettonTxParams = await router.buildSwapJettonToTonTxParams({

+ const tonToJettonTxParams = await router.getSwapJettonToTonTxParams({

BN.js replacement with native BigInt

In the previous version of the SDK package, to represent the amount, we used BN.js, which came as a part of the TonWeb package and was accessible via TonWeb.utils.BN. @ton/ton package uses native javascript BigInt instead of BN.js.

And the migration is peaty easy - since the constructors of BN and BigInt are comparable. We only need to replace Class that represents the amount

-  offerAmount: new TonWeb.utils.BN('1000000000'),
+  offerAmount: BigInt('1000000000'),
-  minAskAmount: new TonWeb.utils.BN('1'),
+  minAskAmount: BigInt('1'),

Operations with pTON

Previously, every operation that worked with a native TON requested a proxyTonAddress. But since we are developing the next version of the proxyTon contract with some differences in the ton sending transaction instead of only the address, we need to know more about the proxyTon.

So now operations with native ton require the instance of pTON contracts.

const tonToJettonTxParams = await router.getSwapJettonToTonTxParams({
-  proxyTonAddress: pTON.v1.address,
+  proxyTon: new pTON.v1(),
});

txParams shape change and MessageData type drop

To better match @ton/ton package interfaces, we slightly changed the object's shape that returns from the get*TxParams methods. The change is only in names; the purpose of this field stayed unchanged. It describes the transaction that, if sent, will cause the requested action on the DEX.

This change lets us use the get*TxParams methods output directly in the @ton/ton send functionality.

Before

type TxParams = typeof tonToJettonTxParams;
// ^: { to: Address, gasAmount: BN, payload: Cell }

After

type TxParams = typeof tonToJettonTxParams;
// ^: { to: Address, value: BigInt, body?: Cell | null }

Because we switched from our MessageData interface to @ton/ton SenderArguments type, MessageData export from the SDK package was removed

Contracts method renaming

In v1.0.0, some of the contract methods were renamed:

Conclusion

And in the end this is a code we have migrated to

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

const client = new TonClient({
  endpoint: "https://ton-api.ston.fi/jsonRPC",
});

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

const tonToJettonTxParams = await router.getSwapJettonToTonTxParams({
    userWalletAddress: "", // ! replace with your address
    offerJettonAddress: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
    offerAmount: BigInt("1000000000"),
    proxyTon: new pTON.v1(),
    minAskAmount: BigInt("1"),
    queryId: 12345,
  });

This document explains how to populate and interpret the extra field in SwapChunk (as referenced in omniston-swap.md), specifically when using protocols like StonFiV1, StonFiV2, DeDust, or TonCo.

Overview

In the Omniston Swap protocol, each SwapChunk contains two fields for protocol-specific data:

• extra_version (integer) - Indicates the version of the data structure being used

• extra (bytes) - Contains the protocol-specific data as a base64-encoded byte array

These fields allow different DEX protocols to include their own parameters and configuration for executing swaps. This document describes the format of that data and how to encode it properly.

Protocol Definitions

message ExtraData {
  oneof extra {
    StonFiV1Extra ston_fi_v1 = 1;
    StonFiV2Extra ston_fi_v2 = 2;
    DeDustExtra de_dust = 3;
    TonCoExtra ton_co = 4;
  }
}

message StonFiV1Extra {
  string pool_address = 1;
  string min_ask_amount = 2;

  // Filled by Omniston service
  string recommended_min_ask_amount = 50;
}

message StonFiV2Extra {
  string pool_address = 1;
  string min_ask_amount = 2;

  // Filled by Omniston service
  string recommended_min_ask_amount = 50;
}

message DeDustExtra {
  string pool_address = 1;
  string min_ask_amount = 2;
  string referrer_address = 3;  // Specified in `referralAddress` swap parameter in DeDust SDK

  // Filled by Omniston service
  string recommended_min_ask_amount = 50;
}

message TonCoExtra {
  string pool_address = 1;
  string min_ask_amount = 2;
  string limit_sqrt_price = 3;

  // Filled by Omniston service
  string recommended_min_ask_amount = 50;
}

Field Descriptions

Common Fields

All protocol extras share these common fields:

• pool_address (string)

  • The address of the DEX pool contract that will execute the swap

  • This is specific to the token pair being swapped and the protocol being used

• min_ask_amount (string)

  • The minimum amount of ask tokens that must be received for this chunk

  • If the protocol cannot provide at least this amount, the swap will be aborted

  • Used to protect against slippage and ensure minimum received amount

• recommended_min_ask_amount (string)

  • The recommended minimum amount of ask tokens (filled by Omniston service)

  • This field provides an optimized slippage protection value calculated by the platform

  • Available for all protocols starting with extra version 1

Protocol-Specific Fields

DeDust Protocol

The DeDust protocol includes an additional field:

• referrer_address (string)

  • Optional address that may receive referral rewards/fees according to DeDust's rules

  • This is specified in the referralAddress parameter when using the DeDust SDK

TonCo Protocol

The TonCo protocol includes an additional field:

• limit_sqrt_price (string)

  • Square root price limit for the swap operation

  • Used to control price impact and provide additional slippage protection

  • This parameter is specific to TonCo's concentrated liquidity model

Usage Example

Here's an example of how to construct and encode the extra data for a StonFiV2 swap:

// 1. Create the protocol-specific extra data
const stonFiV2Extra = {
  pool_address: "EQA...", // Address of the StonFi pool
  min_ask_amount: "1000000", // Minimum tokens to receive
};

// 2. Wrap in ExtraData message
const extraData = {
  extra: {
    oneofKind: "ston_fi_v2",
    ston_fi_v2: stonFiV2Extra,
  },
};

// 3. Serialize to protobuf bytes
const extraBytes = ExtraData.encode(extraData).finish();

// 4. Base64 encode for JSON transport
const extraBase64 = Buffer.from(extraBytes).toString("base64");

// 5. Use in SwapChunk
const chunk = {
  protocol: "StonFiV2",
  offer_amount: "2000000",
  ask_amount: "1950000",
  extra_version: 1,
  extra: extraBase64,
};

Integration with Swap Flow

When the Omniston server processes a swap request:

1. It examines the protocol field of each SwapChunk to determine which DEX to use

2. Based on the extra_version, it knows how to decode the extra field

3. The decoded data provides the necessary parameters (pool address, minimum amounts, etc.) to execute the swap through the chosen DEX

For more details on the overall swap flow and how chunks fit into routes and steps, see omniston-swap.md.

Version History

• Version 1: Initial version supporting StonFiV1, StonFiV2, DeDust, and TonCo protocols. Note: Currently, only extra_version = 1 is supported for all protocols.

  • Added recommended_min_ask_amount field filled by Omniston service for optimized slippage protection

  • Added support for TonCo protocol with limit_sqrt_price parameter

See Also

• omniston-swap.md - Main swap protocol documentation

• omniston-nodejs.md - Node.js SDK usage

• omniston-react.md - React components and hooks

This guide explains how to become a resolver (Market Maker) in the Omniston protocol and integrate with its gRPC API.

Overview

A resolver is a service that provides token exchange rates and executes trades. To become a resolver, you need to:

1. Register by obtaining a Soul-Bound Token (SBT)

2. Connect to the gRPC API

3. Handle quote requests and trades

Registration Process

Step 1: Generate Keys

First, generate one or more Ed25519 key pairs that will be used for authentication:

Step 2: Prepare Metadata

Create a JSON document containing:

• Your resolver name

• Your public key(s)

Example:

{
  "name": "MyResolver",
  "publicKeys": [
    "b951254b184fae6906a61ab01e37296fbb28961494cacf7befac9f638fcfe40c",
    "9397ddd52a0d6033da4a32e654b4afbddcc5d832575e396c0a6f5b213faa199f"
  ]
}

Step 3: Submit Registration

1. Your metadata will be stored in an SBT NFT collection

2. You'll receive your SBT stake address for API authentication

Connecting to the API

Authentication

1. Create a connection payload:

message ConnectPayload {
  uint64 connect_timestamp = 1;  // Current timestamp in milliseconds
  string stake_address = 2;      // Your SBT stake address
}

1. Sign the payload:

• Serialize the ConnectPayload to bytes

• Sign using your Ed25519 private key

• Base64 encode the signature