Payload Formats

Swap Payload

To start the swap you need to send the coins to the router wallets with the payload that describes the swap. Ton and jetton transfer differ, but the payload remains mostly the same. This payload you be passed by JettonWallet or ProxyTon to the router contract.

https://docs.tonco.io/technical-reference/contracts/router#jetton_transfer_notification

The swap payload looks like this:

Path	Mnemonic	Type	Description
0	op	Uint(32),op	POOLV3_SWAP (Opcode : 0xa7fb58f8)
0	target_wallet	Address(267)	jetton wallet attached to the router. used to identify swap direction
0	sqrtPriceLimitX96	Uint(160),PriceX96	Limit marginal price. Swap won't go beyond it. This is a price in pool terms - so you need to invert it if pool has swapped the jettons order. It is safe to pass 0 here if you don't care about the price movement For more details see - Price Storage Format and conversion
0	minOutAmount	Coins(124)	Minimum amount of the output jettons to get back. If not reached, your input would be returned to you
0	recipient	Address(267)	The recipient of the swap if it fails (or is payload for mutihop is not present)
	payloads_cell	MaybeCell(1)	Cell with payloads for swap result and change
1	target_address	Address(267)	Target will receive the result of the swap. Could be addr_none() (*00b*) then owner_address is used
1	ok_forward_amount	Coins(124)	Amount of TON to use for forward payload that would be sent with the result of the swap
1	ok_forward_payload	Cell(0),Payload	Payload that would be sent with the jettons of the result of the swap
1	ret_forward_amount	Coins(124)	Amount of TON to use for forward payload that would be sent with the change for the swap (if any)
1	ret_forward_payload	Cell(0),Payload	Payload that would be sent with the jettons of the change of the swap (if any)

Notes

1. Note how the role of owner_address changes depending on whether multihop is enabled on the Router or not. This is needed so that if multihop is disabled asynchronously, there is still a chance that the coins go to the owner.

2. Depending on which token is used as the intermediate, its recipient may differ.

   • For a regular token, the recipient is the wallet owner. For example, if you want to make a swap through USDT, the result of the first swap must be sent back to the Router — so the recipient is the Router.

   • For wtPTon (the TON wrapper), the recipient is the TON wallet address associated with the Router. It directly receives the wrapped TON and, without unwrapping, sends a notification about it to the Router.

     • For reference: our proxyTon is exactly the same as proxyTon from stonfi, only not packed into a library — so you can peek at its behavior in the source code.

3. Gas. When the time comes to send coins along two paths — the result and the change — the gas left after processing by the pool and the Router is split into two parts: ok_forward_amount and ret_forward_amount. If there’s anything left, it is split in half and added to these values before the token is sent. In other words, to receive both the change and the result without knowing in advance how it will turn out, you need to send extra gas along with the swap message: ok_forward_amount + ret_forward_amount + 2 * transfer_fee (~0.048?).