> For the complete documentation index, see [llms.txt](https://docs.tonco.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tonco.io/contracts-v1.6-forthcoming/router.md). # Router ### router * [Description](#description) * [Data Storage](#data-storage) * [Interface](#interface) * [Messages](#messages) ## Description The **Router** is the system's central dispatcher and the custodian of all LP jetton wallets. Users reach the protocol by transferring jettons to the router with a payload (see [router payloads](/contracts-v1.6-forthcoming/router_payloads.md)); the router parses it and routes the funds to the right [Pool](/contracts-v1.6-forthcoming/pool.md) for a swap or for funding a mint. It also deploys new pools (from the Pool Factory or the admin), pays funds back out through its own jetton wallets (PAY\_TO), and supports a multihop shortcut. The router cannot cryptographically verify that a transfer notification came from a real jetton wallet, so it derives the target pool from the sender — a fake sender simply maps to a pool that does not exist. Critical parameters (admin, proxyTON wallet, flags, router/pool code) change only through a two-phase timelock; the admin is expected to be a multisig. ## Interface ### getRouterState (address, address, address, address?, int, int, int) getRouterState () returns the router state and configuration #### Return Values | # | Type | Description | | - | -------- | ---------------------------------------------------------------------------- | | 0 | address | router admin address | | 1 | address | pool admin address (passed to pools on creation; has privileged pool rights) | | 2 | address | pool factory address (allowed to request pool creation) | | 3 | address? | proxy TON wallet address (critial to multihop shortcut) | | 4 | int | router flags | | 5 | int | router seqno (monotonic counter for indexing) | | 6 | int | router version (e.g. 16000 = v1.6.000) | ### getPoolAddress (address) getPoolAddress (jettonWallet0: address, jettonWallet1: address) returns pool address for two given jetton\_wallets belonging to the router #### Parameters | # | Type | Name | Description | | - | ------- | ------------- | -------------------------------------------------- | | 0 | address | jettonWallet0 | Address of the jetton 0 wallet belonging to router | | 1 | address | jettonWallet1 | Address of the jetton 1 wallet belonging to router | #### Return Values | # | Type | Description | | - | ------- | ------------ | | 0 | address | pool address | ### getChildContracts (cell, cell, cell, cell) getChildContracts () returns code of the child contracts *deprecated* #### Return Values | # | Type | Description | | - | ---- | ----------------------------------- | | 0 | cell | code of the pool contract | | 1 | cell | code of the account contract | | 2 | cell | code of the nft position contract | | 3 | cell | code of the pool prototype contract | ### get\_pending\_timelocks ( int, int, address?, int, address?, int, int, int, cell?, int, cell?,) get\_pending\_timelocks () returns active router timelocks to monitor system state. Timestamp 0xFFFFFFFFFFFFFFFF means - never/timelock not active #### Return Values | # | Type | Description | | -- | -------- | ----------------------------------------------------- | | 0 | int | Timelock delay | | 1 | int | Timestamp when new Admin Address can be committed | | 2 | address? | New Admin Address | | 3 | int | Timestamp when new Proxy Ton Address can be committed | | 4 | address? | New Proxy Ton Address | | 5 | int | Timestamp when new flags can be committed | | 6 | int | New Flags | | 7 | int | Timestamp when new code can be committed | | 8 | cell? | Cell with new code | | 9 | int | Timestamp when new pool code can be committed | | 10 | cell? | Cell with new pool code | ## Messages ### JETTON\_TRANSFER\_NOTIFICATION Opcode : **0x7362d09c** Process router funding, payload determines if it is mint or swap\ Access Rights: Sent by a jetton wallet when a user transfers tokens to the router. The router cannot verify that the notification truly comes from a real jetton wallet, so it does not authorize the sender directly: the target pool is derived from the sender, and if the sender is not a genuine wallet the derived pool simply does not exist. Funds that fail validation are returned to the user.
PathMnemonicTypeDescription
opUint(32),op
query_idUint(64)queryid as of the TON documentation
jetton_amountCoins(124)Amount of coins sent to the router
from_userAddress(267)User that originated the transfer
forward_payloadCell(0),Either, PayloadPayload for processing
TL-B Description This is a preliminary tl-b - subject to change {% code title="Tlb for JETTON\_TRANSFER\_NOTIFICATION" overflow="wrap" lineNumbers="true" %} ```javascript JETTON_TRANSFER_NOTIFICATION#7362d09c query_id:uint64 jetton_amount:(VarUInteger 16) from_user:MsgAddress forward_payload:(Either ^Cell Cell) = ContractMessages; ``` {% endcode %}
### ROUTER\_CREATE\_POOL Opcode : **0x2e3034ef** Operation that deploys and inits new [Pool](/contracts-v1.6-forthcoming/pool.md) contract for two given jettons identified by their wallets. New pool would reorder the jettons to match the invariant `slice_hash(jetton0_address) > slice_hash(jetton1_address).`\ Access Rights: Allowed for the Pool Factory and the Router Admin (Superadmin). On a repeated CREATE\_POOL for an existing pool the router forwards an initialization message, which lets the admin change tick spacing, NFT metadata, the initial price (while no positions exist), the Pool Admin and Controller, and the lock state; a request coming through the Pool Factory cannot assign the ALM Vault or Arbiter roles.
PathMnemonicTypeDescription
opUint(32),op
query_idUint(64)queryid as of the TON documentation
jetton_wallet0Address(267)Address of the jetton0 wallet. Used to compute pool address
jetton_wallet1Address(267)Address of the jetton1 wallet. Used to compute pool address
tick_spacingUint(24)Tick spacing to be used in the pool
initial_priceX96Uint(160),PriceX96Initial price for the pool
pool_activeUint(1)Should pool be created as active
protocol_feeUint(16),FeeProtocol fee in FEE_DENOMINATOR parts. If value is more than 10000 value would be default
lp_fee_baseUint(16),FeeLiquidity provider base fee in FEE_DENOMINATOR. If value is more than 10000 value would be default
lp_fee_currentUint(16),FeeCurrent value of the pool fee, in case of dynamic adjustment. If value is more than 10000 value would be default
0Cell(0) roles_cellCell With Role
0has_controllerUint(1),BoolFlag that shows if this message have a new controller address
0controller_addrAddress(267)Address that is allowed to change the fee. Can always be updated by admin.
0has_creatorUint(1),BoolFlag that shows if this message have a new creator address
0creator_addrAddress(267)Address that is allowed to change the fee. Can always be updated by admin. If has_controller is false could be 00b
00Cell(0) privilege_roles_cellCell With Privilege Roles
0->0has_arbiterUint(1),BoolFlag that shows if this message have a new Arbiter address
0->0arbiter_addrAddress(267)Address that is allowed to make privileged swaps
0->0has_almUint(1),BoolFlag that shows if this message have a new ALM address
0->0alm_addrAddress(267)Address that is used to identify ALM contract
01Cell(0) roles_addCell With Additional Roles
0->1has_oracleUint(1),BoolFlag that shows if this message have a new oracle address
0->1oracle_addrAddress(267)Address that is allowed to change the fee. Can always be updated by admin. Could be 00b
1Cell(0) metadata_cellCell With Metainfo
1nftv3_contentCell(0),MetadataMetadata for the NFT Collection
1nftv3item_contentCell(0),MetadataMetadata for the NFT Item
2Cell(0) minter_cellCell With Minters
2jetton0_minterAddress(267)Address of the jetton0 minter, used by indexer and frontend
2jetton1_minterAddress(267)Address of the jetton1 minter, used by indexer and frontend
TL-B Description This is a preliminary tl-b - subject to change {% code title="Tlb for ROUTER\_CREATE\_POOL" overflow="wrap" lineNumbers="true" %} ```javascript ROUTER_CREATE_POOL#2e3034ef query_id:uint64 jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress tick_spacing:uint24 initial_priceX96:uint160 pool_active:uint1 protocol_fee:uint16 lp_fee_base:uint16 lp_fee_current:uint16 roles_cell:^Roles_cellType metadata_cell:^Metadata_cellType minter_cell:^Minter_cellType = ContractMessages; _ has_arbiter:uint1 arbiter_addr:MsgAddress has_alm:uint1 alm_addr:MsgAddress = Privilege_roles_cellType; _ has_oracle:uint1 oracle_addr:MsgAddress = Roles_addType; _ has_controller:uint1 controller_addr:MsgAddress has_creator:uint1 creator_addr:MsgAddress privilege_roles_cell:^Privilege_roles_cellType // optional ref (present only if a ref is left) roles_add:^Roles_addType // optional ref (present only if a ref is left) = Roles_cellType; _ nftv3_content:^Cell nftv3item_content:^Cell = Metadata_cellType; _ jetton0_minter:MsgAddress jetton1_minter:MsgAddress = Minter_cellType; ``` {% endcode %}
### ROUTER\_PAY\_TO Opcode : **0xa1daa96d** This message is the message that is sent to Router by the pool, an it would be accepted only from the pool: Possible error codes | Operation | Error Core | Value | Meaning | | --------- | -------------------------------- | ----- | -------------------------------------------------------- | | SWAP | RESULT\_SWAP\_OK | 200 | Swap went fine | | SWAP | RESULT\_SWAP\_OUTPUT\_TOO\_SMALL | 230 | minAmount was not reached, swap reverted | | SWAP | RESULT\_SWAP\_INTERNAL\_ERROR | 231 | Internal error, generally this should not happen | | SWAP | RESULT\_SWAP\_POOL\_LOCKED | 232 | Attempt to swap in the locked pool | | SWAP | RESULT\_SWAP\_POOL\_EMPTY | 233 | Attempt to swap in the empty pool | | MINT | RESULT\_MINT\_OK | 202 | Mint went fine | | MINT | RESULT\_NO\_LIQUIDITY | 226 | Minting Zero liquidity was asked (not always unintended) | | MINT | RESULT\_TICK\_IMPOSSIBLE\_LOW | 220 | One of the ticks is too low | | MINT | RESULT\_TICK\_IMPOSSIBLE\_HIGH | 221 | One of the ticks is too high | | MINT | RESULT\_WRONG\_TICK\_SPACING | 222 | One of ticks is not divisible by tick\_spacing | | MINT | RESULT\_TOO\_MANY\_TICKS | 223 | Pool is full | | MINT | RESULT\_TOO\_MUCH\_LIQUIDITY | 224 | Too much liquidity in one tick | | MINT | RESULT\_NOT\_ENOUGH\_COINS | 225 | Not enough coins to mint | | BURN | RESULT\_BURN\_OK | 201 | Burn went fine | \ Access Rights: Accepted by the router only from a pool: the sender must match the pool the router itself derives, so no other contract can trigger a payout. The router then sends the funds out through its own jetton wallet. As an exception, when the router's emergency mode is enabled the Router Admin may invoke PAY\_TO directly.
PathMnemonicTypeDescription
opUint(32),op
query_idUint(64)queryid as of the TON documentation
reciever0Address(267)Address of the first receiver of the funds
reciever1Address(267)Address of the second receiver of the funds
exit_code0Uint(8),ErrorCodeMost significant byte. Reforge: result of the first processed order
exit_code1Uint(8),ErrorCodeReforge: result of the second processed order
exit_code2Uint(8),ErrorCodeReforge: result of the third processed order
exit_code3Uint(8),ErrorCodeLeast significant byte. Swap/burn/collect result is here; reforge: fourth order
seqnoUint(64),IndexerInternal pool sequence number
0Maybe Cell(1) coinsinfo_cellCell with info about the coins
0jetton0_addressAddress(267)Jetton to be sent to receiver0 identified by the wallet that belongs to router
0jetton1_addressAddress(267)Jetton to be sent to receiver1 identified by the wallet that belongs to router
0amount0Coins(124)Amount of coins to be payed to receiver0
0amount1Coins(124)Amount of coins to be payed to receiver1
00Cell(0) payload_cellInformation about the payload
0->0payload_amount0Coins(124)Amount of GRAM to forward to receiver0 together with payload_0
0->0payload_0Cell(1),Maybe, PayloadForward payload delivered to receiver0 with the jetton transfer
0->0payload_amount1Coins(124)Amount of GRAM to forward to receiver1 together with payload_1
0->0payload_1Cell(1),Maybe, PayloadForward payload delivered to receiver1 with the jetton transfer
0->0excess_addressAddress(267)Address to receive the excess gas
1Maybe Cell(1) indexer_swap_info_cellIndexer-only. Post-swap pool state (null for non-swap)
1liquidityUint(128),IndexerPost-swap concentrated liquidity at current tick
1price_sqrtUint(160),Indexer,PriceX96Post-swap square root of the price stored as fixed point 64.96
1tickInt(24),IndexerPost-swap current tick
1feeGrowthGlobal0X128Int(256),IndexerCurrent range fee per unit of the liquidity for jetton0
1feeGrowthGlobal1X128Int(256),IndexerCurrent range fee per unit of the liquidity for jetton1
2Maybe Cell(1) positions_cellCell with positions (null for swap/collect)
20Maybe Cell(1) burn0Cell with burn number 0
2->0index[0]Uint(64)Index of the burned position NFT
2->0subindex[0]Uint(4)Subindex
2->0liquidity[0]Uint(128)Position liquidity before this burn
2->0tickLower[0]Int(24)lower bound of the range in which to mint
2->0tickUpper[0]Int(24)upper bound of the range in which to mint
2->0feeGrowthInside0LastX128[0]Int(256),x128Fee counter inside position range for jetton0, per unit of liquidity, in 128.128 fixed point
2->0feeGrowthInside1LastX128[0]Int(256),x128Fee counter inside position range for jetton1, per unit of liquidity, in 128.128 fixed point
2,00Maybe Cell(1) new_fee_cellFee counters to collect to (Used by indexer)
2->0->0feeGrowthInside0CurrentX128[0]Int(256),x128Fee counter inside position range for jetton0, per unit of liquidity, in 128.128 fixed point
2->0->0feeGrowthInside1CurrentX128[0]Int(256),x128Fee counter inside position range for jetton1, per unit of liquidity, in 128.128 fixed point
2->0liquidity2Burn[0]Uint(128)Amount of liquidity that was burned from this position
21Maybe Cell(1) burn1Cell with burn number 1
2->1index[1]Uint(64)Index of the burned position NFT
2->1subindex[1]Uint(4)Subindex
2->1liquidity[1]Uint(128)Position liquidity before this burn
2->1tickLower[1]Int(24)lower bound of the range in which to mint
2->1tickUpper[1]Int(24)upper bound of the range in which to mint
2->1feeGrowthInside0LastX128[1]Int(256),x128Fee counter inside position range for jetton0, per unit of liquidity, in 128.128 fixed point
2->1feeGrowthInside1LastX128[1]Int(256),x128Fee counter inside position range for jetton1, per unit of liquidity, in 128.128 fixed point
2,10Maybe Cell(1) new_fee_cellFee counters to collect to (Used by indexer)
2->1->0feeGrowthInside0CurrentX128[1]Int(256),x128Fee counter inside position range for jetton0, per unit of liquidity, in 128.128 fixed point
2->1->0feeGrowthInside1CurrentX128[1]Int(256),x128Fee counter inside position range for jetton1, per unit of liquidity, in 128.128 fixed point
2->1liquidity2Burn[1]Uint(128)Amount of liquidity that was burned from this position
22Maybe Cell(1) burn2Cell with burn number 2
2->2index[2]Uint(64)Index of the burned position NFT
2->2subindex[2]Uint(4)Subindex
2->2liquidity[2]Uint(128)Position liquidity before this burn
2->2tickLower[2]Int(24)lower bound of the range in which to mint
2->2tickUpper[2]Int(24)upper bound of the range in which to mint
2->2feeGrowthInside0LastX128[2]Int(256),x128Fee counter inside position range for jetton0, per unit of liquidity, in 128.128 fixed point
2->2feeGrowthInside1LastX128[2]Int(256),x128Fee counter inside position range for jetton1, per unit of liquidity, in 128.128 fixed point
2,20Maybe Cell(1) new_fee_cellFee counters to collect to (Used by indexer)
2->2->0feeGrowthInside0CurrentX128[2]Int(256),x128Fee counter inside position range for jetton0, per unit of liquidity, in 128.128 fixed point
2->2->0feeGrowthInside1CurrentX128[2]Int(256),x128Fee counter inside position range for jetton1, per unit of liquidity, in 128.128 fixed point
2->2liquidity2Burn[2]Uint(128)Amount of liquidity that was burned from this position
23Maybe Cell(1) burn3Cell with burn number 3
2->3index[3]Uint(64)Index of the burned position NFT
2->3subindex[3]Uint(4)Subindex
2->3liquidity[3]Uint(128)Position liquidity before this burn
2->3tickLower[3]Int(24)lower bound of the range in which to mint
2->3tickUpper[3]Int(24)upper bound of the range in which to mint
2->3feeGrowthInside0LastX128[3]Int(256),x128Fee counter inside position range for jetton0, per unit of liquidity, in 128.128 fixed point
2->3feeGrowthInside1LastX128[3]Int(256),x128Fee counter inside position range for jetton1, per unit of liquidity, in 128.128 fixed point
2,30Maybe Cell(1) new_fee_cellFee counters to collect to (Used by indexer)
2->3->0feeGrowthInside0CurrentX128[3]Int(256),x128Fee counter inside position range for jetton0, per unit of liquidity, in 128.128 fixed point
2->3->0feeGrowthInside1CurrentX128[3]Int(256),x128Fee counter inside position range for jetton1, per unit of liquidity, in 128.128 fixed point
2->3liquidity2Burn[3]Uint(128)Amount of liquidity that was burned from this position
TL-B Description This is a preliminary tl-b - subject to change {% code title="Tlb for ROUTER\_PAY\_TO" overflow="wrap" lineNumbers="true" %} ```javascript ROUTER_PAY_TO#a1daa96d query_id:uint64 reciever0:MsgAddress reciever1:MsgAddress exit_code0:uint8 exit_code1:uint8 exit_code2:uint8 exit_code3:uint8 seqno:uint64 coinsinfo_cell:(Maybe ^Coinsinfo_cellType) indexer_swap_info_cell:(Maybe ^Indexer_swap_info_cellType) positions_cell:(Maybe ^Positions_cellType) = ContractMessages; _ payload_amount0:(VarUInteger 16) payload_0:(Maybe ^Cell) payload_amount1:(VarUInteger 16) payload_1:(Maybe ^Cell) excess_address:MsgAddress = Payload_cellType; _ jetton0_address:MsgAddress jetton1_address:MsgAddress amount0:(VarUInteger 16) amount1:(VarUInteger 16) payload_cell:^Payload_cellType // optional ref (present only if a ref is left) = Coinsinfo_cellType; _ liquidity:uint128 price_sqrt:uint160 tick:int24 feeGrowthGlobal0X128:int256 feeGrowthGlobal1X128:int256 = Indexer_swap_info_cellType; _ feeGrowthInside0CurrentX128_0:int256 feeGrowthInside1CurrentX128_0:int256 = New_fee_cellType; _ index_0:uint64 subindex_0:uint4 liquidity_0:uint128 tickLower_0:int24 tickUpper_0:int24 feeGrowthInside0LastX128_0:int256 feeGrowthInside1LastX128_0:int256 new_fee_cell:(Maybe ^New_fee_cellType) liquidity2Burn_0:uint128 = Burn0Type; _ feeGrowthInside0CurrentX128_1:int256 feeGrowthInside1CurrentX128_1:int256 = New_fee_cellType1; _ index_1:uint64 subindex_1:uint4 liquidity_1:uint128 tickLower_1:int24 tickUpper_1:int24 feeGrowthInside0LastX128_1:int256 feeGrowthInside1LastX128_1:int256 new_fee_cell:(Maybe ^New_fee_cellType1) liquidity2Burn_1:uint128 = Burn1Type; _ feeGrowthInside0CurrentX128_2:int256 feeGrowthInside1CurrentX128_2:int256 = New_fee_cellType2; _ index_2:uint64 subindex_2:uint4 liquidity_2:uint128 tickLower_2:int24 tickUpper_2:int24 feeGrowthInside0LastX128_2:int256 feeGrowthInside1LastX128_2:int256 new_fee_cell:(Maybe ^New_fee_cellType2) liquidity2Burn_2:uint128 = Burn2Type; _ feeGrowthInside0CurrentX128_3:int256 feeGrowthInside1CurrentX128_3:int256 = New_fee_cellType3; _ index_3:uint64 subindex_3:uint4 liquidity_3:uint128 tickLower_3:int24 tickUpper_3:int24 feeGrowthInside0LastX128_3:int256 feeGrowthInside1LastX128_3:int256 new_fee_cell:(Maybe ^New_fee_cellType3) liquidity2Burn_3:uint128 = Burn3Type; _ burn0:(Maybe ^Burn0Type) burn1:(Maybe ^Burn1Type) burn2:(Maybe ^Burn2Type) burn3:(Maybe ^Burn3Type) = Positions_cellType; ``` {% endcode %}
### ROUTERV3\_RESET\_GAS Opcode : **0x42a0fb43** This operation allows router owners the gas if too much accumulated on the contract\ Access Rights: Allowed only for the Router Admin. Withdraws excess TON that accumulated on the router, leaving enough to keep it funded.
PathMnemonicTypeDescription
opUint(32),op
query_idUint(64)queryid as of the TON documentation
TL-B Description This is a preliminary tl-b - subject to change {% code title="Tlb for ROUTERV3\_RESET\_GAS" overflow="wrap" lineNumbers="true" %} ```javascript ROUTERV3_RESET_GAS#42a0fb43 query_id:uint64 = ContractMessages; ``` {% endcode %}
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tonco.io/contracts-v1.6-forthcoming/router.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.