Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This section contains SDK example for performing swap in DEX
In this section, to illustrate all three possible types of a swap, we will do following exchange chain
swap 1 TON to STON (ton to jetton swap)
swap STON to GEMSTON (jetton to jetton swap)
swap GEMSTON back to TON (jetton to ton swap)
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.
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.
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.
Below are recommended values for TON sent and forward gas for each type of the swap:
pTON
-> Jetton
swap_amount + 0.185
0.185
Jetton
-> Jetton
0.22
0.175
Jetton
-> pTON
0.17
0.125
pTON
-> Jetton
Jetton
-> Jetton
Jetton
-> pTON
This section contains glossary with common terminology used throughout this documentation
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.
While a digital asset can take many forms, the STON.fi Protocol supports jetton pairs.
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.
Digital assets that are stored in a STON.fi pool contract, and are able to be traded against by traders.
A smart contract deployed from a STON.fi that enables trading between two jettons.
A contract deployed by the STON.fi protocol that pairs two assets.
The price between the available buy and sell prices. In STON.fi protocol, this is the ratio of the two jettons reserves.
The difference between the mid-price and the execution price of a trade.
Fees that are rewarded to the protocol itself, rather than to liquidity providers.
Fees collected upon swapping which are rewarded to liquidity providers.
An amount the price moves in a trading pair between when a transaction is submitted and when it is executed.
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 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.
This section contains fee values used in STON.fi AMM
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 STON.fi protocol.
Download pdf Link
Current version: 0.6, released Aug 2023
This section contains the default list procedure description.
We are dedicated to building an open and transparent digital currency trading ecosystem, and we look forward to working with projects that share this vision. For that we have developer tools (DEX SDK) that allow you to deploy our DEX to anyone, anywhere. This allows to make your own pools, add tokens, and use any custom interface.
In the interface of our app, we prioritize the reputation of the assets and the availability of volumes to ensure our users have the best experience.
Consequently, we have established requirements for tokens to be included in our DEX's default list:
Formal review
Liquidity of $10,000 (in TON) paired with the token to be included
The inclusion of a new asset on STON.fi default token list is a multi-step process that involves a formal application procedure, a review by our team, and an initial liquidity check procedure.
This guide outlines the main workflow of the application, review, and process of adding tokens to the default list.
Application: The first step is to apply for inclusion in the default list on STON.fi. Projects must provide basic information about themselves through the application form, accessible via the link provided.
Review: After the application is submitted, our team reviews the provided information. We assess the project's compliance with our default list criteria and evaluate its potential for success on our platform.
Liquidity: If the internal review is successful, the next step is to check initial liquidity on the DEX. Note that the initial liquidity in the pool must be at least $10,000 (in TON) paired with the second token.
Public Inclusion: At the agreed-upon time, the initialized pools will be available in the public interface for trading.
To apply for inclusion in the default list on STON.fi, please follow the provided link and fill out the application form with the necessary information.
Our team will review your application and contact you if your project is selected for inclusion to the default token list. We are excited to see new projects on our platform and look forward to working with you.
Request listing Link
The STON.fi Docs
STON.fi 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.
STON.fi is live! See app.ston.fi
Website: https://ston.fi/
Web App: https://app.ston.fi/
Github: https://github.com/ston-fi/
Twitter: @ston_fi
Telegram: @stonfidex
Reddit: https://reddit.com/r/STONFi/
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.
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.
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.
This section contains basic description of STON.fi protocol
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.
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.
This section contains information about SDK for STON.fi protocol
Welcome to the STON.fi SDK docs section.
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.
SDK is built based on the @ton 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 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
Firstly install the @ton/ton package following their installation guide
Then, add SDK package using the package manager of your choice.
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.
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:
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 here. Try this app at sdk-demo-app.ston.fi
This section contains SDK reference for DEX
The remaining sections of the documentation will demonstrate specific examples of the DEX usage:
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.
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.
This document explains the logic behind STON.fi Jetton-to-Jetton DEX
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.
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.
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).
The wallet contract is a standard Jetton wallet and is used to hold the LP Jetton minted by Pools.
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.
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.
Dex v2 supports liquidity provision using only one token by automatically performing a swap before minting liquidity
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.
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.
Creation of a stableswap pool is handled directly by STON.fi and cannot be done by users.
This section contains SDK example for withdrawing liquidity from DEX
Burn all liquidity tokens to free liquidity from a pool
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.
This section contains SDK example for refunding undeposited liquidity in DEX
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 doc section about transaction sending guide with examples for different libraries.
This section contains SDK reference for DEX
The remaining sections of the documentation will demonstrate specific examples of the DEX usage:
This section contains SDK example for performing swap in DEX
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.
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.
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.
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.
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.
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.
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.
This section contains SDK example for refunding undeposited liquidity in DEX
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 doc section about transaction sending guide with examples for different libraries.
This section contains SDK example for withdrawing liquidity from DEX
Burn all liquidity tokens to free liquidity from a pool
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.
This section contains SDK example for staking tokens in Farm
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 doc section about transaction sending guide with examples for different libraries.
This section contains sdk methods reference
address
Address of the Router contract
gasConstants
getPoolAddress
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
token0
Address | string
The address of the router's wallet of first Jetton
token1
Address | string
The address of the router's wallet of second Jetton
Result
Returns an address of a pool for a specified pair of assets.
getPoolAddressByJettonMinters
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
token0
Address | string
The address of the first pool Jetton Minter
wallet
token1
Address | string
The address of the second pool Jetton Minter
wallet
Result
Returns an address of a pool for a specified pair of assets.
getPool
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
token0
Address | string
The address of the first pool Jetton Minter
wallet
token1
Address | string
The address of the second pool Jetton Minter
wallet
Result
Returns an instance of PoolV1
with specified Jetton token addresses.
getRouterData
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
Result
Returns structure containing current state of the router.
isLocked
boolean
true if transfer_notification
operations are locked (swap
, provide_lp
)
adminAddress
Address
Address of contract's admin account
tempUpgrade
Cell
A structure describing state of contract's code & admin upgrade; zero values indicate that no upgrade is pending
poolCode
Cell
Code of the router's liquidity pool contract
jettonLpWalletCode
Cell
Code of lp wallet contract
lpAccountCode
Cell
Code of lp account contract
createSwapBody
userWalletAddress
Address | string
User's address
minAskAmount
bigint | number | string
Minimum amount of tokens received (in basic token units)
askJettonWalletAddress
Address | string
Jetton router's wallet address of tokens to be received
referralAddress
Address | string | undefined
referral address
getSwapJettonToJettonTxParams
Build all data required to execute a jetton to jetton swap
transaction
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
userWalletAddress
Address | string
User's address
offerJettonAddress
Address | string
Jetton Minter
address of a token to be swapped
askJettonAddress
Address | string
Jetton Minter
address of a token to be received
offerAmount
bigint | number | string
Amount of tokens to be swapped (in basic token units)
minAskAmount
bigint | number | string
Minimum amount of tokens to be received (in basic token units)
referralAddress
Address | string | undefined
Referral address
gasAmount
bigint | number | string | undefined
Transaction gas
forwardGasAmount
bigint | number | string | undefined
Forward amount of gas for the next transaction (in nanoTons)
queryId
bigint | number | undefined
Query id
Result
to
Address
Address of the router's Jetton wallet for the swapped token
value
bigint
Recommended amount of TON (in nanoTons) sent as gas
body
Cell | null | undefined
Optional Cell
with data to be send
sendSwapJettonToJetton
getSwapJettonToTonTxParams
Build all data required to execute a jetton to ton swap
transaction
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
userWalletAddress
Address | string
User's address
offerJettonAddress
Address | string
Jetton Minter
address of a token to be swapped
proxyTon
PtonV1
instance of pTON contract
offerAmount
bigint | number | string
Amount of tokens to be swapped (in basic token units)
minAskAmount
bigint | number | string
Minimum amount of tokens to be received (in basic token units)
referralAddress
Address | string | undefined
Referral address
gasAmount
bigint | number | string | undefined
Transaction gas
forwardGasAmount
bigint | number | string | undefined
Forward amount of gas for the next transaction (in nanoTons)
queryId
bigint | number | undefined
Query id
Result
to
Address
Address of the router's Jetton wallet for the swapped token
value
bigint
Recommended amount of TON (in nanoTons) sent as gas
body
Cell | null | undefined
Optional Cell
with data to be send
sendSwapJettonToTon
getSwapTonToJettonTxParams
Build all data required to execute a ton to jetton swap
transaction
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
userWalletAddress
Address | string
User's address
proxyTon
PtonV1
instance of pTON contract
askJettonAddress
Address | string
Jetton Minter
address of a token to be received
offerAmount
bigint | number | string
Amount of tokens to be swapped (in basic token units)
minAskAmount
bigint | number | string
Minimum amount of tokens to be received (in basic token units)
referralAddress
Address | string | undefined
Referral address
forwardGasAmount
bigint | number | string | undefined
Forward amount of gas for the next transaction (in nanoTons)
queryId
bigint | number | undefined
Query id
Result
to
Address
Address of the router's Jetton wallet for the swapped token
value
bigint
Recommended amount of TON (in nanoTons) sent as gas
body
Cell | null | undefined
Optional Cell
with data to be send
sendSwapTonToJetton
createProvideLiquidityBody
routerWalletAddress
Address | string
Address of the router's Jetton token wallet
minLpOut
bigint | number | string
Minimum amount of created liquidity tokens (in basic token units)
getProvideLiquidityJettonTxParams
Collect all data required to execute a jetton provide_lp
transaction
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
userWalletAddress
Address | string
User's address
sendTokenAddress
Address | string
Address of the first Jetton token or a proxy ton contract
otherTokenAddress
Address | string
Address of the second Jetton token
sendAmount
bigint | number | string
Amount of the first/second tokens deposited as liquidity (in basic token units)
minLpOut
bigint | number | string
Minimum amount of created liquidity tokens (in basic token units)
gasAmount
bigint | number | string | undefined
Transaction gas
forwardGasAmount
bigint | number | string | undefined
Forward amount of gas for the next transaction (in nanoTons)
queryId
bigint | number | undefined
Query id
Result
to
Address
Address of the router's Jetton wallet for the swapped token
value
bigint
Recommended amount of TON (in nanoTons) sent as gas
body
Cell | null | undefined
Optional Cell
with data to be send
sendProvideLiquidityJetton
getProvideLiquidityTonTxParams
Collect all data required to execute a proxy ton provide_lp
transaction
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
userWalletAddress
Address | string
User's address
proxyTon
PtonV1
instance of pTON contract
otherTokenAddress
Address | string
Address of the second Jetton token
sendAmount
bigint | number | string
Amount of the first/second tokens deposited as liquidity (in basic token units)
minLpOut
bigint | number | string
Minimum amount of created liquidity tokens (in basic token units)
forwardGasAmount
bigint | number | string | undefined
Forward amount of gas for the next transaction (in nanoTons)
queryId
bigint | number | undefined
Query id
Result
to
Address
Address of the router's Jetton wallet for the swapped token
value
bigint
Recommended amount of TON (in nanoTons) sent as gas
body
Cell | null | undefined
Optional Cell
with data to be send
sendProvideLiquidityTon
address
Address of the Pool contract
gasConstants
getPoolData
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
Result
Returns structure containing current state of the pool.
reserve0
bigint
Amount of the first token (in basic token units)
reserve1
bigint
Amount of the second token (in basic token units)
token0WalletAddress
Address
Address of the first Jetton token
token1WalletAddress
Address
Address of the second Jetton token
lpFee
bigint
Liquidity pool fee value
protocolFee
bigint
Protocol fee
refFee
bigint
Referral fee
protocolFeeAddress
Address
Address for receiving protocol fees
collectedToken0ProtocolFee
bigint
Amount of collected protocol fees of the first token (in basic token units)
collectedToken1ProtocolFee
bigint
Amount of collected protocol fees of the second token (in basic token units)
Notes:
fee ratio is the value of fee divided by FEE_DIVIDER
(10000); so a fee of 1% has a value of 100
getExpectedOutputs
Estimate expected result of the amount of jettonWallet tokens swapped to the other type of tokens of the pool
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
amount
bigint | number | string
Amount of tokens to swap (in basic token units)
jettonWallet
Address | string
Token Jetton address (must be equal to one of the Jetton addresses of the pool)
Result
Returns structure with expected result of a token swap
jettonToReceive
bigint
Amount of tokens received (in basic token units)
protocolFeePaid
bigint
Amount tokens paid for protocol fees (in basic token units)
refFeePaid
bigint
Amount tokens paid for referral fees (in basic token units)
getExpectedTokens
Estimate an expected amount of lp tokens minted when providing liquidity.
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
amount0
bigint | number | string
Amount of tokens for the first Jetton (in basic token units)
amount1
bigint | number | string
Amount of tokens for the second Jetton (in basic token units)
Result
Returns an estimated amount of liquidity tokens to be minted
getExpectedLiquidity
Estimate expected liquidity freed upon burning liquidity tokens.
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
jettonAmount
bigint | number | string
Amount of liquidity tokens (in basic token units)
Result
Returns structure with expected freed liquidity
amount0
bigint
Amount of tokens for the first Jetton (in basic token units)
amount1
bigint
Amount of tokens for the second Jetton (in basic token units)
getLpAccountAddress
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
ownerAddress
Address | string
Address of a user
Result
Function getLpAccountAddress
returns the lp account address of a user
getLpAccount
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
ownerAddress
Address | string
Address of a user
Result
returns an instance of LpAccountV1
getJettonData
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
Result
Returns a structure with Jetton data
totalSupply
bigint
Total token supply (in basic token units)
isMintable
boolean
If mintable
adminAddress
Address
Admin address
jettonContentUri
string
Offchain uri with Jetton data
jettonWalletCode
Cell
Code of the lp Jetton wallet
getWalletAddress
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
ownerAddress
Address | string
Address of a user
Result
returns a calculated lp wallet address of a user
getJettonWallet
Arguments
ownerAddress
Address | string
Address of a user
ownerAddress
Address | string
Address of a user
Result
Function getJettonWallet
returns a JettonWallet
instance for an address returned by getWalletAddress
createCollectFeesBody
getCollectFeeTxParams
Build all data required to execute a collect_fees
transaction.
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
gasAmount
bigint | number | string | undefined
Transaction gas
queryId
bigint | number | undefined
Query id
Result
to
Address
Address of the router's Jetton wallet for the swapped token
value
bigint
Recommended amount of TON (in nanoTons) sent as gas
body
Cell | null | undefined
Optional Cell
with data to be send
Notes:
param
is entirely optional
the default value for gasAmount
is equal to 1.1 TON
sendCollectFees
createBurnBody
getBurnTxParams
Build all data required to execute a burn
transaction.
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
amount
bigint | number | string
Lp tokens to burn
responseAddress
Address | string
Excesses address
gasAmount
bigint | number | string | undefined
Transaction gas
queryId
bigint | number | undefined
Query id
sendBurn
address
Address of the LpAccount contract
gasConstants
getLpAccountData
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
Result
Returns structure containing current state of the lp account.
userAddress
Address
Owner's address
poolAddress
Address
Pool's address
amount0
bigint
Balance of the first Jetton token (in basic token units)
amount1
bigint
Balance of the second Jetton token (in basic token units)
createRefundBody
getRefundTxParams
Build all data required to execute a refund_me
transaction.
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
gasAmount
bigint | number | string | undefined
Transaction gas
queryId
bigint | number | undefined
Query id
Result
to
Address
Address of the router's Jetton wallet for the swapped token
value
bigint
Recommended amount of TON (in nanoTons) sent as gas
body
Cell | null | undefined
Optional Cell
with data to be send
sendRefund
createDirectAddLiquidityBody
getDirectAddLiquidityTxParams
Build all data required to execute a direct_add_liquidity
transaction.
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
amount0
bigint | number | string
Amount of the first Jetton tokens (in basic token units)
amount1
bigint | number | string
Amount of the second Jetton tokens (in basic token units)
minimumLpToMint
bigint | number | string | undefined
Minimum amount of received liquidity tokens (in basic token units)
gasAmount
bigint | number | string | undefined
Transaction gas
queryId
bigint | number | undefined
Query id
Result
to
Address
Address of the router's Jetton wallet for the swapped token
value
bigint
Recommended amount of TON (in nanoTons) sent as gas
body
Cell | null | undefined
Optional Cell
with data to be send
Notes:
addition of liquidity will fail if a user should receive less than minimumLpToMint
of lp tokens as a result
the default value for gasAmount
is equal to 0.3 TON
sendDirectAddLiquidity
createResetGasBody
getResetGasTxParams
Build all data required to execute a reset_gas
transaction.
Arguments
provider
ContractProvider
Instance of @ton/core
contract provider
gasAmount
bigint | number | string | undefined
Transaction gas
queryId
bigint | number | undefined
Query id
Result
to
Address
Address of the router's Jetton wallet for the swapped token
value
bigint
Recommended amount of TON (in nanoTons) sent as gas
body
Cell | null | undefined
Optional Cell
with data to be send
Notes:
params
is entirely optional
the default value for gasAmount
is equal to 0.3 TON
sendResetGas
This section contains SDK reference for Farm contracts
The remaining sections of the documentation will demonstrate specific examples of the Farm usage:
This section contains SDK example for unstaking tokens in Farm
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 doc section about transaction sending guide with examples for different libraries.
This section contains SDK example for claiming rewards in Farm
Claim rewards 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 doc section about transaction sending guide with examples for different libraries.
This section contains a guide for sending transactions in TON blockchain
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:
This section contains migration guide for SDK v0.5.* -> v1.0.0
In the SDK v1.0.0
release, we introduce some breaking changes. You can find the complete list of the release changes in the 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
:
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.
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.
That means router contract creation in the code we are migrating needed to be changed to the following:
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
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
The @ton/ton package needs to be opened for use in making on-chain requests from the contract.
build*TxParams
methods renamingAll 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
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
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.
txParams
shape change and MessageData
type dropTo 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
After
Because we switched from our MessageData
interface to @ton/ton SenderArguments
type, MessageData
export from the SDK package was removed
In v1.0.0
, some of the contract methods were renamed:
And in the end this is a code we have migrated to
This section contains SDK example for destroying unstaked farm NFT
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.
This section contains a guide for sending transactions in TON blockchain using @tonconnect
Tonconnect package uses the sendTransaction
method to send a transaction to the blockchain. An example of the usage is on their .
This section contains a guide for sending transactions in TON blockchain using tonweb
Tonweb package uses the transfer
method to send a transaction to the blockchain. An example of the usage is on their .
This section contains SDK example for performing fee withdrawal from the vault contract
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.
This section contains a guide for sending transactions in TON blockchain using @ton/ton
Ton package uses the sendTransfer
method to send a transaction to the blockchain. An example of the usage is on their .
The main source of this release's breaking changes is the migration from the to the package. So, the first step is to add the @ton/ton package to your project. To do that, .
v0.5.*
v1.0.0
RouterV1.getData
RouterV1.getRouterData
PoolV1.getData
PoolV1.getPoolData
LpAccountV1.getData
LpAccountV1.getLpAccountData
This section contains SDK reference for DEX
The remaining sections of the documentation will demonstrate specific examples of the DEX usage:
This section contains SDK example for refunding undeposited liquidity in DEX
Refund tokens that were sent to LP account but weren't added to a liquidity pool yet
This section contains SDK example for performing swap in DEX
In this section, to illustrate all three possible types of a swap, we will do following exchange chain
swap 1 TON to STON (ton to jetton swap)
swap STON to GEMSTON (jetton to jetton swap)
swap GEMSTON back to TON (jetton to ton swap)
Below are recommended values for TON sent and forward gas for each type of the swap:
pTON
-> Jetton
swap_amount + 0.215
0.215
Jetton
-> Jetton
0.265
0.205
Jetton
-> pTON
0.185
0.125
pTON
-> Jetton
Jetton
-> Jetton
Jetton
-> pTON
This section contains information about SDK for STON.fi protocol
v0.5
version of the SDK is deprecated. Please use latest SDK version instead
Welcome to the STON.fi SDK docs section.
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.
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
To install SDK via npm
use:
To install SDK with yarn
use:
To install SDK with pnpm
use:
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:
This section contains SDK example for withdrawing liquidity from DEX
Burn all liquidity tokens to free liquidity from a pool
This section contains SDK example for claiming rewards in Farm
Claim rewards from Farm NFT
This section contains SDK example for unstaking tokens in Farm
Unstake funds from Farm NFT
This section contains SDK example for destroying unstaked farm NFT
Destroy of the Farm NFT is a transfer of the Farm NFT from the user wallet to the zero address.
This section contains a guide for sending transactions in TON blockchain
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:
This section contains SDK example for staking tokens in Farm
Staking of the LP tokens in Farm
This section contains a guide for sending transactions in TON blockchain using @tonconnect
Tonconnect package uses the sendTransaction
method to send a transaction to the blockchain. An example of the usage is on their DOCs.
This section contains a guide for sending transactions in TON blockchain using @ton/ton
Ton package uses the sendTransfer
method to send a transaction to the blockchain. An example of the usage is on their README.
This section contains a guide for sending transactions in TON blockchain using tonweb
Tonweb package uses the transfer
method to send a transaction to the blockchain. An example of the usage is on their README.
This section contains SDK reference for Farm contracts
The remaining sections of the documentation will demonstrate specific examples of the Farm usage:
This section describes the usage of get methods
Example of usage of various get methods of the SDK.
This section contains SDK example for refunding undeposited liquidity in DEX
Refund tokens deposited on liquidity pool account but not added to a liquidity pool yet.
This section describes how to create a custom router revision
Create a custom router revision.
This section contains SDK reference for DEX
v0.4
version of the SDK is deprecated. Please use latest SDK version instead
The remaining sections of the documentation will demonstrate specific examples of the SDK usage:
This section contains SDK example for withdrawing liquidity from DEX
Free liquidity by buring liquidity pool tokens.
This section contains migration guide for SDK v0.4.* -> v0.5.*
In the SDK v0.5
release, we introduce some breaking changes. You can find the full 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.4
to v0.5
Let's migrate the v0.4
jetton to TON swap example code to the v0.5
:
The first thing you will face after the SDK update is that Module '"@ston-fi/sdk"' has no exported member Router
.
This is because contracts (such as Router
, Pool
, LpAccount
, etc) now no longer exported by their names. We start to use the export of domain related objects that will contain all the contracts.
At the current state SDK exports 3 domain object DEX
, FARM
, pTON
.
So the first required change to our code is to replace the import of Router
contract with the DEX
object.
Because multiple versions of the contracts appeared with uncomparable interfaces, we were forced to drop the architecture with revisions and the root class that obtained multiple revisions.
before:
after:
If you use extends or overrides contract revisions from the SDK anywhere in your code, you will now need to override the contract class instead.
If you use the override of the revision to define custom gas constants, it's now possible to pass gas constants as constructor parameters.
Since we dropped revisions but still need to be able to separate different contracts, every contract now provides the statice field version
. And to math this, *_REVISION
enums was renamed to *_VERSION
.
Now you can use it like this:
*_VERSION
enum values is in lover case (v1
) to match the STON.fi API responses
Back to our code - you can just remove import and usage of the ROUTER_REVISION
completely and instead, to determine witch version of the DEX contract you would like to use, use version key of the domain object (DEX
in this case)
For contracts with known addresses (for example, a router), the address is available as a static field on the class and is no longer required to be specified in the constructor.
The following changes need to be made on this step
All contract constructors now require 1 object with tonApiClient
field to be passed. tonApiClient
is a name for what in TonWeb is named provider
.
Optionally, you can pass an instance of stonApiClient
. This is a class from @ston-fi/api
package. If it is passed, STON.fi public REST API will be used to fetch data instead of using direct on-chain methods called via TON API.
At the current state of the package development, this client is optional, but we expect it to be required in the future when it no longer is possible to get some data required for the SDK to work from on-chain and
In v0.5
, some of the contract methods were renamed:
v0.4
v0.5
buildSwapJettonTxParams
buildSwapJettonToJettonTxParams
& buildSwapJettonToTonTxParams
buildSwapProxyTonTxParams
buildSwapTonToJettonTxParams
buildProvideLiquidityProxyTonTxParams
buildProvideLiquidityTonTxParams
Our code snippet using renamed fn buildSwapJettonTxParams
that was split in two: buildSwapJettonToJettonTxParams
& buildSwapJettonToTonTxParams
. Since we are swapping a jetton to TON, we will use a new fn buildSwapJettonToTonTxParams
buildSwapJettonToTonTxParams
fn now explicitly requires us to pass the address of the pTON contract to be used in the swap. Previously, it required the same, but under the askJettonAddress
name, that was confusing.
Because pTON class is now exported from the SDK we can use address from the pTON contract instead of a hardcoded string value in our code
And in the end this is a code we have migrated to
This section contains api reference of the lp wallet contract
This is a standard Jetton token wallet for holding liquidity tokens. Only specific modifications for this implementation will be described.
burn
(0x595f07bc)Burn an amount of liquidity tokens.
Sends a message with burn_notification
op code to the router contract with the amount of token burnt.
This section contains api reference of the lp account contract
get_lp_account_data
Returns current state of the lp account: owner address, pool address and amount of both Jetton tokens.
None
Returns the current state of the lp account.
Return structure
On-chain counterparts of getter methods.
getter_lp_account_data
(0x1d439ae0)Sends a message with current state of the lp account. On-chain equivalent of get_lp_account_data
.
None
Sends a message with current state of the lp account to sender_address
Handles incoming messages from a pool
add_liquidity
(0x3ebe5431)Stores the sent amount of tokens by the user to be added as new liquidity. Upon receiving an appropriate amount of both tokens sends a message with those amounts to a pool to be added as new liquidity. The automatic liquidity addition happens only if the amount of both tokens if greater than 1000 and non-zero min_lp_out
was specified, otherwise the user can keep increasing the amount of stored tokens.
Notes:
addition of liquidity will fail if a user should receive less than min_lp_out
of lp tokens as a result
Sends a message to the pool with cb_add_liquidity
op
Notes:
addition of liquidity will fail if a user should receive less than min_lp_out
of lp tokens as a result
Handles incoming messages from a user
refund_me
(0xbf3f447)Initiates a refund of stored tokens by add_liquidity
if the user decides to cancel the addition of new liquidity. The amount of stored tokens will be sent to the pool which will initiate a transfer back to the user.
None
Sends a message with cb_refund_me
op code and amount of stored tokens to a pool. The pool will send a message to refund those tokens back to the user.
direct_add_liquidity
(0x4cf82803)Initiates an addition of new liquidity to a pool with a specified amount of both tokens and a minimum amount of received liquidity. The operation is successful only if there's an equal or greater amount of both tokens stored in the account (the amount of both tokens must be greater than 1000). This method is useful if an automatic liquidity addition has not been triggered upon deposition of tokens.
Notes:
addition of liquidity will fail if a user should receive less than min_lp_out
of lp tokens as a result
min_lp_out
value must be greater than zero for this operation to proceed
Sends a message with cb_add_liquidity
op code and amount of both tokens to be added as new liquidity.
Notes:
addition of liquidity will fail if a user should receive less than min_lp_out
of lp tokens as a result
reset_gas
(0x42a0fb43)Updates the amount of $TON (in nanoTons) on the lp account to REQUIRED_TON_RESERVE
(10000000) of the account. The remaining $TON will be sent back to the user_address
None
Sends an empty message back to the user with the remaining $TON
op
uint32
Operation code is equal to burn
query_id
uint64
Query id
amount
coins
Amount of coins to burn (in basic token units)
response_destination
address
Address of a user
user_address
address
0
Owner's address
pool_address
address
1
Pool's address
amount0
coins
2
Balance of th e first Jetton token (in basic token units)
amount1
coins
3
Balance of the second Jetton token (in basic token units)
getter_lp_account_data
0x1d439ae0
Sends a message with the current state of the pool
op
uint32
Operation code equal to getter_lp_account_data
query_id
uint64
Query id
user_address
address
Owner's address
pool_address
address
Pool's address
amount0
coins
Balance of the first Jetton token (in basic token units)
amount1
coins
Balance of the second Jetton token (in basic token units)
add_liquidity
0x3ebe5431
Add liquidity
new_amount0
coins
Amount of the first Jetton tokens added (in basic token units)
new_amount1
coins
Amount of the second Jetton tokens added (in basic token units)
min_lp_out
coins
Minimum required amount of received new liquidity tokens (in basic token units)
op
uint32
Operation code, equal to cb_add_liquidity
query_id
uint64
Query id
amount0
coins
Amount of the first Jetton tokens added (in basic token units)
amount1
coins
Amount of the second Jetton tokens added (in basic token units)
user_address
address
Owner's address
min_lp_out
coins
Minimum amount of received liquidity tokens (in basic token units)
refund_me
0xbf3f447
Return previously sent tokens back to the user
direct_add_liquidity
0x4cf82803
Directly add liquidity with specified amount of tokens and a minimum amount of received liquidity tokens
reset_gas
0x42a0fb43
Reset gas
op
uint32
Operation code
query_id
uint64
Query id
amount0
coins
Amount of the first Jetton tokens (in basic token units)
amount1
coins
Amount of the second Jetton tokens (in basic token units)
user_address
address
Owner's address
amount0
coins
Amount of the first Jetton tokens (in basic token units)
amount1
coins
Amount of the second Jetton tokens (in basic token units)
min_lp_out
coins
Minimum amount of received liquidity tokens (in basic token units)
op
uint32
Operation code
query_id
uint64
Query id
am0
coins
Amount of the first Jetton tokens (in basic token units)
am1
coins
Amount of the second Jetton tokens (in basic token units)
user_address
address
Owner's address
min_lp_out
coins
Minimum amount of received liquidity tokens (in basic token units)
WORKCHAIN
0
Workchain id
REQUIRED_TON_RESERVE
10000000
Amount of $TON (in nanoTons) to be left on the lp account contract as gas
This section describes different op codes of AMM smart contracts
This section describes different op codes of AMM smart contracts v2
The section contains separate documents for each smart contract used in AMM:
Definitions of terminology used can be found in Glossary
Example schemes can be found here:
A table with DEX v2 op codes:
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
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 fees are stored in Vault
contract
custom referral fee value in each swap (maximum 1%)
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
)
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
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
This section contains SDK example for performing swap in DEX
Perform a swap operation.
Perform a swap operation using proxy-ton.
Below are recommended values for TON sent and forward gas for each type of the swap:
Jetton
-> Jetton
0.265
0.205
Jetton
-> pTON
0.185
0.125
pTON
-> Jetton
swap_amount + 0.215
0.215
Jetton
-> Jetton
Jetton
-> pTON
pTON
-> Jetton
This section contains api reference of the lp wallet contract
This is a standard Jetton token wallet for holding liquidity tokens. Only specific modifications for this implementation will be described.
burn
(0x595f07bc)Burn an amount of liquidity tokens.
op
uint32
Operation code is equal to burn
query_id
uint64
Query id
amount
coins
Amount of coins to burn (in basic token units)
response_destination
address
Address of a user
custom_payloads
maybe_ref
Payloads for token0 and token1
payload_0
maybe_ref
Payload used for amount0
; can be cross_swap
payload_1
maybe_ref
Payload used for amount1
; can be cross_swap
Sends a message with burn_notification_ext
op code to the router contract with the amount of token burnt.
This section contains api reference of the vault contract
Check examples for in-depth message flow.
get_vault_data
Returns Vault
data
None
Returns VaultData
structure containing current state of the Vault
.
RouterData
structure
owner_address
address
0
Owner of this Vault
token_address
address
1
Address of Router
's jetton wallet for s token'
router_address
address
2
Router
's address
deposited_amount
bigint
3
Amount of tokens collected
Handles calls from the Vault
owner
withdraw_fee
(0x354bcdf4)Burn an amount of liquidity tokens.
op
uint32
Operation code
query_id
uint64
Query id
Sends a message with vault_pay_to
op code to the router contract with the amount of token to be payed.
Handles calls from the Router
owner
deposit_ref_fee
(0x0490f09b)Increase ref fee tracker for the user.
op
uint32
Operation code
query_id
uint64
Query id
jetton_amount
bigint
Amount of the tokens
excesses_address
address
Address to receive TON excesses
Sends excesses to excesses_address
.
This section contains api reference of the lp account contract
get_lp_account_data
Returns current state of the LpAccount
.
None
Returns LpAccountData
structure containing current state of the lp account.
LpAccountData
structure
user_address
address
0
Owner's address
pool_address
address
1
Pool's address
amount0
coins
2
Balance of the first Jetton token (in basic token units)
amount1
coins
3
Balance of the second Jetton token (in basic token units)
On-chain counterparts of getter methods.
getter_lp_account_data
0x24cfc100
Sends a message with the current state of the pool
getter_lp_account_data
(0x24cfc100)Sends a message with current state of the lp account. On-chain equivalent of get_lp_account_data
.
None
Sends a message with current state of the lp account to sender_address
op
uint32
Operation code equal to getter_lp_account_data
query_id
uint64
Query id
user_address
address
Owner's address
pool_address
address
Pool's address
amount0
coins
Balance of the first Jetton token (in basic token units)
amount1
coins
Balance of the second Jetton token (in basic token units)
Handles incoming messages from a pool
add_liquidity
0x50c6a654
Add liquidity
add_liquidity
(0x50c6a654)Stores the sent amount of tokens by the user to be added as new liquidity. Upon receiving an appropriate amount of both tokens sends a message with those amounts to a pool to be added as new liquidity. The automatic liquidity addition happens only if the amount of both tokens if greater than 1000 and non-zero min_lp_out
was specified, otherwise the user can keep increasing the amount of stored tokens.
new_amount0
coins
Amount of the first Jetton tokens added (in basic token units)
new_amount1
coins
Amount of the second Jetton tokens added (in basic token units)
min_lp_out
coins
Minimum required amount of received new liquidity tokens (in basic token units)
fwd_amount
coins
Forward amount used to send custom_payload
(if present) in transfer_notification
both_positive
uint1
Trigger liquidity deposit only if both token amounts are non-zero
to_address
address
Owner of new liquidity tokens
custom_payload
maybe_ref
Payload sent in transfer_notification
upon receiving tokens
additional_fields
ref
See table below
refund_address
address
Address of the owner of LpAccount
where tokens will be refunded if liquidity mint wasn't successful
excess_address
address
Address where all TON excesses will be sent
Notes:
addition of liquidity will fail if a user should receive less than min_lp_out
of lp tokens as a result
Sends a message to the pool with cb_add_liquidity
op
op
uint32
Operation code, equal to cb_add_liquidity
query_id
uint64
Query id
amount0
coins
Amount of the first Jetton tokens added (in basic token units)
amount1
coins
Amount of the second Jetton tokens added (in basic token units)
user_address
address
Owner's address
min_lp_out
coins
Minimum amount of received liquidity tokens (in basic token units)
fwd_amount
coins
Forward amount used to send custom_payload
(if present) in transfer_notification
custom_payload
maybe_ref
Payload sent in transfer_notification
upon receiving tokens
additional_data
ref
See table below
to_address
address
Owner of new liquidity tokens
refund_address
address
Address of the owner of LpAccount
where tokens will be refunded if liquidity mint wasn't successful
excess_address
address
Address where all TON excesses will be sent
Notes:
addition of liquidity will fail if a user should receive less than min_lp_out
of lp tokens as a result
LpAccount
is deleted upon sending this message (Pool
always sends msgs with state_init
)
Handles incoming messages from a user
refund_me
0x132b9a2c
Return previously sent tokens back to the user
direct_add_liquidity
0x0ff8bfc6
Directly add liquidity with specified amount of tokens and a minimum amount of received liquidity tokens
reset_gas
0x29d22935
Reset gas
refund_me
(0x132b9a2c)Initiates a refund of stored tokens by add_liquidity
if the user decides to cancel the addition of new liquidity. The amount of stored tokens will be sent to the pool which will initiate a transfer back to the user.
None
Sends a message with cb_refund_me
op code and amount of stored tokens to a pool. The pool will send a message to refund those tokens back to the user.
op
uint32
Operation code
query_id
uint64
Query id
amount0
coins
Amount of the first Jetton tokens (in basic token units)
amount1
coins
Amount of the second Jetton tokens (in basic token units)
user_address
address
Owner's address
payload_0
maybe_ref
Payload used for amount0
; can be cross_swap
payload_1
maybe_ref
Payload used for amount1
; can be cross_swap
direct_add_liquidity
(0x0ff8bfc6)Initiates an addition of new liquidity to a pool with a specified amount of both tokens and a minimum amount of received liquidity. The operation is successful only if there's an equal or greater amount of both tokens stored in the account (the amount of both tokens must be greater than 1000). This method is useful if an automatic liquidity addition has not been triggered upon deposition of tokens.
amount0
coins
Amount of the first Jetton tokens (in basic token units)
amount1
coins
Amount of the second Jetton tokens (in basic token units)
min_lp_out
coins
Minimum amount of received liquidity tokens (in basic token units)
fwd_amount
coins
Forward amount used to send custom_payload
(if present) in transfer_notification
to_address
address
Owner of new liquidity tokens
custom_payload
maybe_ref
Payload sent in transfer_notification
upon receiving tokens
additional_fields
ref
See table below
refund_address
address
Address of the owner of LpAccount
where tokens will be refunded if liquidity mint wasn't successful
excess_address
address
Address where all TON excesses will be sent
Notes:
addition of liquidity will fail if a user should receive less than min_lp_out
of lp tokens as a result
min_lp_out
value must be greater than zero for this operation to proceed
Sends a message with cb_add_liquidity
op code and amount of both tokens to be added as new liquidity.
reset_gas
(0x29d22935)Updates the amount of TON (in nanoTons) on the lp account to storage_fee::lp_account
(10000000) of the account. The remaining TON will be sent back to the user_address
None
Sends an empty message back to the user with the remaining TON
storage_fee::lp_account
1000000
Amount of TON (in nanoTons) to be left on the lp account contract as gas
This section contains information about public DEX API for STON.fi protocol
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.
DEX API live here
Currently, there are no limits for DEX API use.
You can always found detailed information about the DEX API in
To simplify DEX API integration in your projects, we also have a tiny
This section contains example schemes Vault operations
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.
Bob
is user doing the swap, Alice
is referral, Send
is send token, Receive
is receive token.
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)
This section contains example schemes for swap operations
Simple swap of one token to another.
Bob
is user doing the swap, Alice
is referral, Send
is send token, Receive
is receive token.
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.
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 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.
This section contains example schemes for liquidity provision
Liquidity provision is done via 2 transactions: deposit of the first token and deposit of the second token.
The amount of the first token sent is stored on a user's lp account awaiting a transaction 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
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
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)
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.
Liquidly is withdrawn from a pool by burning lp tokens, a user then receives both pool tokens based on the current exchange rate.
A user can deposit liquidity after it was refunded to lp account without doing a withdraw.
This section contains information about OMNISTON protocol
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.
Omniston demo App is live! See
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
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.
Omniston SDK packages for developers:
For instructions on performing a swap using the Omniston protocol, see the .
for JavaScript/TypeScript applications.
for use in React or Next.js applications.
for application developers.
This section contains api reference of the router contract
get_vault_address
Returns an address of a vault for a specified asset and user.
user
address
0
The address of the Vault
's owner
token
address
1
The address of the Router
's jetton wallet
Returns VaultV2
object for Vault
's' address.
get_pool_address
Returns an address of a pool for a specified pair of assets.
It's necessary to specify addresses of Jetton wallets of the Router
as the arguments of this method. These addresses can be retrieved with get_wallet_address
of the Jetton minter.
token0
address
0
The address of the Router
's wallet of first Jetton
token1
address
1
The address of the Router
's wallet of second Jetton
Returns Pool
address.
get_router_data
Returns the current state of the Router
None
Returns RouterData
structure containing current state of the Router
.
RouterData
structure
id
uint32
0
Router
id
dex_type
string
1
Router
type
is_locked
bool
2
true if transfer_notification
operations are locked (swap
, provide_lp
)
admin_address
address
3
Address of contract's admin account
temp_upgrade
cell
4
A structure describing state of contract's code & admin upgrade; zero values indicate that no upgrade is pending
pool_code
cell
5
Code of the Router
's liquidity pool contract
jetton_lp_wallet_code
cell
6
Code of lp wallet contract
lp_account_code
cell
7
Code of lp account contract
vault_code
cell
8
Code of lp account contract
Notes:
possible dex_type
values:
constant_product
stableswap
get_router_version
Returns the current Router
version
None
Returns VersionData
structure containing Router
version.
RouterData
structure
major
uint
0
Major version
minor
uint
1
Minor version
development
string
2
Contains additional version info
transfer_notification
(0x7362d09c)Messages received from Jetton wallets belonging to the Router
upon getting a token transfer from a user. The user must include a custom payload with additional op code (either swap
or provide_lp
) and appropriate data in order for those messages to be processed correctly.
op
uint32
Operation code; equal to transfer_notification
query_id
uint64
Query id
jetton_amount
coins
Jetton amount (in basic token units)
from_user
address
User address
payload
cell
Cell with data
payload
bodytransferred_op
uint32
Additional operation code
token_wallet1
address
The address of the Router
's wallet of second Jetton
Notes:
payload
contains other fields depending on which op code is called
swap
0x6664de2a
Swap one type of Jetton tokens for another
provide_lp
0x37c096df
Provide liquidity; route call to the correct pool
swap
(0x6664de2a)Swap tokens. This message is received when the Router's Jetton token wallet sends a message upon confirmation of token transfer from a user with a custom payload. The Router
then sends a swap
message to the appropriate pool contract address.
Check examples for in-depth message flow.
payload
bodyop
uint32
Swap op
other_token_wallet
address
Address of the other Router
token wallet
refund_address
address
Address where refund will be sent if swap fails
excesses_address
address
Address where TON excesses will be sent
deadline
uint64
Timestamp of execution deadline for this tx
additional_data
cell
Cell with additional data
additional_data
bodymin_out
coins
Minimum required amount of tokens to receive
receiver_address
address
Address where tokens will be sent after swap
fwd_gas
coins
Gas used to forward a message in transfer_notification
after swap if custom_payload
is present
custom_payload
maybe_ref
Payload sent in transfer_notification
after swap
refund_fwd_gas
coins
Gas used to forward a message in transfer_notification
if swap fails if refund_payload
is present
refund_payload
maybe_ref
Payload sent in transfer_notification
if swap fails
ref_fee
uint16
Referral fee
referral_address
address
Referral address
Notes:
swap will fail if a user should receive less than min_out
of tokens as a result
max allowed value of ref_fee
is 100 (1%)
Sends a message with op swap
to Pool
provide_lp
(0x37c096df)Provide liquidity for a pool. This message is received when Router's token wallet sends a message upon confirmation of token transfer from a user with a custom payload. The Router
then sends a provide_lp
message to the appropriate pool contract address.
Check examples for in-depth message flow.
payload
bodyop
uint32
Provide lp op
other_token_wallet
address
Address of the other Router
token wallet
refund_address
address
Address where refund will be sent if swap fails
excesses_address
address
Address where TON excesses will be sent
deadline
uint64
Timestamp of execution deadline for this tx
additional_data
cell
Cell with additional data
additional_data
bodymin_lp_out
coins
Minimum required amount of lp tokens to receive
receiver_address
address
Address where lp tokens will be sent
both_positive
uint1
Trigger liquidity deposit only if both token amounts are non-zero
fwd_gas
coins
Gas used to forward a message in transfer_notification
after mint if custom_payload
is present
custom_payload
maybe_ref
Payload sent in transfer_notification
after lp mint
Sends a message with op provide_lp
to a liquidity pool
On-chain counterparts of getter methods
getter_pool_address
0x2993ade0
Sends a message with a pool address for a requested token pair; counterpart to get_pool_address
getter_pool_address
(0x2993ade0)Sends a message with an address of a pool for a specified pair of assets; counterpart to get_pool_address
token0
address
The address of the Router
's wallet of first Jetton
token1
address
The address of the Router
's wallet of second Jetton
Sends a message back to the sender with the pool address
op
uint32
Operation code equal to getter_pool_address
query_id
uint64
Query id
pool_address
address
Address of a pool
Handles governance message from admin to change pool parameters.
The admin can lock/unlock trading on all pools, change fees on a certain pool, upgrade the Router
code, etc.
set_fees
0x58274069
Change fee parameters of a pool
reset_pool_gas
0x66d0dff2
Update the amount of TON (in nanoTons) on a pool to storage_fee::router
of a pool
update_pool_status
0x2af4607c
Change Pool
status
update_status
0x38a6022f
Change Router
status
init_code_upgrade
0x03601fc8
Initiate code upgrade for the Router
init_admin_upgrade
0x0b02fd5b
Initiate admin change for the Router
cancel_admin_upgrade
0x72d6b3b4
Cancel an admin change
cancel_code_upgrade
0x1f72111a
Cancel a code upgrade
finalize_upgrades
0x4e6707b7
Finalize upgrades of the Router
code and admin change
reset_gas
0x29d22935
Update the amount of TON (in nanoTons) on the Router
to storage_fee::router
of the Router
set_params
0x2b8b3b62
Change pool-specific parameters
set_fees
(0x58274069)Change fees of a pool including liquidity pool fees, protocol fees and referral fees. It's necessary to provide correct Jetton token addresses for a target liquidity pool.
new_lp_fee
uint16
New liquidity pool fee ratio
new_protocol_fee
uint16
New protocol fee ratio
new_protocol_fee_address
address
Address for receiving protocol fees
additional_data
cell
Cell with wallet addresses
additional_data
bodyjetton_wallet0
address
The address of the Router
's wallet of first Jetton
jetton_wallet1
address
The address of the Router
's wallet of second Jetton
excesses_address
address
The address where TON excesses will be sent
Notes:
fee ratio is the value of fee divided by params::fee_divider
(10000); so to set a fee to 1% the value must be 100
fees must be between MIN_FEE
(0) and MAX_FEE
(100)
Sends a message with op set_fees
to a liquidity pool.
update_status
(0x38a6022f)Changes Router
is_locked
var to the opposite value. If is_locked == 1
blocks transfer_notification
messages from going through. Effectively blocks swap
and provide_lp
transactions through this Router
.
None.
None.
init_code_upgrade
(0x03601fc8)Initiates code upgrade for the Router
. An appropriate data with the new Router
code must be provided. The changes won't take effect until finalize_upgrades
is received by the Router
. The minimum delay between initiating code upgrade and finalizing the changes in seven days.
new_code
cell
Code of the new Router
contract
Excesses will be sent to admin_address
init_admin_upgrade
(0x0b02fd5b)Initiates admin change for the Router
. An appropriate address for a new Router
admin must be provided. The changes won't take effect until finalize_upgrades
is received by the Router
. The minimum delay between initiating admin change and finalizing the changes in two days.
new_admin
address
New admin address
Excesses will be sent to admin_address
cancel_admin_upgrade
(0x72d6b3b4)Cancels an admin change if there's a pending admin change.
None
Excesses will be sent to admin_address
cancel_code_upgrade
(0x1f72111a)Cancels a code upgrade if there's a pending code change.
None
Excesses will be sent to admin_address
finalize_upgrades
(0x4e6707b7)Finalizes upgrades of the Router
code and admin changes. In order for the changes to take effect an appropriate amount of time must pass since initializing and upgrade. For code upgrade the delay is seven days, for an admin change the delay is two days.
None
None
reset_gas
(0x29d22935)Updates the amount of TON (in nanoTons) on the Router
to storage_fee::router
(100000) of the Router
. The remaining TON will be sent to the Router
admin.
None
Excesses will be sent to admin_address
reset_pool_gas
(0x66d0dff2)Updates the amount of TON (in nanoTons) on a pool to storage_fee::router
of a pool. Forwards this message to a pool contract for provided pair of Jetton tokens.
jetton_wallet0
address
The address of the Router
's wallet of first Jetton
jetton_wallet1
address
The address of the Router
's wallet of second Jetton
excesses_address
address
The address where TON excesses will be sent
Sends a message to a liquidity pool with reset_gas
op code carrying remaining gas
update_pool_status
(0x2af4607c)Changes Pool
is_locked
var to the opposite value. If is_locked == 1
blocks swaps and liquidity withdraws from this Pool
jetton_wallet0
address
The address of the Router
's wallet of first Jetton
jetton_wallet1
address
The address of the Router
's wallet of second Jetton
excesses_address
address
The address where TON excesses will be sent
Excesses will be sent to excesses_address
pay_to
(0x657b54f5)Initiates a Jetton token transfer from wallets belonging to this Router
, called from pools (on swap, liquidity providing, refund, etc).
op
uint32
Operation code; equal to pay_to
query_id
uint64
Query id
to_address
address
Address of a receiver
excesses_address
address
Address where TON excesses will be sent
original_caller
address
Address of the original tx sender
exit_code
uint32
Exit code
custom_payload
maybe_ref
Payload sent in transfer_notification
additional_data
cell
Cell with additional data
additional_data
bodyfwd_gas
coins
Gas used to forward custom_payload
if present
amount0_out
coins
Amount of the first Jetton token (in basic token units)
token0_address
address
The address of the Router
's wallet of the first Jetton
amount1_out
coins
Amount of the second Jetton token (in basic token units)
token1_address
address
The address of the Router
's wallet of the second Jetton
Sends transfer of amount0_out
tokens to owner
message to token0_address
wallet if amount0_out
> 0
or
Sends transfer of amount1_out
tokens to owner
message to token1_address
wallet if amount1_out
> 0
or
Sends swap
to some Pool
if custom_payload
is cross_swap
pay_vault
(0x63381632)Deposit a token amount into a Vault
contract; used if swap
was done with referral
op
uint32
Operation code; equal to pay_vault
query_id
uint64
Query id
to_address
address
Address of a receiver
excesses_address
address
The address where TON excesses will be sent
additional_data
cell
Cell with additional data
additional_data
bodyamount0_out
coins
Amount of the first Jetton token (in basic token units)
token0_address
address
The address of the Router
's wallet of the first Jetton
amount1_out
coins
Amount of the second Jetton token (in basic token units)
token1_address
address
The address of the Router
's wallet of the second Jetton
Sends deposit_ref_fee
to a corresponding token Vault
of to_address
vault_pay_to
(0x2100c922)Initiates a Jetton token transfer from wallets belonging to this Router
, called from a Vault
when an owner withdraws their collected referral fees.
op
uint32
Operation code; equal to vault_pay_to
query_id
uint64
Query id
amount_out
coins
Amount of the Jetton token (in basic token units)
token_address
address
The address of the Router
's wallet of the Jetton
to_address
address
Address of a receiver
Sends transfer of amount_out
tokens to to_address
message to token_address
wallet
Use a normal swap payload as custom_payload
in the initial swap with the other Router
address as the receiver_address
. The value of fwd_gas
must be non-zero and enough to perform the next swap.
This payload allows chaining of swap operations on the same Router
; fwd_gas
is ignored.
custom_payload
bodyop
uint32
Cross-swap op (0x69cf1a5b)
other_token_wallet
address
Address of the other Router
token wallet
refund_address
address
Address where refund will be sent if swap fails
excesses_address
address
Address where TON excesses will be sent
deadline
uint64
Timestamp of execution deadline for this tx
additional_data
cell
Cell with additional data
additional_data
bodymin_out
coins
Minimum required amount of tokens to receive
receiver_address
address
Address where tokens will be sent after swap
fwd_gas
coins
Gas used to forward a message in transfer_notification
after swap if custom_payload
is present
custom_payload
maybe_ref
Payload sent in transfer_notification
after swap
refund_fwd_gas
coins
Gas used to forward a message in transfer_notification
if swap fails if refund_payload
is present
refund_payload
maybe_ref
Payload sent in transfer_notification
if swap fails
ref_fee
uint16
Referral fee
referral_address
address
Referral address
storage_fee::router
10000000
Amount of TON (in nanoTons) to be left on the Router
contract as gas
params::twodays
172800
Two days is seconds
params::sevendays
604800
Seven days in seconds
This section contains table of DEX v2 op codes
swap
0x6664de2a
Token transfer payload op
for swap
provide_lp
0x37c096df
Token transfer payload op
for liquidity addition
cross_swap
0x69cf1a5b
Custom payload op in swap payload to chain swaps on the same Router
set_fees
0x58274069
Sent by admin to Router
to set new Pool
fees
reset_gas
0x29d22935
Sent by admin to Router
to reset gas
reset_pool_gas
0x66d0dff2
Sent by admin to Router
to reset Pool
gas
update_status
0x38a6022f
Sent by admin to Router
to change Router
lock status
init_code_upgrade
0x03601fc8
Sent by admin to Router
to initiate code upgrade
init_admin_upgrade
0x0b02fd5b
Sent by admin to Router
to initiate admin update
cancel_code_upgrade
0x1f72111a
Sent by admin to Router
to cancel code upgrade
cancel_admin_upgrade
0x72d6b3b4
Sent by admin to Router
to cancel admin update
finalize_upgrades
0x4e6707b7
Sent by admin to Router
to apply all pending updates if cooldown passed
update_pool_status
0x2af4607c
Sent by admin to Router
to change Pool
lock status
set_params
0x2b8b3b62
Sent by admin to Router
to update pool-specific params if present
direct_add_liquidity
0x0ff8bfc6
Sent by user to LpAccount
to initiate liquidity addition
refund_me
0x132b9a2c
Sent by user to LpAccount
to refund deposited tokens
withdraw_fee
0x354bcdf4
Sent by user to Vault
to collect their tokens
set_rate
0x4a2bddb0
Sent by setter to Pool
to change ratio variable (if present)
collect_fees
0x1ee4911e
Sent by protocol address to Pool
to collect fees
internal_set_fees
0x58274069
Sent from Router
to Pool
to change fees
reset_gas
0x29d22935
Sent from Router
to Pool
to rest gas
internal_update_status
0x62752512
Sent from Router
to Pool
to change Pool
lock status
internal_set_params
0x7163444a
Sent from Router
to Pool
to update pool-specific params if present
deposit_ref_fee
0x0490f09b
Sent from Router
to Vault
to deposit tokens in Vault
pay_to
0x657b54f5
Sent from Pool
to Router
to initiate token transfer
add_liquidity
0x50c6a654
Sent from Pool
to LpAccount
to add tokens
pay_vault
0x63381632
Sent from Pool
to Router
to deposit tokens in Vault
cb_add_liquidity
0x06ecd527
Sent from LpAccount
to Pool
to add liquidity
cb_refund_me
0x0f98e2b8
Sent from LpAccount
to Pool
to refund tokens
burn_notification_ext
0x297437cf
Sent from LpWallet
to Pool
after lp tokens burn
vault_pay_to
0x2100c922
Sent from Vault
to Router
to transfer tokens from Vault
to user
swap_refund_no_liq
0x5ffe1295
No liquidity in Pool
swap_refund_tx_expired
0x1ec28412
Swap transaction expired on Pool
swap_refund_reserve_err
0x38976e9b
Not enough liquidity to perform a swap
swap_refund_0_out
0x5f954434
Swap out token amount is 0
swap_refund_slippage
0x39603190
Swap out token amount is less than provided minimum value
swap_pool_locked
0x365c484d
Pool
is locked
swap_fee_out_of_bounds
0xa768c0d1
Ref fee is too big
swap_ok
0xc64370e5
Transfer after swap
burn_ok
0xdda48b6a
Transfer after liquidity withdraw (lp token burn)
refund_ok
0xde7dbbc2
Transfer after LpAccount
refund
transfer_bounce_locked
0x0a0dbdcb
Router
is locked
transfer_bounce_invalid_pool
0x09a8afbf
Incorrect Pool
(both token addresses are the same)
transfer_bounce_wrong_wc
0x720f5b17
Call was done from the wrong workchain
transfer_bounce_low_gas
0x8368a711
Not enough gas to preform operation
transfer_bounce_invalid_request
0x19727ea8
Incorrect token transfer payload op
transfer_bounce_tx_expired
0x0f5681d3
Transaction expired on Router
provide_refund_wrong_workchain
0x4e7405a8
Receiver of liquidity is in the wrong workchain
provide_refund_tx_expired
0xd6a53fd8
Provide transaction expired on Pool
provide_wallet_address
0x2c76b973
Received by Pool
to return lp wallet address for a specified user
take_wallet_address
0xd1735400
Send as a response to provide_wallet_address
with lp wallet address
getter_lp_account_data
0x24cfc100
On-chain getter with LpAccount
data
getter_pool_data
0x26df39fc
On-chain getter with Pool
common data
getter_lp_account_address
0x15fbca95
On-chain getter with LpAccount
address
getter_pool_address
0x2993ade0
On-chain getter with Pool
address
This section contains api reference of the router contract
get_pool_address
Returns an address of a pool for a specified pair of assets.
It's necessary to specify addresses of Jetton wallets of the router as the arguments of this method. These addresses can be retrieved with get_wallet_address
of the Jetton minter.
token0
address
0
The address of the router's wallet of first Jetton
token1
address
1
The address of the router's wallet of second Jetton
Returns single slice with the address of liquidity pool for specified pair of Jettons.
get_router_data
Returns the current state of the router: is the router locked, admin address, pending code or admin upgrades, pool contract code, lp wallet code, lp account code.
None
Returns current state of the Router
Result structure
is_locked
bool
0
if operations are locked (swap
, provide_lp
)
admin_address
address
1
Address of contract's admin account
temp_upgrade
cell
2
A structure describing state of contract's code & admin upgrade; zero values indicate that no upgrade is pending
pool_code
cell
3
Code of the router's liquidity pool contract
jetton_lp_wallet_code
cell
4
Code of lp wallet contract
lp_account_code
cell
5
Code of lp account contract
transfer_notification
(0x7362d09c)Messages received from Jetton wallets belonging to the router upon getting a token transfer from a user. The user must include a custom payload with additional op code (either swap
or provide_lp
) and appropriate data in order for those messages to be processed correctly.
op
uint32
Operation code; equal to transfer_notification
query_id
uint64
Query id
jetton_amount
coins
Jetton amount (in basic token units)
from_user
address
User address
ref_msg_data
cell
Cell with data
ref_msg_data
bodytransferred_op
uint32
Additional operation code
token_wallet1
address
The address of the router's wallet of second Jetton
Notes:
ref_msg_data
contains other fields depending on which op code is called
swap
0x25938561
Swap one type of Jetton tokens for another
provide_lp
0xfcf9e58f
Provide liquidity; route call to the correct pool
swap
(0x25938561)Swap tokens. This message is received when the Router's Jetton token wallet sends a message upon confirmation of token transfer from a user with a custom payload. The router then sends a swap
message to the appropriate pool contract address.
ref_msg_data
bodytransferred_op
uint32
Additional operation code; equal to swap
token_wallet1
address
The address of the router's wallet of second Jetton
min_out
coins
Minimum amount out (in basic token units)
to_address
address
User address
has_ref
uint1
If referral is present
ref_address
address
Referral address; present only if has_ref
is 1
Sends a message with op swap
to a liquidity pool
provide_lp
(0xfcf9e58f)Provide liquidity for a pool. This message is received when Router's token wallet sends a message upon confirmation of token transfer from a user with a custom payload. The router then sends a provide_lp
message to the appropriate pool contract address.
ref_msg_data
bodytransferred_op
uint32
Additional operation code; equal to provide_lp
token_wallet1
address
The address of the router's wallet of second Jetton
min_lp_out
coins
Minimum amount of created liquidity tokens (in basic token units)
Sends a message with op provide_lp
to a liquidity pool
On-chain counterparts of getter methods
getter_pool_address
0xd1db969b
Sends a message with a pool address for a requested token pair; counterpart to get_pool_address
getter_pool_address
(0xd1db969b)Sends a message with an address of a pool for a specified pair of assets; counterpart to get_pool_address
token0
address
The address of the router's wallet of first Jetton
token1
address
The address of the router's wallet of second Jetton
Sends a message back to the sender with the pool address
op
uint32
Operation code equal to getter_pool_address
query_id
uint64
Query id
pool_address
address
Address of a pool
Handles governance message from admin to change pool parameters.
The admin can lock/unlock trading on all pools, change fees on a certain pool, upgrade the router code, etc.
set_fees
0x355423e5
Change fee parameters of a pool
collect_fees
0x1fcb7d3d
Collect protocol fees from a pool
lock
0x878f9b0e
Lock the router (locks all swaps and liquidity providing)
unlock
0x6ae4b0ef
Unlock the router
init_code_upgrade
0xdf1e233d
Initiate code upgrade for the router
init_admin_upgrade
0x2fb94384
Initiate admin change for the router
cancel_admin_upgrade
0xa4ed9981
Cancel an admin change
cancel_code_upgrade
0x357ccc67
Cancel a code upgrade
finalize_upgrades
0x6378509f
Finalize upgrades of the router code and admin change
reset_gas
0x42a0fb43
Update the amount of $TON (in nanoTons) on the router to REQUIRED_TON_RESERVE
of the router
reset_pool_gas
0xf6aa9737
Update the amount of $TON (in nanoTons) on a pool to REQUIRED_TON_RESERVE
of a pool
Notes:
REQUIRED_TON_RESERVE
for the router is 100000
set_fees
(0x355423e5)Change fees of a pool including liquidity pool fees, protocol fees and referral fees. It's necessary to provide correct Jetton token addresses for a target liquidity pool.
new_lp_fee
uint8
New liquidity pool fee ratio (multiplied by FEE_DIVIDER
)
new_protocol_fee
uint8
New protocol fee ratio (multiplied by FEE_DIVIDER
)
new_ref_fee
uint8
New referral fee ratio (multiplied by FEE_DIVIDER
)
new_protocol_fee_address
address
Address for receiving protocol fees
ref_wallets
cell
Cell with wallet addresses
ref_wallets
bodyjetton_wallet0
address
The address of the router's wallet of first Jetton
jetton_wallet1
address
The address of the router's wallet of second Jetton
Notes:
fee ratio is the value of fee divided by FEE_DIVIDER
(10000); so to set a fee to 1% the value must be 100
fees must be between MIN_FEE
(0) and MAX_FEE
(100)
Sends a message with op set_fees
to a liquidity pool.
collect_fees
(0x1fcb7d3d)Collect protocol fees from a pool. The appropriate Jetton wallet addresses must be provided.
jetton_wallet0
address
The address of the router's wallet of first Jetton
jetton_wallet1
address
The address of the router's wallet of second Jetton
Sends a message to a liquidity pool with collect_fees
op code.
lock
(0x878f9b0e)Stops all transfer_notification
messages from going through. Effectively blocks swap
and provide_lp
transactions through this router.
None.
None.
unlock
(0x6ae4b0ef)Allows all transfer_notification
messages to go through. Enables swap
and provide_lp
transactions through this router.
None
None.
init_code_upgrade
(0xdf1e233d)Initiates code upgrade for the router. An appropriate data with the new router code must be provided. The changes won't take effect until finalize_upgrades
is received by the router. The minimum delay between initiating code upgrade and finalizing the changes in seven days.
code
cell
Code of the new router contract
None
init_admin_upgrade
(0x2fb94384)Initiates admin change for the router. An appropriate address for a new router admin must be provided. The changes won't take effect until finalize_upgrades
is received by the router. The minimum delay between initiating admin change and finalizing the changes in two days.
admin
address
New admin address
None
cancel_admin_upgrade
(0xa4ed9981)Cancels an admin change if there's a pending admin change.
None
None
cancel_code_upgrade
(0x357ccc67)Cancels a code upgrade if there's a pending code change.
None
None
finalize_upgrades
(0x6378509f)Finalizes upgrades of the router code and admin change. In order for the changes to take effect an appropriate amount of time must pass since initializing and upgrade. For code upgrade the delay is seven days, for an admin change the delay is two days.
None
None
reset_gas
(0x42a0fb43)Updates the amount of $TON (in nanoTons) on the router to REQUIRED_TON_RESERVE
(100000) of the router. The remaining $TON will be sent to the router admin.
None
Sends an empty message back to admin with the remaining $TON
reset_pool_gas
(0xf6aa9737)Updates the amount of $TON (in nanoTons) on a pool to REQUIRED_TON_RESERVE
of a pool. Forwards this message to a pool contract for provided pair of Jetton tokens.
jetton_wallet0
address
The address of the router's wallet of first Jetton
jetton_wallet1
address
The address of the router's wallet of second Jetton
Sends a message to a liquidity pool with reset_gas
op code carrying remaining gas
pay_to
(0xf93bb43f)Initiates a Jetton token transfer from wallets belonging to this router, called from pools (on swap, liquidity providing, refund, etc).
op
uint32
Operation code; equal to pay_to
query_id
uint64
Query id
owner
address
Address of a receiver
exit_code
uint32
Exit code
ref_coins_data
cell
Cell with Jetton wallet addresses and token amounts
ref_coins_data
bodyamount0_out
coins
Amount of the first Jetton token (in basic token units)
token0_address
address
The address of the router's wallet of the first Jetton
amount1_out
coins
Amount of the second Jetton token (in basic token units)
token1_address
address
The address of the router's wallet of the second Jetton
Sends transfer of amount0_out
tokens to owner
message to token0_address
wallet if amount0_out
> 0
Sends transfer of amount1_out
tokens to owner
message to token1_address
wallet if amount1_out
> 0
WORKCHAIN
0
Workchain id
REQUIRED_TON_RESERVE
100000
Amount of $TON (in nanoTons) to be left on the router contract as gas
TWODAYS
172800
Two days is seconds
SEVENDAYS
604800
Seven days in seconds
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
, or DeDust
.
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.
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
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
Here's an example of how to construct and encode the extra data for a StonFiV2 swap:
When the Omniston server processes a swap request:
It examines the protocol
field of each SwapChunk
to determine which DEX to use
Based on the extra_version
, it knows how to decode the extra
field
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 1: Initial version supporting StonFiV1, StonFiV2, and DeDust protocols
omniston-swap.md - Main swap protocol documentation
omniston-nodejs.md - Node.js SDK usage
omniston-react.md - React components and hooks
This section contains api reference of the pool contract
get_pool_data
Returns the current state of the Pool
None
Returns PoolData
structure containing current state of the pool. Typed pools may return additional arguments if present
PoolData
structure
is_locked
bool
0
true if transfer_notification
operations are locked (swap
, provide_lp
)
router_address
address
1
Address of the Router
total_supply
coins
2
Total supply of lp tokens
reserve0
coins
3
Amount of the first token (in basic token units)
reserve1
coins
4
Amount of the second token (in basic token units)
token0_wallet_address
address
5
Address of the first Jetton token
token1_wallet_address
address
6
Address of the second Jetton token
lp_fee
uint16
7
Liquidity pool fee value
protocol_fee
uint16
8
Protocol fee
protocol_fee_address
address
9
Address for receiving protocol fees
collected_token0_protocol_fee
coins
10
Amount of collected protocol fees of the first token (in basic token units)
collected_token1_protocol_fee
coins
11
Amount of collected protocol fees of the second token (in basic token units)
Notes:
fee ratio is the value of fee divided by params::fee_divider
(10000); so a fee of 1% has a value of 100
stableswap
)Additional data in PoolData
structure specific to stableswap pools
PoolData
structure additional params
amp
uint32
12
Stableswap amplification parameter
get_lp_account_address
Get the lp account address of a user
owner_address
address
Address of a user
Returns the lp account address of a user
get_jetton_data
Standard jetton 'get' methods from TonWeb JettonMinter.
None
Returns a structure with Jetton data
JettonData
structure
total_supply
coins
0
Total token supply of lp tokens (in basic token units)
mintable
bool
1
always true
admin_address
address
2
Router
address
jetton_content_uri
string
3
Offchain uri with Jetton data
jetton_wallet_code
cell
4
Code of the lp Jetton wallet
get_wallet_address
Get lp wallet address of a user.
owner_address
address
Address of a user
Returns a calculated lp wallet address of a user
get_pool_type
Get Pool
type, equals to dex_type
param in get_router_data
None
Return pool type of this pool as string:
constant_product
stableswap
On-chain counterparts of getter methods.
getter_pool_data
0x26df39fc
Sends a message with the current state of the pool
getter_lp_account_address
0x15fbca95
Sends a message with the lp account address of a user
provide_wallet_address
0x2c76b973
Sends a message with the lp wallet address of a user
getter_pool_data
(0x26df39fc)Sends a message with the current state of the pool. On-chain equivalent of get_pool_data
.
None
Sends a message with current pool data to the sender_address
op
uint32
Operation code is equal to getter_pool_data
query_id
uint64
Query id
is_locked
uint1
If this Pool
is locked
reserve0
coins
Amount of the first token (in basic token units)
reserve1
coins
Amount of the second token (in basic token units)
token0_address
address
Address of the first Jetton token
token1_address
address
Address of the second Jetton token
additional_data
cell
Cell with additional data
additional_data
bodylp_fee
uint16
Liquidity pool fee value
protocol_fee
uint16
Protocol fee
router_address
address
Address of the Router
protocol_fee_address
address
Address for receiving protocol fees
total_supply
coins
Total amount of minted lp tokens
collected_token0_protocol_fee
coins
Amount of collected protocol fees of the first token (in basic token units)
collected_token1_protocol_fee
coins
Amount of collected protocol fees of the second token (in basic token units)
getter_lp_account_address
(0x15fbca95)Sends a message with the lp account address of a user. On-chain equivalent of get_lp_account_address
.
user_address
address
Address of a user
Sends a message with the lp account address of a user to sender_address
op
uint32
Operation code is equal to getter_expected_outputs
query_id
uint64
Query id
lp_account_address
address
lp account address of a user
provide_wallet_address
(0x2c76b973)Sends a message with the lp wallet address of a user. On-chain equivalent of get_wallet_address
.
owner_address
address
Address of a user
include_address?
uint1
Include user address in the response message
Sends a message back to sender with the calculated lp wallet address of a user
op
uint32
Operation code is equal to take_wallet_address
(0xd1735400)
query_id
uint64
Query id
lp_wallet_address
address
Calculated lp wallet address
additional_data
maybe_ref
Cell with data if include_address?
evaluates to true
additional_data
bodyincluded_address
address
Address of a user
Handles operations sent from a Jetton wallet.
burn_notification_ext
0x297437cf
Sent by LP wallet after burning LP jettons to release liquidity
burn_notification_ext
(0x297437cf)Sent by LpWallet
after burning LP jettons to release liquidity.
jetton_amount
coins
Amount of liquidity tokens to burn (in basic token units)
from_address
address
User address
response_address
address
Address for a response message
custom_payloads
maybe_ref
Payloads for token0 and token1
payload_1
maybe_ref
Payload used for amount0
; can be cross_swap
payload_2
maybe_ref
Payload used for amount1
; can be cross_swap
Sends a message with op excesses
(0xd53276db) to response_address
Sends a message with a released amount of both tokens to be received by a user as a result of the burn operation to the router, which initiates pay_to
operation to from_address
Handles messages from the router.
swap
0x6664de2a
Swap tokens
provide_lp
0x37c096df
Provide liquidity
reset_gas
0x29d22935
Reset gas
set_fees
0x58274069
Set new fee parameters
swap
(0x6664de2a)Swap tokens. This message is received from the router when the user initiates a token swap.
from_user
address
User address
amount0
coins
Amount of incoming first token
amount1
coins
Amount of incoming second token
payload
cell
Cell with dex payload
payload
bodyop
uint32
Swap op
other_token_wallet
address
Address of the other Router
token wallet
refund_address
address
Address where refund will be sent if swap fails
excesses_address
address
Address where TON excesses will be sent
additional_data
cell
Cell with additional data
additional_data
bodymin_out
coins
Minimum required amount of tokens to receive
receiver_address
address
Address where tokens will be sent after swap
fwd_gas
coins
Gas used to forward a message in transfer_notification
after swap if custom_payload
is present
custom_payload
maybe_ref
Payload sent in transfer_notification
after swap
refund_fwd_gas
coins
Gas used to forward a message in transfer_notification
if swap fails if refund_payload
is present
refund_payload
maybe_ref
Payload sent in transfer_notification
if swap fails
ref_fee
uint16
Referral fee
referral_address
address
Referral address
Notes:
swap will fail if a user should receive less than min_out
of tokens as a result
max allowed value of ref_fee
is 100 (1%)
Sends a message with an amount of the other tokens to be received by a user as a result of the swap to the router, which initiates pay_to
operation
Additionally may send a message with referral fees to the router, which initiates pay_vault
operation to Vault
of referral_address
provide_lp
(0x37c096df)Provide liquidity for the pool. A user must submit an amount of both tokens to receive lp tokens and add new liquidity to a pool. This message is routed to liquidity pool account with add_liquidity
operation code.
from_user
address
User address
amount0
coins
Amount of incoming first token
amount1
coins
Amount of incoming second token
payload
cell
Cell with dex payload
payload
bodyop
uint32
Provide lp op
other_token_wallet
address
Address of the other Router
token wallet
refund_address
address
Address where refund will be sent if swap fails
excesses_address
address
Address where TON excesses will be sent
additional_data
cell
Cell with additional data
additional_data
bodymin_lp_out
coins
Minimum required amount of lp tokens to receive
receiver_address
address
Address where lp tokens will be sent
both_positive
uint1
Trigger liquidity deposit only if both token amounts are non-zero
fwd_gas
coins
Gas used to forward a message in transfer_notification
after mint if custom_payload
is present
custom_payload
maybe_ref
Payload sent in transfer_notification
after lp mint
Sends a message to liquidity pool account with add_liquidity
operation code.
reset_gas
(0x29d22935)Updates the amount of TON (in nanoTons) on the pool to storage_fee::pool
(10000000) of the pool. The remaining amount of TON will be sent to excesses_address
.
excesses_address
address
Address where excess ton will be sent
Sends a message to excesses_address
with the remaining TON
internal_set_fees
(0x75930d63)Set new fee values including liquidity pool fees, protocol fees and referral fees as well as an address for receiving collected protocol fees.
new_lp_fee
uint16
New liquidity pool fee ratio (multiplied by params::fee_divider
)
new_protocol_fee
uint16
New protocol fee ratio (multiplied by params::fee_divider
)
new_protocol_fee_address
address
Address for receiving protocol fees
excesses_address
address
Address where TON excesses will be sent
Notes:
fee ratio is the value of fee divided by params::fee_divider
(10000); so to set a fee to 1% the value must be 100
fees must be between params::min_fee
(0) and params::max_fee
(100)
Sends a message to excesses_address
with the remaining TON
Handles messages from the protocol_fee_address
.
collect_fees
0x1ee4911e
Collect fees
collect_fees
(0x1ee4911e)Collect protocol fees. The amount of fees in both tokens will be sent to protocol_fee_address
address.
payload_0
maybe_ref
Payload used for amount0
; can be cross_swap
payload_1
maybe_ref
Payload used for amount1
; can be cross_swap
Sends a message with collected fees in both tokens to the router, which initiates pay_to
operation to protocol_fee_address
.
Handles messages from an lp account.
cb_add_liquidity
0x06ecd527
Sent by user's lp_account after adding liquidity
cb_refund_me
0x0f98e2b8
Sent by user's lp_account after adding liquidity
cb_add_liquidity
(0x06ecd527)Add new liquidity to the pool. Sent by user's lp account after both or one amounts tokens is sent by a user. The resulting added liquidity must be greater than min_lp_out
for the operation to be successful.
amount0
coins
Amount of the first Jetton tokens added (in basic token units)
amount1
coins
Amount of the second Jetton tokens added (in basic token units)
user_address
address
Owner's address
min_lp_out
coins
Minimum amount of received liquidity tokens (in basic token units)
fwd_amount
coins
Forward amount used to send custom_payload
(if present) in transfer_notification
custom_payload
maybe_ref
Payload sent in transfer_notification
upon receiving tokens
additional_data
ref
See table below
to_address
address
Owner of new liquidity tokens
refund_address
address
Address of the owner of LpAccount
where tokens will be refunded if liquidity mint wasn't successful
excess_address
address
Address where all TON excesses will be sent
Notes:
addition of liquidity will fail if a user should receive less than min_lp_out
of lp tokens as a result
cannot add liquidity if a supply of either tokens becomes greater than MAX_COINS
(2^120 - 1)
Sends a message with internal_transfer
(0x178d4519) op code to the lp wallet of to_address
with minted liquidity tokens
cb_refund_me
(0x0f98e2b8)Sent by user's lp account after a user initiates refund_me
operation to cancel addition of new liquidity. The amount of previously stored tokens will be sent back to the user.
amount0
coins
Amount of the first Jetton tokens (in basic token units)
amount1
coins
Amount of the second Jetton tokens (in basic token units)
user_address
address
Owner's address
payload_0
maybe_ref
Payload used for amount0
; can be cross_swap
payload_1
maybe_ref
Payload used for amount1
; can be cross_swap
Sends a message with amount0
of the first token and amount1
of the second token to the router, which initiates pay_to
operation
storage_fee::pool
10000000
Amount of TON (in nanoTons) to be left on the pool contract as gas
params::required_min_liquidity
1001
Minimum amount of liquidity required
MAX_COINS
2^120 - 1
Maximum amount of tokens (in basic token units) stored as liquidity
gas::pool::provide_wallet_address
20000000
Additional gas (in nanoTons) for providing a wallet
params::fee_divider
10000
Fee values are divided by this value
params::min_fee
0
Minimum fee allowed (0%)
params::max_fee
100
Maximum fee allowed (1%)
This package provides binding for omniston-sdk to the React ecosystem. Using this package, you can access all Omniston methods as hooks powered by TanStack react query (out-of-box loading states, retries, error handling, and match more)
You can find all supported methods in our docs or take a look onto our demo app that use NextJs and omniston-sdk-react
package
You can pass custom queryClient
if you want to apply shared behaviour to all of the queries
The provider takes the following parameters:
client
ApiClient | undefined
Optional. Provide this if you want to override the default API client. By default, this will be an ApiClient
using ReconnectingTransport
apiUrl
URL | string
Omniston WebSocket API URL.
Send a request for quote to swap an asset to another asset.
A QuoteRequest
has the following properties:
settlementMethods
SettlementMethod[]
Supported methods of swap settlement
askAssetAddress
Address
Blockchain-specific address of ask asset
offerAssetAddress
Address
Blockchain-specific address of offer asset
amount
{ offerUnits: string } | { askUnits: string }
Either the amount of offer asset or ask asset
amount.offerUnits
string
The amount of offer asset the trader wants to pay, including all fees, in base asset units
amount.askUnits
string
The amount of ask asset the trader wants to get after all fees, in base asset units
referrerAddress
Address | undefined
The address of referrer that will receive the fees
referrerFeeBps
number | undefined
The amount of fees required by the referrer in basis points (1/10000 = 0.01%)
settlementParams
RequestSettlementParams | undefined
Additional parameters of RFQ related to settlement. See the table below.
RequestSettlementParams
max_price_slippage_bps
number | undefined
Maximum price slippage, in basis points (0.01%). For example, 100 = 1% slippage.
max_outgoing_messages
number | undefined
Maximum number of outgoing messages supported by the wallet. For TON blockchain, this defaults to 4 if omitted.
Note: Some parameters in RequestSettlementParams
may only be relevant for certain blockchains or certain settlement methods. If your settlement method or wallet does not require them, you can omit them or set them to default values.
The server returns Observable<QuoteResponseEvent>
, which is a stream of quote updates.
A QuoteResponseEvent
might be one of the following:
{ type: "quoteUpdated"; quote: Quote; }
{ type: "noQuote"; }
{ type: "unsubscribed"; }
A Quote
has the following properties:
quoteId
string
ID of the quote generated by the platform (32 characters)
resolverId
string
ID of the resolver
resolverName
string
Name of the resolver
offerAssetAddress
Address
Blockchain-specific address of offer asset
askAssetAddress
Address
Blockchain-specific address of ask asset
offerUnits
string
The amount of offer asset the trader must pay, including all fees
askUnits
string
The amount of ask asset the trader will get after all fees
referrerAddress
Address | undefined
The address of referrer that will receive the fees
referrerFeeUnits
string
The amount of fees that the referrer will get (in units of offerAssetAddress
)
protocolFeeUnits
string
The amount of fees charged by the protocol (in units of offerAssetAddress
).
quoteTimestamp
number
The timestamp (UTC seconds) of Quote sent by resolver
tradeStartDeadline
number
Max timestamp (UTC seconds) of start of the trade
gasBudget
string
The amount of gas budget for the trade
params
object | undefined
Various parameters specific to the settlement method. See the source code for more details.
Now that we have a quote, we should request a server to build a transaction to initiate the trade that the user can verify and sign.
The buildTransfer
method takes a TransactionRequest
object as a parameter, having the following properties:
quote
Quote
The valid quote received from Omniston.requestForQuote
sourceAddress
Address
The address on offerBlockchain
that will send initial transaction to start the trade
destinationAddress
Address
The address on askBlockchain
that will receive result of the trade
You can found the instruction on how to send transaction using the @tonconnect/ui-react
package here.
See TON Cookbook for detailed instructions.
For tutorial purposes, we'll use the @ton/core
package to get the external transaction hash and find the internal hash with TonAPI v2.
After the user has signed and initiated the transaction, we can track the trade status.
The trackTrade
method has the following parameters:
quoteId
string
ID of the quote received from Omniston.requestFromQuote
traderWalletAddress
Address
The address of trader's wallet that initiated transaction
outgoingTxHash
string
Hash of the transaction that initiated the trade
It returns Observable<TrackTradeStatus>
. For the different trade status values, see the source code. We are interested in the trade result enum which can be read from status.tradeSettled?.result?
field. The enum has the following values:
TRADE_RESULT_FULLY_FILLED
The trade has been completed and fully filled.
TRADE_RESULT_PARTIALLY_FILLED
The trade has been partially filled. Something went wrong.
TRADE_RESULT_ABORTED
The trade has been aborted.
TRADE_RESULT_UNKNOWN
UNRECOGNIZED
This guide explains how to become a resolver (Market Maker) in the Omniston protocol and integrate with its gRPC API.
A resolver is a service that provides token exchange rates and executes trades. To become a resolver, you need to:
Register by obtaining a Soul-Bound Token (SBT)
Connect to the gRPC API
Handle quote requests and trades
First, generate one or more Ed25519 key pairs that will be used for authentication:
For other languages, you can use any standard Ed25519 implementation library available in your preferred programming language
Create a JSON document containing:
Your resolver name
Your public key(s)
Example:
Your metadata will be stored in an SBT NFT collection
You'll receive your SBT stake address for API authentication
Create a connection payload:
Sign the payload:
Serialize the ConnectPayload
to bytes
Sign using your Ed25519 private key
Base64 encode the signature
Send a ConnectRequest
:
Example connection request:
The resolver API uses a bidirectional gRPC stream. After connecting:
You'll receive these events from the server:
Key events:
QuoteRequestedEvent
: New quote request from a trader
QuoteRequestCancelledEvent
: Trader cancelled their request
QuoteAcceptedEvent
: Your quote was accepted
QuoteRejectedEvent
: Your quote was rejected
QuoteInvalidatedEvent
: Confirmation of quote invalidation
You can send these requests to the server:
Key requests:
UpdateQuoteRequest
: Provide or update a quote
InvalidateQuoteRequest
: Cancel a previously provided quote
When you receive a QuoteRequestedEvent
:
Respond with an UpdateQuoteRequest
:
For swap settlement, include route information:
You receive QuoteRequestedEvent
You send UpdateQuoteRequest
The server validates your quote and responds with:
QuoteAcceptedEvent
: Your quote was validated and accepted, includes quote_id
.
QuoteRejectedEvent
: Your quote was rejected. The event includes a code
field from the QuoteRejectedCode
enum. Possible reasons include:
UNDEFINED
(0) - Uncategorized error
INVALID_PARAMETERS
(1) - Invalid value of a parameter
INVALID_AMOUNTS
(2) - Asset amount restrictions don't pass RFQ requirements
ROUTE_PROHIBITED
(3) - Route uses a prohibited intermediate asset
POOL_PROHIBITED
(4) - Route uses a unverified or prohibited liquidity pool
EMULATION_RESULT_MISMATCH
(5) - Transaction emulation produced a result different from the quote
INTERNAL_ERROR
(101) - Server errors
At any time, you can:
Send new UpdateQuoteRequest
to update the quote
Send InvalidateQuoteRequest
to cancel the quote
Sequence Numbers
Use monotonically increasing seqno
for your requests
Match reply_to
with event seqno
when responding
Track request/response correlation using seqno
Quote Management
Honor your quotes until trade_start_deadline
Invalidate quotes you can't fulfill
Include all fees in your quoted amounts
Error Handling
Reconnect on connection loss
Handle all event types
Log rejected quotes for monitoring
Performance
Maintain a single gRPC connection
Process events asynchronously
Buffer outgoing requests
Connect to: https://omni-grpc.ston.fi
This section contains api reference of the pool contract
get_pool_data
Returns the current state of the pool: Jetton token reserves, Jetton wallet addresses and fee parameters.
None
Returns current state of the Pool
Result structure
reserve0
coins
0
Amount of the first token (in basic token units)
reserve1
coins
1
Amount of the second token (in basic token units)
token0_wallet_address
address
2
Address of the first Jetton token
token1_wallet_address
address
3
Address of the second Jetton token
lp_fee
uint8
4
Liquidity pool fee value
protocol_fee
uint8
5
Protocol fee
ref_fee
uint8
6
Referral fee
protocol_fee_address
address
7
Address for receiving protocol fees
collected_token0_protocol_fee
coins
8
Amount of collected protocol fees of the first token (in basic token units)
collected_token1_protocol_fee
coins
9
Amount of collected protocol fees of the second token (in basic token units)
Notes:
fee ratio is the value of fee divided by FEE_DIVIDER
(10000); so a fee of 1% has a value of 100
get_expected_outputs
Estimate expected result of the amount
of jettonWallet
tokens swapped to the other type of tokens of the pool.
amount
coins
Amount of tokens to swap (in basic token units)
token_wallet
address
Token Jetton address (must be equal to one of the Jetton addresses of the pool)
Returns expected result of a token swap
Result structure
jetton_to_receive
coins
0
Amount of tokens received (in basic token units)
protocol_fee_paid
coins
1
Amount tokens paid for protocol fees (in basic token units)
ref_fee_paid
coins
2
Amount tokens paid for referral fees (in basic token units)
get_expected_tokens
Estimate an expected amount of lp tokens minted when providing liquidity.
amount0
coins
Amount of tokens for the first Jetton (in basic token units)
amount1
coins
Amount of tokens for the second Jetton (in basic token units)
Returns an estimated amount of liquidity tokens to be minted
get_expected_liquidity
Estimate expected liquidity freed upon burning liquidity tokens.
jetton_amount
coins
Amount of liquidity tokens (in basic token units)
Returns expected freed liquidity
Return structure
amount0
coins
0
Amount of tokens for the first Jetton (in basic token units)
amount1
coins
1
Amount of tokens for the second Jetton (in basic token units)
get_lp_account_address
Get the lp account address of a user
owner_address
address
Address of a user
Function the lp account address of a user
get_jetton_data
Standard jetton 'get' methods from TonWeb JettonMinter.
None
Returns a structure with Jetton data
Return structure
total_supply
coins
0
Total token supply (in basic token units)
is_mintable
bool
1
If new tokens can be minted
admin_address
address
2
Admin address
jetton_content_uri
string
3
Offchain uri with Jetton data
jetton_wallet_code
cell
4
Code of the lp Jetton wallet
get_wallet_address
Get lp wallet address of a user.
owner_address
address
Address of a user
Returns calculated lp wallet address of a user
On-chain counterparts of getter methods.
getter_pool_data
0x43c034e6
Sends a message with the current state of the pool
getter_expected_outputs
0xed4d8b67
Sends a message with an estimated result of the token swap
getter_lp_account_address
0x9163a98a
Sends a message with the lp account address of a user
getter_expected_tokens
0x9ce632c5
Sends a message with an estimated amount of lp tokens minted when providing liquidity
getter_expected_liquidity
0x8751801f
Sends a message with estimated liquidity freed upon burning of liquidity tokens
provide_wallet_address
0x2c76b973
Sends a message with the lp wallet address of a user
getter_pool_data
(0x43c034e6)Sends a message with the current state of the pool. On-chain equivalent of get_pool_data
.
None
Sends a message with current pool data to the sender_address
op
uint32
Operation code is equal to getter_pool_data
query_id
uint64
Query id
reserve0
coins
Amount of the first token (in basic token units)
reserve1
coins
Amount of the second token (in basic token units)
token0_address
address
Address of the first Jetton token
token1_address
address
Address of the second Jetton token
ref_fee_data
cell
Cell with fee data
ref_fee_data
bodylp_fee
uint8
Liquidity pool fee value
protocol_fee
uint8
Protocol fee
ref_fee
uint8
Referral fee
protocol_fee_address
address
Address for receiving protocol fees
collected_token0_protocol_fee
coins
Amount of collected protocol fees of the first token (in basic token units)
collected_token1_protocol_fee
coins
Amount of collected protocol fees of the second token (in basic token units)
getter_expected_outputs
(0xed4d8b67)Sends a message with an estimated result of the token swap. On-chain equivalent of get_expected_outputs
.
amount
coins
Amount of tokens (in basic token units)
token_wallet
address
Token Jetton address
Sends a message with an estimated result of the token swap to sender_address
op
uint32
Operation code is equal to getter_expected_outputs
query_id
uint64
Query id
out
coins
Amount of tokens to be received (in basic token units)
protocol_fee_out
coins
Amount tokens paid for protocol fees (in basic token units)
ref_fee_out
coins
Amount tokens paid for referral fees (in basic token units)
getter_lp_account_address
(0x9163a98a)Sends a message with the lp account address of a user. On-chain equivalent of get_lp_account_address
.
user_address
address
Address of a user
Sends a message with the lp account address of a user to sender_address
op
uint32
Operation code is equal to getter_expected_outputs
query_id
uint64
Query id
lp_account_address
address
lp account address of a user
Notes:
the current version of the contract returns a message with getter_expected_outputs
op code instead of getter_lp_account_address
so the user must differentiate those messages with some other means
getter_expected_tokens
(0x9ce632c5)Sends a message with an estimated amount of lp tokens minted when providing liquidity. On-chain equivalent of get_expected_tokens
user_address
address
User address (unused)
amount0
coins
Amount of tokens for the first Jetton (in basic token units)
amount1
coins
Amount of tokens for the second Jetton (in basic token units)
Sends a message with an estimated amount of liquidity tokens to be minted to sender_address
op
uint32
Operation code is equal to getter_expected_tokens
query_id
uint64
Query id
liquidity
coins
Expected amount of liquidity tokens (in basic token units)
getter_expected_liquidity
(0x8751801f)Sends a message with estimated liquidity freed upon burning liquidity tokens. On-chain equivalent of get_expected_liquidity
.
jetton_amount
coins
Amount of liquidity tokens to burn (in basic token units)
Sends a message with estimated liquidity to sender_address
op
uint32
Operation code is equal to getter_expected_tokens
query_id
uint64
Query id
amount0_out
coins
Amount of tokens for the first Jetton (in basic token units)
amount1_out
coins
Amount of tokens for the second Jetton (in basic token units)
provide_wallet_address
(0x2c76b973)Sends a message with the lp wallet address of a user. On-chain equivalent of get_wallet_address
.
owner_address
address
Address of a user
include_address?
uint1
Include user address in the response message
Sends a message back to sender with the calculated lp wallet address of a user
op
uint32
Operation code is equal to take_wallet_address
(0xd1735400)
query_id
uint64
Query id
lp_wallet_address
address
Calculated lp wallet address
ref_address
cell | null
Cell with data if include_address?
evaluates to true
ref_address
bodyincluded_address
address
Address of a user
Handles operations sent from a Jetton wallet.
burn_notification
0x7bdd97de
Sent by LP wallet after burning LP jettons to release liquidity
burn_notification
(0x7bdd97de)Sent by LP wallet after burning LP jettons to release liquidity.
jetton_amount
coins
Amount of liquidity tokens to burn (in basic token units)
from_address
address
User address
response_address
address
Address for a response message
Sends a message with op excesses
(0xd53276db) to response_address
Sends a message with a released amount of both tokens to be received by a user as a result of the burn operation to the router, which initiates pay_to
operation to from_address
Handles messages from the router.
swap
0x25938561
Swap tokens
provide_lp
0xfcf9e58f
Provide liquidity
reset_gas
0x42a0fb43
Reset gas
collect_fees
0x1fcb7d3d
Collect fees
set_fees
0x355423e5
Set new fee parameters
swap
(0x25938561)Swap tokens. This message is received from the router when the user initiates a token swap.
from_user_address
address
User address
token_wallet
address
Incoming Jetton wallet address
amount
coins
Amount of incoming tokens (in basic token units)
min_out
coins
Minimum amount of received tokens (in basic token units)
has_ref
uint1
If referral is present
ref_bodycell
cell
Cell with data
Notes:
swap will fail if a user should receive less than min_out
of tokens as a result
ref_bodycell
bodyfrom_real_user
address
Who initialized the swap
ref_address
address
Referral address; present only if has_ref is 1
Sends a message with an amount of the other tokens to be received by a user as a result of the swap to the router, which initiates pay_to
operation
Additionally may send a message with referral fees to the router, which initiates pay_to
operation to ref_address
provide_lp
(0xfcf9e58f)Provide liquidity for the pool. A user must submit an amount of both tokens to receive lp tokens and add new liquidity to a pool. This message is routed to liquidity pool account with add_liquidity
operation code.
owner_addr
address
User address
min_lp_out
coins
Minimum amount of received liquidity tokens (in basic token units)
amount0
coins
Amount of the first Jetton token (in basic token units)
amount1
coins
Amount of the second Jetton token (in basic token units)
Sends a message to liquidity pool account with add_liquidity
operation code.
reset_gas
(0x42a0fb43)Updates the amount of $TON (in nanoTons) on the pool to REQUIRED_TON_RESERVE
(10000000) of the pool. The remaining amount of $TON will be sent back to the router.
None
Sends an empty message back to the router with the remaining $TON
collect_fees
(0x1fcb7d3d)Collect protocol fees. The amount of fees in both tokens will be sent to protocol_fee_address
address.
None
Sends a message with collected fees in both tokens to the router, which initiates pay_to
operation to protocol_fee_address
.
set_fees
(0x355423e5)Set new fee values including liquidity pool fees, protocol fees and referral fees as well as an address for receiving collected protocol fees.
new_lp_fee
uint8
New liquidity pool fee ratio (multiplied by FEE_DIVIDER
)
new_protocol_fee
uint8
New protocol fee ratio (multiplied by FEE_DIVIDER
)
new_ref_fee
uint8
New referral fee ratio (multiplied by FEE_DIVIDER
)
new_protocol_fee_address
address
Address for receiving protocol fees
Notes:
fee ratio is the value of fee divided by FEE_DIVIDER
(10000); so to set a fee to 1% the value must be 100
fees must be between MIN_FEE
(0) and MAX_FEE
(100)
None
Handles messages from an lp account.
cb_add_liquidity
0x56dfeb8a
Sent by user's lp_account after adding liquidity
cb_refund_me
0x89446a42
Sent by user's lp_account after adding liquidity
cb_add_liquidity
(0x56dfeb8a)Add new liquidity to the pool. Sent by user's lp account after an appropriate amount (greater than 1000
) of both Jetton tokens is sent by a user. The resulting added liquidity must be greater than min_lp_out
for the operation to be successful.
tot_am0
coins
Amount of the first Jetton token (in basic token units)
tot_am1
coins
Amount of the second Jetton token (in basic token units)
user_address
address
User address
min_lp_out
coins
Minimum amount of received liquidity tokens (in basic token units)
Notes:
addition of liquidity will fail if a user should receive less than min_lp_out
of lp tokens as a result
cannot add liquidity if a supply of either tokens becomes greater than MAX_COINS
(2^120 - 1)
Sends a message with internal_transfer
(0x178d4519) op code to the lp wallet of user_address
with minted liquidity tokens; on initial liquidity addition tokens are minted to addr_none
cb_refund_me
(0x89446a42)Sent by user's lp account after a user initiates refund_me
operation to cancel addition of new liquidity. The amount of previously stored tokens will be sent back to the user.
tot_am0
coins
Amount of the first Jetton token (in basic token units)
tot_am1
coins
Amount of the second Jetton token (in basic token units)
user_address
address
User address
Sends a message with tot_am0
of the first token and tot_am1
of the second token to the router, which initiates pay_to
operation
Handles direct messages from a user.
collect_fees
0x1fcb7d3d
Called by anyone; collect fees; the caller receives a bounty
collect_fees
(0x1fcb7d3d)Collect protocol fees which will be sent to protocol_fee_address
. A user which initiates this operation receives a bounty equal to 1/1000 of collected amount of both tokens.
None
Sends a message with collected fees (minus the bounty) to protocol_fee_address
Sends a message with an amount of tokens to be received by a user as a bounty (equal to collected fees divided by 1000) to the router, which initiates pay_to
operation
WORKCHAIN
0
Workchain id
REQUIRED_TON_RESERVE
10000000
Amount of $TON (in nanoTons) to be left on the pool contract as gas
REQUIRED_MIN_LIQUIDITY
1000
Minimum amount of liquidity required
REQUIRED_MIN_COLLECT_FEES
1000000
Minimum amount of tokens (in basic token units) collected as fees
MAX_COINS
2^120 - 1
Maximum amount of tokens (in basic token units) stored as liquidity
PROVIDE_ADD_GAS_CONSUMPTION
10000000
Additional gas (in nanoTons) for providing a wallet
FEE_DIVIDER
10000
Fee values are divided by this value
MIN_FEE
0
Minimum fee allowed
MAX_FEE
100
Maximum fee allowed
This package acts as a typescript wrapper on top of the Ston.fi Omniston protocol API and provides RxJS styled observables on top of the WebSocket API connection
Create an Omniston instance, specifying the API URL.
The constructor takes the following parameters:
client
ApiClient | undefined
Optional. Provide this if you want to override the default API client. By default, this will be an ApiClient
using ReconnectingTransport
apiUrl
URL | string
Omniston WebSocket API URL.
Send a request for quote to swap an asset to another asset.
A QuoteRequest
has the following properties:
settlementMethods
SettlementMethod[]
Supported methods of swap settlement
askAssetAddress
Address
Blockchain-specific address of ask asset
offerAssetAddress
Address
Blockchain-specific address of offer asset
amount
{ offerUnits: string } | { askUnits: string }
Either the amount of offer asset or ask asset
amount.offerUnits
string
The amount of offer asset the trader wants to pay, including all fees, in base asset units
amount.askUnits
string
The amount of ask asset the trader wants to get after all fees, in base asset units
referrerAddress
Address | undefined
The address of referrer that will receive the fees
referrerFeeBps
number | undefined
The amount of fees required by the referrer in basis points (1/10000 or 0.01%)
settlementParams
RequestSettlementParams | undefined
Additional parameters of RFQ related to settlement. See the table below.
RequestSettlementParams
max_price_slippage_bps
number | undefined
Maximum price slippage, in basis points (0.01%). For example, 100 = 1% slippage.
max_outgoing_messages
number | undefined
Maximum number of outgoing messages supported by the wallet. For TON blockchain, this defaults to 4 if omitted.
Note: Some parameters in RequestSettlementParams
may only be relevant for certain blockchains or certain settlement methods. If your settlement method or wallet does not require them, you can omit them or set them to default values.
The server returns Observable<QuoteResponseEvent>
, which is a stream of quote updates.
A QuoteResponseEvent
might be one of the following:
{ type: "quoteUpdated"; quote: Quote; }
{ type: "noQuote"; }
{ type: "unsubscribed"; }
A Quote
has the following properties:
quoteId
string
ID of the quote generated by the platform (32 characters)
resolverId
string
ID of the resolver
resolverName
string
Name of the resolver
offerAssetAddress
Address
Blockchain-specific address of offer asset
askAssetAddress
Address
Blockchain-specific address of ask asset
offerUnits
string
The amount of offer asset the trader must pay, including all fees
askUnits
string
The amount of ask asset the trader will get after all fees
referrerAddress
Address | undefined
The address of referrer that will receive the fees
referrerFeeUnits
string
The amount of fees that the referrer will get (in units of offerAssetAddress
)
protocolFeeUnits
string
The amount of fees charged by the protocol (in units of offerAssetAddress
).
quoteTimestamp
number
The timestamp (UTC seconds) of Quote sent by resolver
tradeStartDeadline
number
Max timestamp (UTC seconds) of start of the trade
gasBudget
string
The amount of gas budget for the trade
params
object | undefined
Various parameters specific to the settlement method. See the source code for more details.
Now that we have a quote, we should request a server to build a transaction to initiate the trade that the user can verify and sign.
The buildTransfer
method takes a TransactionRequest
object as a parameter, having the following properties:
quote
Quote
The valid quote received from Omniston.requestForQuote
sourceAddress
Address
The address on offerBlockchain
that will send initial transaction to start the trade
destinationAddress
Address
The address on askBlockchain
that will receive result of the trade
You can send messages
to any library of your choice. Take a look at our transaction sending guide with examples of different popular packages
After the user has signed and initiated the transaction, we can track the trade status.
The trackTrade
method has the following parameters:
quoteId
string
ID of the quote received from Omniston.requestFromQuote
traderWalletAddress
Address
The address of trader's wallet that initiated transaction
outgoingTxHash
string
Hash of the transaction that initiated the trade
It returns Observable<TrackTradeStatus>
. For the different trade status values, see the source code. We are interested in the trade result enum which can be read from status.tradeSettled?.result?
field. The enum has the following values:
TRADE_RESULT_FULLY_FILLED
The trade has been completed and fully filled.
TRADE_RESULT_PARTIALLY_FILLED
The trade has been partially filled. Something went wrong.
TRADE_RESULT_ABORTED
The trade has been aborted.
TRADE_RESULT_UNKNOWN
UNRECOGNIZED
Settlement of the trade by direct swap using third-party contracts.
A protocol user who performs the token exchange.
Service providing a token exchange rate, also known as Market Maker
.
Data types used:
Blockchain
Number. Blockchain code as defined by SLIP-044. (https://github.com/satoshilabs/slips/blob/master/slip-0044.md)
For TON
, it is 607
.
Address
Object. It consists of two fields:
blockchain
- blockchain of the asset,
address
- address of assets, wallets in the specified Blockchain
.
For example:
Amount
String. Amount of assets in units.
SettlementMethod
Number. The method of trade settlement. Value of enum of settlement methods. Currently, supports only Swap
settlement method, which is 0
.
Protocol
Number. The protocol of swap settlement. Currently, it supports:
StonFiV1
= 1: STON.fi DEX v1 protocol
StonFiV2
= 2: STON.fi DEX v2 protocol
DeDust
= 3: DeDust DEX protocol
Number
Integer number.
RequestSettlementParams
Object. Additional parameters for the quote request (RFQ):
max_price_slippage_bps
: Maximum price slippage, in basis points (0.01%). For example, 100 = 1% slippage.
max_outgoing_messages
: Maximum number of outgoing messages supported by the wallet. For TON blockchain, this defaults to 4 if omitted.
Note: These parameters are general RFQ settings and may be used across different settlement methods. They are not specific to any particular settlement method.
SwapSettlementParams
Object. Settlement parameters specific to the swap settlement method. This type is used in the Quote's params
field when the settlement method is swap. Contains:
routes
: Array of SwapRoute
objects that define the possible paths for the swap.
Each SwapRoute
consists of:
steps
: Array of SwapStep
objects describing each step in the swap route
gas_budget
: String indicating the gas budget to complete the transfer
Each SwapStep
contains:
offer_asset_address
: Address object for the asset being offered
ask_asset_address
: Address object for the asset being requested
chunks
: Array of SwapChunk
objects breaking down the swap into smaller operations
Each SwapChunk
represents a single swap operation:
protocol
: Protocol used for this swap operation (e.g., "1")
offer_amount
: Amount of the offered asset
ask_amount
: Expected amount of the asked asset
extra_version
: Version of the extra data format
extra
: Protocol-specific data as a base64-encoded byte array
quote_id
String. A 32-byte identifier of the quote.
Every method name contains version of API. Now it is v1beta6
.
quote
Allows you to create a new request for quote (RFQ
).
Accepts the following parameters as input:
Sample:
After the request (RFQ
), the channel will start receiving quote_updated
events from resolvers, which consist of a quote
. A Quote
in the channel is updated if a more profitable deal for the trader comes in. The Quote
includes the following fields:
For Swap
settlement method the params
is:
Object SwapRoute
:
Object SwapStep
:
Object SwapChunk
:
Sample:
trade.track
Method that allows you to track the status of a token exchange.
Accepts the following parameters as input:
Sample:
The channel will start receiving records about the current status of the transfer. The following statuses are available:
RouteStatus
steps
- Array of StepStatus
objects.
StepStatus
chunks
- Array of ChunkStatus
objects.
ChunkStatus
Samples:
transaction.build_transfer
A request to generate unsigned transfer to initiate the trade.
Accepts the following parameters as input:
Sample:
The response contains a ton
object with the blockchain-specific transaction data:
Each Message
object contains:
For more details on how to populate or interpret the extra
field for these protocols, see the ().
offer_asset_address
Address
Blockchain-specific address of offer asset.
ask_asset_address
Address
Blockchain-specific address of ask asset.
amount
Amount
Either the amount of offer asset or ask asset:
offer_units
- The amount of offer asset the trader wants to pay, including all fees.
ask_units
- The amount of ask asset the trader wants to get after all fees.
referrer_address
Address
The address of referrer that will receive the fees or empty string if referrer is not specified.
referrer_fee_bps
Number
The amount of fees required by the referrer in basis points (1/10000 or 0.01%)
settlement_methods
Array(SettlementMethod)
Supported methods of swap settlement. The protocol limits settlement methods in quotes to specified methods. Different combinations of offer & ask chains might support different methods.
quote_id
String
ID of the quote generated by the platform (32 bytes)
resolver_id
String
ID of the Resolver
resolver_name
String
Name of the Resolver
offer_asset_address
Address
Blockchain-specific address of offer asset.
ask_asset_address
Address
Blockchain-specific address of ask asset.
offer_units
Amount
The amount of offer asset the trader must pay, including all fees.
ask_units
Amount
The amount of ask asset the trader will get after all fees.
referrer_address
Address
The address of referrer that will receive the fees or empty string if referrer is not specified.
referrer_fee_bps
Number
The amount of fees that the referrer will get (in units of offer_asset_address).
protocol_fee_units
Number
The amount of fees charged by the protocol (in units of offer_asset_address).
quote_timestamp
Number
The timestamp (UTC seconds) of Quote sent by resolver.
trade_start_deadline
Number
Max timestamp (UTC seconds) of start of the trade. The start of the trade is defined as the reception of offer asset by the corresponding smart contract. The resolver may still settle the trades started after this deadline has passed at own discretion.
params
Object
Additional parameters specific to settlement method. Details see below
routes
Array(SwapRoute)
Array of Swap routes
steps
Array(SwapStep)
Array of Swap steps
gas_budget
Amount
The amount of gas budget to complete transfer
offer_asset_address
Address
Blockchain-specific address of offer asset.
ask_asset_address
Address
Blockchain-specific address of ask asset.
chunks
Array(SwapChunk)
Array of swap chunks
protocol
Protocol
Protocol of this swap operation
offer_amount
Amount
The amount of offer asset the trader must pay, including all fees.
ask_amount
Amount
The expected amount of ask asset the trader will get after all fees.
extra_version
Number
Version of the extra data format
extra
bytes
Bytes array used by the underlying protocol to coordinate the swap. In JSON form, it is typically base64-encoded. It is not JSON.
quote_id
String
(32 bytes) ID of the quote
trader_wallet_address
Address
The address of trader's wallet that initiated transaction
outgoing_tx_hash
String
Hash of the transaction that initiated the trade
awaiting_transfer
Waiting for the trader to initiate the trade.
transferring
Initial transaction found, waiting for transfer of funds to complete.
swapping
(SWAP method only) Awaiting swap transactions in the pools.
routes
- Info about partial filling of the trade. Array of RouteStatus
.
awaiting_fill
(ESCROW / HTLC only) Waiting for the trade to be filled.
claim_available
(HTLC only) Resolver's deposit is claimable.
refund_available
(ESCROW / HTLC) Deposit timeout has expired, need to refund it.
receiving_funds
The transaction with incoming funds found, waiting for it to mine.
routes
- Info about partial filling of the trade.
trade_settled
The trade has completed (fully or partially filled or fully aborted)
result
- Result of the trade:
- 0
- Unknown
- 1
- fully filled
- 2
- partially filled
- 3
- aborted
routes
- Info about partial filling of the trade. Array of RouteStatus
target_address
Address
Address of the contract that processes this chunk. Generally, this address receives offer tokens. More specifically, it might be the address of a protocol or liquidity pool.
offer_units
Amount
The amount of offer asset transferred from trader wallet
expected_ask_units
Amount
The expected amount of ask asset to be transferred to trader wallet
actual_ask_units
Amount
The actual amount of ask asset transferred to trader wallet
result
Number
Result of the chunk:
- 0
- Processing
- 1
- Filled
- 2
- Aborted
protocol
Protocol
Protocol of this swap operation
tx_hash
String
Hash of the transaction that executed this chunk
source_address
Address
The address on offer_blockchain that will send initial transaction to start the trade
destination_address
Address
The address on ask_blockchain that will receive result of the trade
quote
Quote
The valid quote received from quote
subscription
ton
Object
Contains TON-specific transaction data
ton.messages
Array(Message)
Array of messages to be sent
target_address
String
The address of the recipient
send_amount
String
Amount in nanotons to send as attached value
payload
String
Hex-encoded or base64-encoded transaction data