How tou build routes using our API?
(input token -> output token)
or
indirect (input token -> token1 -> token2 -> ... -> output token)
. By splitting the amount of the input token between
several liquidity pools on several decentralized exchanges (DeDust, STONfi, etc), we can reduce the price impact
and get a better price for you.max_length
- maximum path length in tokens, default is 3. If specified, it must be an integer from [2; 5] range. Value of 2 indicates that route can contain only direct-swaps paths (input token -> output token)
. Value of 3, however, states that route may also contain paths with one intermediate token (input token -> token1 -> output token)
.max_splits
- maximum number of splits, default is 4. If specified, it must be an integer from [1; 20] range. Each split is a distinct path, therefore a distinct blockchain-message that will need to be sent. Currently, wallet contract implementations up to version 4 support not more than 4 messages in a single transaction. Starting from version 5, the number of message in a single transaction has been raise to 255 (but ours upper limit is 20)
. pool_selector
is an optional property that allows you to control which liquidity pools can be used whilst building the route.
blockchains
- allows you to limit liquidity pools to given blockchains only. Currently swap.coffee does not support cross-chain swaps, but who knows what will happen tomorrow 🙂 If you’re certain that you won’t like performing cross-chain swaps in the future, set this property to [“ton”] value. By default, all supported blockchains are used.dexes
- allows you to limit liquidity pools to given dexes only. By default, all supported DEXes are used.max_volatility
- allows you to filter out those liquidity pools, whose price volatility over the last 15 minutes exceeded the given value. The higher the value, the more volatile liquidity pools may be used.slippage
to 0.1, it means that transaction within blockchain must be aborted if any of the swaps lead to obtaining less than 1 - 0.1 = 0.9 = 90%
of amount predicted by swap.coffee backend in returned route. Due to async nature of TON blockchain, such slippage
abortion can also lead to a situation where the sender is left with neither the input nor the output tokens, but an intermediate one.
There are also tokens that can’t be swapped directly, because they don’t share a liquidity pool. Therefore, if you setup parameters so that only direct swaps allowed (i.e. if max_length
is equal to 2), an empty route will be built for you.
output_amount
parameter. Those swaps, in comparison to direct swaps (when you specify input_amount
instead), may be significantly less profitable. They also do not support splitting, which means that resulting route (if exists) will always contain a single path.
buildMultiAssetRoute
function of the RoutingApi
. This function is similar to its single-asset counterpart (buildRoute
), but designed for multiple inputs.
Here are the key differences from buildRoute
:
input_token: ApiTokenAddress
and input_amount: number
, buildMultiAssetRoute
accepts a single input_assets
parameter.input_assets
is an array of ApiMultiAssetInputAsset
object, where each one has the following structure: { asset: ApiTokenAddress, amount: number }
buildMultiAssetRoute
does not support output_amount
field.buildMultiAssetRoute
returns an ApiMultiAssetRoute
object.ApiRoute
object (returned by buildRoute
) describes a single swap operation and contains fields like input_token
, output_token
, input_amount
, output_amount
, and paths
.ApiMultiAssetRoute
object (returned by buildMultiAssetRoute
) aggregates information for the multi-asset swap:
routes: ApiRoute[]
field. Each element here is an ApiRoute
object, representing one part of the multi-asset swap.output_token: ApiToken
field, representing a single output token of the multi-asset swap.total_output_amount
, total_savings
, total_estimated_cashback_usd
, etc., summing up corresponding values from all individual routes.buildMultiAssetRoute
to swap both TON and USDT for CES:
route_id
field. It can be used to check the result of the route’s transactions on the blockchain.
succeeded
, failed
or timed_out
).
route_id
into getTransactionsResult()
you can obtain current state of the route’s transactions execution status. Response is as follows:
buildTransactionsV2
method with.
Each element of the steps
corresponds to a single swap within transaction. For example, if transaction is
A -> B -> C
, then first entry in steps describes A -> B
swap, and the second one describes B -> C
.
TX_STATUS
is a status of a single transaction (related to a single path):
pending
indicates that none of transaction’s swaps have occurred in the blockchain yet.partially_complete
- some (but not all) of transaction’s swaps have occurred in the blockchain.succeeded
- all of transaction’s swaps have successfully executed in blockchain.failed
- one of transaction’s swaps has been aborted due to slippage tolerance.timed_out
- our service could not wait enough for at least one of transaction’s swaps to be present in the
blockchain. This happens if more than 5 minutes have passed since the transaction was generated by our service
until the user sent it, or if more than 3 minutes have passed since the previous swap for this transaction
appeared in the blockchain.SWAP_STATUS
is a status of a single swap within a transaction:
pending
indicates that this swap didn’t happen yet.cancelled
- swap has been cancelled due to one of the previous swaps within same transaction failure or timeout.succeeded
- swap successfully executed.failed
- swap has been aborted due to slippage tolerance.timed_out
- our service could not wait enough for this swap to be present in the blockchain.input
and output
fields are presented only if at least one swap has already moved to status
succeeded
or failed
.input
and output
fields are presented only if swap’s status is succeeded
or failed
. On failure
(abortion due to slippage tolerance) output
is equal to input
.route_id
(and transactions) is generated via
buildTransactionsV2
.
If all transactions are in terminal status (one of succeeded
, failed
or timed_out
), further receipt of this
route’s status will be possible only for 1 minute, after which it will be invalidated from our service’s cache.
custom_fee
property to the transaction construction method:
custom_fee
specification looks as follows:
fixed_fee
is specified in nano-TONs and must not be less than
10_000_000
, which equals 0.01 TON.
percentage_fee
is specified in a parts on 1/1_000_000
: 1
stands for 0.0001%
and 1_000_000
stands for 100%
.
Whilst using this method, you must also specify min_percentage_fee_fixed
property, which, as much as fixed_fee
,
must not be less than 10_000_000
, which equals 0.01 TON. It is also up to you whether you want to limit fee value
from the above by setting max_percentage_fee_fixed
property.
Overall, the final formula for volume-percentage based fee is as follows:
max_wallet_txs - 1
splits: it is configurable during buildRoute
invocation (as shown above).
Default value of max_splits
for buildRoute
is 4. So, if you haven’t specified that property before, it’s time to
start doing so. If you have tools to determine user’s wallet version, you may set it to 3
for walletV4 and to 20
for walletV5. Otherwise, you can just leave it at 3
, because in most circumstances this is more than enough for a
good route to be built.