Reference (v1)

STON.fi DEX v1 SDK methods reference - complete API documentation for router and pool interactions

Router

address

Address of the Router contract

gasConstants

Getters

getPoolAddress

async getPoolAddress(
    provider: ContractProvider,
    params: {
      token0: Address | string;
      token1: Address | string;
    },
): Promise<Address>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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

async getPoolAddressByJettonMinters(
    provider: ContractProvider,
    params: {
      token0: Address | string;
      token1: Address | string;
    },
): Promise<Address>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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

async getPool(
    provider: ContractProvider,
    params: {
      token0: Address | string;
      token1: Address | string;
    },
): Promise<PoolV1>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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

async getRouterData(provider: ContractProvider): Promise<{
    isLocked: boolean;
    adminAddress: Address;
    tempUpgrade: Cell;
    poolCode: Cell;
    jettonLpWalletCode: Cell;
    lpAccountCode: Cell;
}>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Result

Returns structure containing current state of the router.

Name	Type	Description
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

Operations

createSwapBody

async createSwapBody(params: {
    userWalletAddress: Address | string;
    minAskAmount: bigint | number | string;
    askJettonWalletAddress: Address | string;
    referralAddress?: Address | string;
}): Promise<Cell>

Name	Type	Description
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

async getSwapJettonToJettonTxParams(
    provider: ContractProvider,
    params: {
        userWalletAddress: Address | string;
        offerJettonAddress: Address | string;
        askJettonAddress: Address | string;
        offerAmount: bigint | number | string;
        minAskAmount: bigint | number | string;
        referralAddress?: Address | string;
        gasAmount?: bigint | number | string;
        forwardGasAmount?: bigint | number | string;
        queryId?: number | bigint;
    },
): Promise<SenderArguments>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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

Name	Type	Description
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

async getSwapJettonToTonTxParams(
    provider: ContractProvider,
    params: {
        userWalletAddress: Address | string;
        offerJettonAddress: Address | string;
        proxyTon: PtonV1;
        offerAmount: bigint | number | string;
        minAskAmount: bigint | number | string;
        referralAddress?: Address | string;
        gasAmount?: bigint | number | string;
        forwardGasAmount?: bigint | number | string;
        queryId?: number | bigint;
    },
): Promise<SenderArguments>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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

Name	Type	Description
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

async getSwapTonToJettonTxParams(
    provider: ContractProvider,
    params: {
        userWalletAddress: Address | string;
        proxyTon: PtonV1;
        askJettonAddress: Address | string;
        offerAmount: bigint | number | string;
        minAskAmount: bigint | number | string;
        referralAddress?: Address | string;
        forwardGasAmount?: bigint | number | string;
        queryId?: number | bigint;
    },
): Promise<SenderArguments>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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

Name	Type	Description
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

async createProvideLiquidityBody(params: {
    routerWalletAddress: Address | string;
    minLpOut: bigint | number | string;
}): Promise<Cell>

Name	Type	Description
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

async getProvideLiquidityJettonTxParams(
    provider: ContractProvider,
    params: {
        userWalletAddress: Address | string;
        sendTokenAddress: Address | string;
        otherTokenAddress: Address | string;
        sendAmount: bigint | number | string;
        minLpOut: bigint | number | string;
        gasAmount?: bigint | number | string;
        forwardGasAmount?: bigint | number | string;
        queryId?: number | bigint;
    },
): Promise<SenderArguments>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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

Name	Type	Description
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

public async getProvideLiquidityTonTxParams(
    provider: ContractProvider,
    params: {
        userWalletAddress: Address | string;
        proxyTon: PtonV1;
        otherTokenAddress: Address | string;
        sendAmount: bigint | number | string;
        minLpOut: bigint | number | string;
        forwardGasAmount?: bigint | number | string;
        queryId?: number | bigint;
    },
): Promise<SenderArguments>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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

Name	Type	Description
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

Pool

address

Address of the Pool contract

gasConstants

Getters

getPoolData

async getPoolData(provider: ContractProvider): Promise<{
    reserve0: bigint;
    reserve1: bigint;
    token0WalletAddress: Address;
    token1WalletAddress: Address;
    lpFee: bigint;
    protocolFee: bigint;
    refFee: bigint;
    protocolFeeAddress: Address;
    collectedToken0ProtocolFee: bigint;
    collectedToken1ProtocolFee: bigint;
}>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Result

Returns structure containing current state of the pool.

Name	Type	Description
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

async getExpectedOutputs(
    provider: ContractProvider,
    params: {
        amount: bigint | number | string;
        jettonWallet: Address | string;
    },
): Promise<{
    jettonToReceive: bigint;
    protocolFeePaid: bigint;
    refFeePaid: bigint;
}>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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

Name	Type	Description
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.

async getExpectedTokens(
    provider: ContractProvider,
    params: {
        amount0: bigint | number | string;
        amount1: bigint | number | string;
    },
): Promise<bigint>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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.

async getExpectedLiquidity(
    provider: ContractProvider,
    params: {
        jettonAmount: bigint | number | string;
    },
): Promise<{
    amount0: bigint;
    amount1: bigint;
}>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
jettonAmount	bigint | number | string	Amount of liquidity tokens (in basic token units)

Result

Returns structure with expected freed liquidity

Name	Type	Description
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

async getLpAccountAddress(
    provider: ContractProvider,
    params: {
        ownerAddress: Address | string,
    },
): Promise<Address>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
ownerAddress	Address | string	Address of a user

Result

Function getLpAccountAddress returns the lp account address of a user

getLpAccount

async getLpAccount(
    provider: ContractProvider,
    params: {
        ownerAddress: Address | string
    },
): Promise<LpAccountV1>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
ownerAddress	Address | string	Address of a user

Result

returns an instance of LpAccountV1

getJettonData

async getJettonData(
    provider: ContractProvider,
): Promise<{
    totalSupply: bigint,
    isMintable: boolean,
    adminAddress: Address|null,
    jettonContentUri: string|null,
    jettonWalletCode: Cell
}>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Result

Returns a structure with Jetton data

Name	Type	Description
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

getWalletAddress(
    provider: ContractProvider,
    ownerAddress: Address | string,
): Promise<Address>

Arguments

Name	Type	Description
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

async getJettonWallet(
    provider: ContractProvider,
    params: {
        ownerAddress: Address | string;
    },
): Promise<JettonWallet>

Arguments

Name	Type	Description
ownerAddress	Address | string	Address of a user

Name	Type	Description
ownerAddress	Address | string	Address of a user

Result

Function getJettonWallet returns a JettonWallet instance for an address returned by getWalletAddress

Operations

createCollectFeesBody

async createCollectFeesBody(params: {
    queryId?: QueryIdType
}): Promise<Cell>

getCollectFeeTxParams

Build all data required to execute a collect_fees transaction.

async getCollectFeeTxParams(
    provider: ContractProvider,
    params?: {
        gasAmount?: bigint | number | string;
        queryId?: number | bigint;
    },
): Promise<SenderArguments>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
gasAmount	bigint | number | string | undefined	Transaction gas
queryId	bigint | number | undefined	Query id

Result

Name	Type	Description
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

async createBurnBody(params: {
    amount: bigint | number | string;
    responseAddress: Address | string;
    queryId?: number | bigint;
}): Promise<Cell>

getBurnTxParams

Build all data required to execute a burn transaction.

async getBurnTxParams(
    provider: ContractProvider,
    params: {
        amount: bigint | number | string;
        responseAddress: Address | string;
        gasAmount?: bigint | number | string;
        queryId?: number | bigint;
    },
): Promise<SenderArguments>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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

LpAccount

address

Address of the LpAccount contract

gasConstants

Getters

getLpAccountData

async getLpAccountData(provider: ContractProvider): Promise<{
    userAddress: Address;
    poolAddress: Address;
    amount0: bigint;
    amount1: bigint;
}>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Result

Returns structure containing current state of the lp account.

Name	Type	Description
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)

Operations

createRefundBody

async createRefundBody(params?: {
    queryId?: QueryIdType
}): Promise<Cell>

getRefundTxParams

Build all data required to execute a refund_me transaction.

async getRefundTxParams(
    provider: ContractProvider,
    params?: {
        gasAmount?: bigint | number | string;
        queryId?: number | bigint;
    },
): Promise<SenderArguments>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
gasAmount	bigint | number | string | undefined	Transaction gas
queryId	bigint | number | undefined	Query id

Result

Name	Type	Description
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

async createDirectAddLiquidityBody(params: {
    amount0: bigint | number | string;
    amount1: bigint | number | string;
    minimumLpToMint?: bigint | number | string;
    queryId?: number | bigint;
}): Promise<Cell>

getDirectAddLiquidityTxParams

Build all data required to execute a direct_add_liquidity transaction.

async getDirectAddLiquidityTxParams(
    provider: ContractProvider,
    params: {
        amount0: bigint | number | string;
        amount1: bigint | number | string;
        minimumLpToMint?: bigint | number | string;
        gasAmount?: bigint | number | string;
        queryId?: number | bigint;
    },
): Promise<SenderArguments>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
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

Name	Type	Description
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

async createResetGasBody(params?: {
    queryId?: QueryIdType
}): Promise<Cell>

getResetGasTxParams

Build all data required to execute a reset_gas transaction.

async getResetGasTxParams(
    provider: ContractProvider,
    params?: {
        gasAmount?: bigint | number | string;
        queryId?: number | bigint;
    },
): Promise<SenderArguments>

Arguments

Name	Type	Description
provider	ContractProvider	Instance of @ton/core contract provider

Name	Type	Description
gasAmount	bigint | number | string | undefined	Transaction gas
queryId	bigint | number | undefined	Query id

Result

Name	Type	Description
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