Routing

​

How our routing works

1. You provide the input token, the output token and the amount you want to swap.
2. We build the optimal route for you. This route can be direct (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.
3. We build the transactions that will swap the tokens.
4. You send the transactions to the blockchain.
5. If slippage is tolerated or deadline exceeds (in rare cases of blockchain lags), the transaction is being (possibly partially) reverted. Otherwise, you receive the output token in your wallet.

​

Basic usage

Swapping assets using our SDK and TonConnect SDK:

import {ApiTokenAddress, RoutingApi} from "@swap-coffee/sdk";
import TonConnect, {WalletInfo, WalletInfoRemote} from "@tonconnect/sdk";

const connector = await setupTonConnect()
const routingApi = new RoutingApi()

const assetIn: ApiTokenAddress = {
    blockchain: "ton",
    address: "native" // stands for TON
}
const assetOut: ApiTokenAddress = {
    blockchain: "ton",
    address: "EQCl0S4xvoeGeFGijTzicSA8j6GiiugmJW5zxQbZTUntre-1" // CES
}

const input_amount = 5 // 5 TON

// let's build an optimal route
const route = await routingApi.buildRoute({
    input_token: assetIn,
    output_token: assetOut,
    input_amount: input_amount,
})

// then we can build transactions payload
const transactions = await routingApi.buildTransactionsV2({
    sender_address: connector.account?.address!!, // address of user's wallet
    slippage: 0.1, // 10% slippage
    paths: route.data.paths,
})

let messages = []

for (const transaction of transactions.data.transactions) {
    // swap.coffee takes care of all the boring stuff here :)
    messages.push({
        address: transaction.address,
        amount: transaction.value,
        payload: transaction.cell,
    })
}

// just send the transaction to the user
await connector.sendTransaction({
    validUntil: Date.now() + 5 * 60 * 1000,
    messages: messages,
})

​

Advanced usage

There are extra settings that you’re able to modify in case you want more control over how routes are built.

The following parameters can be configured:

• 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).

const route = await routingApi.buildRoute({
    input_token: assetIn,
    output_token: assetOut,
    input_amount: input_amount,
    max_length: 4 // allow up to 2 intermediate tokens
});

• 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).

const route = await routingApi.buildRoute({
    input_token: assetIn,
    output_token: assetOut,
    input_amount: input_amount,
    max_splits: 2
});

• 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.

​

Difference between direct and indirect routes

Direct routes without intermediate tokens are usually more safe, but less profitable. Indirect routes with intermediate tokens are usually more profitable, but less safe, because the price of intermediate tokens can change during the transaction and chance that your may receive intermediate tokens instead of the desired output token is higher.

It’s called “slippage” - the difference between the expected price and the actual price. For example, when you set 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.

​

ExactOut swaps

If you want to receive an exact amount of output tokens, you can specify the 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.

const route = await routingApi.buildRoute({
    input_token: assetIn,
    output_token: assetOut,
    output_amount: 200 // desired amount of output token
});

​

Checking transaction results

Along with the transaction built, you receive the route_id field. It can be used to check the result of the route’s transactions on the blockchain.

​

Basic usage

SDK contains inbuilt method for waiting execution results of route’s transactions. Promise will be resolved when all transactions are in terminal status (one of succeeded, failed or timed_out).

import {ApiTokenAddress, RoutingApi, waitForTransactionResults} from "@swap-coffee/sdk";

const connector = await setupTonConnect();
const routingApi = new RoutingApi();

const assetIn: ApiTokenAddress = {
  blockchain: 'ton',
  address: 'native', // stands for TON
};
const assetOut: ApiTokenAddress = {
  blockchain: 'ton',
  address: 'EQCl0S4xvoeGeFGijTzicSA8j6GiiugmJW5zxQbZTUntre-1', // CES
};

const route = await routingApi.buildRoute({
  input_token: assetIn,
  output_token: assetOut,
  input_amount: 5, // 5 TON
});

const transactions = await routingApi.buildTransactionsV2({
  sender_address: connector.account?.address!!,
  slippage: 0.1,
  paths: route.data.paths, // note: use route.data here
});


let messages = [];

for (const transaction of transactions.data.transactions) {
  messages.push({
    address: transaction.address,
    amount: transaction.value,
    payload: transaction.cell,
  });
}

await connector.sendTransaction({
  validUntil: Date.now() + 5 * 60 * 1000,
  messages: messages,
});

const results = await waitForTransactionResults(transactions.data.route_id, routingApi);

for (const result of results) {
  // handle result for each route's paths
}

​

Advanced usage

By passing route_id into getTransactionsResult() you can obtain current state of the route’s transactions execution status. Response is as follows:

[
  {
    "status": "TX_STATUS",
    "steps": [
      {
        "status": "SWAP_STATUS",
        "input": {
          "token_blockchain": "ton",
          "token_address": "EQ...1",
          "amount": 1.2345
        },
        "output": {
          "token_blockchain": "ton",
          "token_address": "EQ...2",
          "amount": 2.3456
        }
      }
    ],
    "input": {
      "token_blockchain": "ton",
      "token_address": "EQ...1",
      "amount": 1.2345
    },
    "output": {
      "token_blockchain": "ton",
      "token_address": "EQ...2",
      "amount": 2.3456
    }
  }
]

Each element of the returned array corresponds to a path at the same index that you provided 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.
• Transaction’s input and output fields are presented only if at least one swap has already moved to status succeeded or failed.
• Swap’s 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.

The route status can be requested within 2 hours from the moment 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 fees (for partners only)

Starting January 2025 various DEXes stopped sharing their fees with aggregators like swap.coffee. We understand the desire of our partners to continue earning on user transactions, and therefore we provide functionality for charging additional fees.

To do so, it is enough to pass the custom_fee property to the transaction construction method:

// building the route itself
const route = await routingApi.buildRoute({
    input_token: assetIn,
    output_token: assetOut,
    input_amount: input_amount,
    max_splits: 3 // Important! Please, continue reading to understand why
})

// building transactions of the route
const transactions = await routingApi.buildTransactionsV2({
    sender_address: connector.account?.address!!, // address of user's wallet
    slippage: 0.1, // 10% slippage
    paths: route.data.paths,
    referral_name: '#YOUR_REFERRAL_NAME#',
    custom_fee: {
        fixed_fee: 'value',
        percentage_fee: 'value',
        min_percentage_fee_fixed: 'value',
        max_percentage_fee_fixed: 'value'
    }
})

As you can see, there are multiple opportunities to set up custom fees collection. Let’s dive into them!

First of all, custom_fee specification looks as follows:

export interface ApiTransactionsCustomFee {
    /**
     * Value in nanotons
     * @type {string}
     * @memberof ApiTransactionsCustomFee
     */
    'fixed_fee'?: string;
    /**
     * Value in 1/1000000: 1 is 0.0001%, 1000000 is 100%. If present, can not be less than 10000000 (0.01 TON)
     * @type {number}
     * @memberof ApiTransactionsCustomFee
     */
    'percentage_fee'?: number;
    /**
     * Value in nanotons. No less than this value may be withdrawn as a percentage_fee. Must be set if percentage_fee is present. Can not be less than 10000000 (0.01 TON)
     * @type {string}
     * @memberof ApiTransactionsCustomFee
     */
    'min_percentage_fee_fixed'?: string;
    /**
     * Value in nanotons. If set, no more than this value may be withdrawn as a percentage_fee. Taken into account only if percentage_fee is present
     * @type {string}
     * @memberof ApiTransactionsCustomFee
     */
    'max_percentage_fee_fixed'?: string;
}

You can charge fixed, volume-percentage based or even both fees every time user performs a swap throughout your service. Each method adds additional transaction to the list given to the user for signing. Regardless of the method chosen and tokens of the swap, fees are always charged in TONs.

Please, keep in mind that whatever value you set, it is not the amount you will receive: all custom fees are divided equally between our partners and swap.coffee itself, which means that you will get only half of what you request from users there.

​

Fixed fee

This method is for those cases when you want to charge the same level of commission on all trades through your service, regardless of the trade volume. Please keep in mind that fixed_fee is specified in nano-TONs and must not be less than 10_000_000, which equals 0.01 TON.

​

Volume-percentage based fee

If you want to charge more commission the larger the trade the user makes, this method is for you. 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:

ref_fee = max(
    max_percentage_fee_fixed,
    min(
        min_percentage_fee_fixed,
        volume_usdt * percentage_fee / 1_000_000
    )
)

​

Thinking of max splits

Because of custom fees being withdrawn as a separate transactions, it is very important to keep in mind that wallet contracts have a limitation of how much transactions they may send at once: no more than 4 for walletV4 and no more than 255 for walletV5.

That’s why, when adding custom fees, you must guarantee that the route for which you are building transactions contains no more than 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.