Router

This section contains op codes of the router contract as well as corresponding SDK methods

Off-chain get methods
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.
FunC
TypeScript
(slice) get_pool_address(slice token0, slice token1) method_id;
async getPoolAddress(params: {
    token0: AddressType
    token1: AddressType
}): Promise<Address | null>
Arguments
Key
Type
Index
Description
token0
AddressType
0
The address of the router's wallet of first Jetton
token1
AddressType
1
The address of the router's wallet of second Jetton
Result
Returns single slice with the address of liquidity pool for specified pair of Jettons.
Additional functions
TypeScript
async getPool(params: {
    jettonAddresses: [AddressType, AddressType];
}): Promise<Pool | null>
Arguments
Key
Type
Description
jettonAddresses
[AddressType, AddressType]
Tuple of Jetton addresses of a pool
Result
Returns a Pool object for a pool with specified Jetton token addresses.
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.
FunC
TypeScript
(int, slice, cell, cell, cell, cell) get_router_data() method_id;
async getData(): Promise<RouterData>
Arguments
None
Result
Returns RouterData structure containing current state of the router.
RouterData structure
Key
Type
Index
Description
isLocked
boolean
0
true if transfer_notification operations are locked (swap, provide_lp)
adminAddress
Address
1
Address of contract's admin account
tempUpgrade
Cell
2
A structure describing state of contract's code & admin upgrade; zero values indicate that no upgrade is pending
poolCode
Cell
3
Code of the router's liquidity pool contract
jettonLpWalletCode
Cell
4
Code of lp wallet contract
lpAccountCode
Cell
5
Code of lp account contract
​
transfer_notification operations
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.
TL-B
transfer_notification#7362d09c query_id:uint64 jetton_amount:Grams from_user:MsgAddress ref_msg_data:^DexPayload = InternalMsgBody;
Message body
Name
Type
Description
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 body
Name
Type
Description
transferred_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
Transfer operations table
Name
Value
Description
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.
TL-B
swap_op#25938561 = SwapOP;
swap$_ transferred_op:SwapOP token_wallet1:MsgAddress min_out:Grams to_address:MsgAddress ref_address:(Either MsgAddress MsgAddress) = DexPayload;
ref_msg_data body
Name
Type
Description
transferred_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
Outgoing messages
Sends a message with op swap to a liquidity pool
Build transaction
Build swap transaction.
TypeScript
async buildSwapJettonTxParams(params: {
    userWalletAddress: AddressType;
    offerJettonAddress: AddressType;
    askJettonAddress: AddressType;
    offerAmount: AmountType;
    minAskAmount: AmountType;
    forwardGasAmount?: AmountType;
    queryId?: QueryIdType;
    referralAddress?: AddressType;
  }): Promise<MessageData>
​
async buildSwapProxyTonTxParams(params: {
    userWalletAddress: AddressType;
    proxyTonAddress: AddressType;
    askJettonAddress: AddressType;
    offerAmount: AmountType;
    minAskAmount: AmountType;
    forwardGasAmount?: AmountType;
    referralAddress?: AddressType;
    queryId?: QueryIdType;
  }): Promise<MessageData>
params structure
Key
Type
Description
userWalletAddress
AddressType
User's address
offerJettonAddress | proxyTonAddress
AddressType
Jetton address of a token to be swapped or proxy ton contract address
askJettonAddress
AddressType
Jetton address of a token to be received
offerAmount
AmountType
Amount of tokens to be swapped (in basic token units)
minAskAmount
AmountType
Minimum amount of tokens to be received (in basic token units)
forwardGasAmount
AmountType | undefined
Optional; forward amount of gas for the next transaction (in nanoTons)
referralAddress
AddressType | undefined
Optional; referral address
queryId
QueryIdType | undefined
Optional; query id
MessageData structure
Name
Type
Description
to
Address
Address of the router's Jetton wallet for the swapped token
payload
Cell
Payload created by createSwapBody
gasAmount
BN
Recommended amount of $TON (in nanoTons) sent as gas
Notes:
the swap will fail if a user should receive less than minAskAmount of tokens as a result
if forwardGasAmount is not specified the default value is 0.265 $TON
the default value for gasAmount is equal to 0.3 $TON
Create payload
Create a payload to initiate a swap transaction.
TypeScript
async createSwapBody(params: {
    userWalletAddress: AddressType;
    minAskAmount: AmountType;
    askJettonWalletAddress: AddressType;
    referralAddress?: AddressType;
}): Promise<Cell>
params structure
Key
Type
Description
userWalletAddress
AddressType
User's address
minAskAmount
AmountType
Minimum amount of tokens received (in basic token units)
askJettonWalletAddress
AddressType
Jetton router's wallet address of tokens to be received
referralAddress
AddressType
Optional; referral address
Notes:
the swap will fail if a user should receive less than minAskAmount of tokens as a result
if forwardGasAmount is not specified the default value is 0.265 $TON
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.
TL-B
provide_lp_op#fcf9e58f = ProvideLpOP;
provide_lp$_ transferred_op:ProvideLpOP token_wallet1:MsgAddress min_lp_out:Grams = DexPayload;
ref_msg_data body
Name
Type
Description
transferred_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)
Outgoing messages
Sends a message with op provide_lp to a liquidity pool
Build transaction
Build provide_lp transactions for the first and the second Jetton token of the pair or TON-Jetton pair.
TypeScript
async buildProvideLiquidityJettonTxParams(params: {
    userWalletAddress: AddressType;
    sendTokenAddress: AddressType;
    otherTokenAddress: AddressType;
    sendAmount: AmountType;
    minLpOut: AmountType;
    forwardGasAmount?: AmountType;
    queryId?: QueryIdType;
  }): Promise<MessageData>
​
public async buildProvideLiquidityProxyTonTxParams(params: {
    userWalletAddress: AddressType;
    proxyTonAddress: AddressType;
    otherTokenAddress: AddressType;
    sendAmount: AmountType;
    minLpOut: AmountType;
    forwardGasAmount?: AmountType;
    queryId?: QueryIdType;
  }): Promise<MessageData>
params structure
Key
Type
Description
userWalletAddress
AddressType
User's address
sendTokenAddress | proxyTonAddress
AddressType
Address of the first Jetton token or a proxy ton contract
otherTokenAddress
AddressType
Address of the second Jetton token
sendAmount
AmountType
Amount of the first/second tokens deposited as liquidity (in basic token units)
minLpOut
AmountType
Minimum amount of created liquidity tokens (in basic token units)
forwardGasAmount
AmountType | undefined
Optional; forward amount of gas for the next transaction (in nanoTons)
queryId
QueryIdType | undefined
Optional; query id
MessageData structure
Name
Type
Description
to
Address
Address of the router's Jetton wallet
payload
Cell
Payload created by createProvideLiquidityBody
gasAmount
BN
Recommended amount of $TON (in nanoTons) sent as gas
Notes:
the provide liquidity operation will fail if a user should receive less than minLpOut of lp tokens as a result
if forwardGasAmount is not specified the default value is 0.265 $TON
the default value for gasAmount is equal to 0.3 $TON
Create payload
Create a payload to initiate a provide_lp transaction.
TypeScript
async createProvideLiquidityBody(params: {
    routerWalletAddress: AddressType;
    minLpOut: AmountType;
}): Promise<Cell>
params structure
Key
Type
Description
routerWalletAddress
AddressType
Address of the router's Jetton token wallet
minLpOut
AmountType
Minimum amount of created liquidity tokens (in basic token units)
Notes:
the provide liquidity operation will fail if a user should receive less than minLpOut of lp tokens as a result
if forwardGasAmount is not specified the default value is 0.265 $TON
​
On-chain queries
On-chain counterparts of getter methods
Operations table
Name
Value
Description
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
TL-B
getter_pool_address#d1db969b query_id:uint64 token0:MsgAddress token1:MsgAddress = InternalMsgBody;
Message Body
Name
Type
Description
token0
address
The address of the router's wallet of first Jetton
token1
address
The address of the router's wallet of second Jetton
Outgoing messages
Sends a message back to the sender with the pool address
Response message body
Name
Type
Description
op
uint32
Operation code equal to getter_pool_address
query_id
uint64
Query id
pool_address
address
Address of a pool
​
On-chain admin operations
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.
Operations table
Name
Value
Description
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.
TL-B
ref_wallets$_ jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress = RefWallets;
set_fees#355423e5 query_id:uint64 new_lp_fee:uint8 new_protocol_fee:uint8 new_ref_fee:uint8 new_protocol_fee_address:MsgAddress ref_wallets:^RefWallets = InternalMsgBody;
Arguments
Name
Type
Description
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 body
Name
Type
Description
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
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)
Outgoing messages
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.
TL-B
collect_fees#1fcb7d3d query_id:uint64 jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress = InternalMsgBody;
Arguments
Name
Type
Description
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
Outgoing messages
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.
TL-B
lock#878f9b0e query_id:uint64 = InternalMsgBody;
Arguments
None.
Outgoing messages
None.
unlock (0x6ae4b0ef)
Allows all transfer_notification messages to go through. Enables swap and provide_lp transactions through this router.
TL-B
unlock#6ae4b0ef query_id:uint64 = InternalMsgBody;
Arguments
None
Outgoing messages
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.
TL-B
init_code_upgrade#df1e233d query_id:uint64 code:^Cell = InternalMsgBody;
Arguments
Name
Type
Description
code
cell
Code of the new router contract
Outgoing messages
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.
TL-B
init_admin_upgrade#2fb94384 query_id:uint64 admin:MsgAddress = InternalMsgBody;
Arguments
Name
Type
Description
admin
address
New admin address
Outgoing messages
None
cancel_admin_upgrade (0xa4ed9981)
Cancels an admin change if there's a pending admin change.
TL-B
cancel_admin_upgrade#a4ed9981 query_id:uint64 = InternalMsgBody;
Arguments
None
Outgoing messages
None
cancel_code_upgrade (0x357ccc67)
Cancels a code upgrade if there's a pending code change.
TL-B
cancel_code_upgrade#357ccc67 query_id:uint64 = InternalMsgBody;
Arguments
None
Outgoing messages
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.
TL-B
finalize_upgrades#6378509f query_id:uint64 = InternalMsgBody;
Arguments
None
Outgoing messages
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.
TL-B
reset_gas#42a0fb43 query_id:uint64 = InternalMsgBody;
Arguments
None
Outgoing messages
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.
TL-B
reset_pool_gas#2fb94384 query_id:uint64 jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress = InternalMsgBody;
Arguments
Name
Type
Description
jetton_wallet0
address
The address of the router's wallet of first Jetton
jetton_wallet1

Key	Type	Index	Description
`isLocked`	`boolean`	0	true if `transfer_notification` operations are locked (`swap`, `provide_lp`)
`adminAddress`	`Address`	1	Address of contract's admin account
`tempUpgrade`	`Cell`	2	A structure describing state of contract's code & admin upgrade; zero values indicate that no upgrade is pending
`poolCode`	`Cell`	3	Code of the router's liquidity pool contract
`jettonLpWalletCode`	`Cell`	4	Code of lp wallet contract
`lpAccountCode`	`Cell`	5	Code of lp account contract

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

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

Key	Type	Description
`userWalletAddress`	`AddressType`	User's address
`offerJettonAddress` \| `proxyTonAddress`	`AddressType`	Jetton address of a token to be swapped or proxy ton contract address
`askJettonAddress`	`AddressType`	Jetton address of a token to be received
`offerAmount`	`AmountType`	Amount of tokens to be swapped (in basic token units)
`minAskAmount`	`AmountType`	Minimum amount of tokens to be received (in basic token units)
`forwardGasAmount`	`AmountType` \| `undefined`	Optional; forward amount of gas for the next transaction (in nanoTons)
`referralAddress`	`AddressType` \| `undefined`	Optional; referral address
`queryId`	`QueryIdType` \| `undefined`	Optional; query id

Name	Type	Description
`to`	`Address`	Address of the router's Jetton wallet for the swapped token
`payload`	`Cell`	Payload created by `createSwapBody`
`gasAmount`	`BN`	Recommended amount of $TON (in nanoTons) sent as gas

Key	Type	Index	Description
`token0`	`AddressType`	0	The address of the router's wallet of first Jetton
`token1`	`AddressType`	1	The address of the router's wallet of second Jetton

Name	Type	Description
`transferred_op`	`uint32`	Additional operation code
`token_wallet1`	`address`	The address of the router's wallet of second Jetton

Name	Value	Description
`swap`	0x25938561	Swap one type of Jetton tokens for another
`provide_lp`	0xfcf9e58f	Provide liquidity; route call to the correct pool

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

Name	Type	Description
`to`	`Address`	Address of the router's Jetton wallet
`payload`	`Cell`	Payload created by `createProvideLiquidityBody`
`gasAmount`	`BN`	Recommended amount of $TON (in nanoTons) sent as gas

Key	Type	Description
`routerWalletAddress`	`AddressType`	Address of the router's Jetton token wallet
`minLpOut`	`AmountType`	Minimum amount of created liquidity tokens (in basic token units)

Name	Type	Description
`op`	`uint32`	Operation code equal to `getter_pool_address`
`query_id`	`uint64`	Query id
`pool_address`	`address`	Address of a pool

Name	Value	Description
`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

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

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