POST
/
v1
/
route
curl --request POST \
  --url https://backend.swap.coffee/v1/route \
  --header 'Content-Type: application/json' \
  --data '{
  "input_token": {
    "blockchain": "ton",
    "address": "native"
  },
  "output_token": {
    "blockchain": "ton",
    "address": "native"
  },
  "input_amount": 1,
  "output_amount": 1,
  "max_splits": 4,
  "max_length": 3,
  "pool_selector": {
    "blockchains": [
      "ton"
    ],
    "dexes": [
      "dedust"
    ],
    "max_volatility": 1
  },
  "mev_protection": true,
  "additional_data": {
    "sender_address": "UQCNTO0Nh0Z7QNyRW1BLWfk08f2dAOw4izrx9sO6OUPg4DoV",
    "referral_name": "tonkeeper"
  }
}'
{
  "input_token": {
    "address": {
      "blockchain": "ton",
      "address": "native"
    },
    "metadata": {
      "name": "ARBUZ",
      "symbol": "ARBUZ",
      "decimals": 123,
      "image_url": "<string>",
      "listed": true
    }
  },
  "output_token": {
    "address": {
      "blockchain": "ton",
      "address": "native"
    },
    "metadata": {
      "name": "ARBUZ",
      "symbol": "ARBUZ",
      "decimals": 123,
      "image_url": "<string>",
      "listed": true
    }
  },
  "input_amount": 123,
  "output_amount": 123,
  "input_usd": 123,
  "output_usd": 123,
  "savings": 123,
  "left_amount": 123,
  "recommended_gas": 123,
  "price_impact": 123,
  "estimated_cashback_usd": 123,
  "partner_commission_ton": 123,
  "mev_protection_fee": 123,
  "paths": [
    {
      "blockchain": "ton",
      "dex": "stonfi",
      "pool_address": "<string>",
      "input_token": {
        "address": {
          "blockchain": "ton",
          "address": "native"
        },
        "metadata": {
          "name": "ARBUZ",
          "symbol": "ARBUZ",
          "decimals": 123,
          "image_url": "<string>",
          "listed": true
        }
      },
      "output_token": {
        "address": {
          "blockchain": "ton",
          "address": "native"
        },
        "metadata": {
          "name": "ARBUZ",
          "symbol": "ARBUZ",
          "decimals": 123,
          "image_url": "<string>",
          "listed": true
        }
      },
      "swap": {
        "result": "fully_fulfilled",
        "input_amount": 123,
        "output_amount": 123,
        "before_reserves": [
          123
        ],
        "after_reserves": [
          123
        ],
        "reason": "<string>",
        "left_amount": 123
      },
      "recommended_gas": 123,
      "average_gas": 123,
      "next": [
        {}
      ]
    }
  ]
}

Authorizations

​
X-Api-Key
string
header
required

Body

application/json
​
input_token
object
required
​
output_token
object
required
​
input_amount
number

Input amount in tokens (not nano!) to be swapped

Required range: x > 0
​
output_amount
number

If specified, the route will be built to get the specified output amount. If not specified, the route will be built to get the maximum output amount for the given input amount.

Required range: x > 0
​
max_splits
integer
default:4

Defines the maximum number of independent paths (i.e., transactions) the route can split into. For v4 wallets, you can omit this or set it to 4; for v5 wallets, you can set it to 20 (this is our internal upper limit, and we may reduce it later to something like 10).

Required range: 1 <= x <= 20
​
max_length
integer
default:3

Defines the maximum length of each path in tokens. It accepts values from [2; 5]. If it's 2, only direct swaps A -> B without multihops are possible. If it's 3, there can be a maximum of 1 intermediate token, i.e., A -> X -> B. If it's 4/5, there can be 2/3 intermediate tokens. A value of 2 deprives you of more profitable exchanges by finding market inefficiencies and does not allow you to exchange tokens without a direct pair (since there can be no intermediate tokens). The higher the value, the more profitable routes can be built, but the higher the likelihood that the user ends up with an intermediate token (since our blockchain is asynchronous, and some swap in the middle of the route may fail due to slippage).

Required range: 2 <= x <= 5
​
pool_selector
object

Configures the DEX pools that can appear in the generated route. By setting blockchains = ["ton"] inside it, you can remove the dexes field; max_volatility allows you to exclude pools whose volatility has been above a certain percentage in the last 15 minutes. This makes sense when you allow 2-3 intermediate tokens or a large number of splits to smooth out potential issues.

​
mev_protection
boolean

Whether a MEV protection should be enabled

Example:

true

​
additional_data
object

Response

200
application/json
resulting route
​
input_token
object
required
​
output_token
object
required
​
input_amount
number
required
​
output_amount
number
required
​
input_usd
number
required
​
output_usd
number
required
​
recommended_gas
number
required
​
price_impact
number
required
​
paths
object[]
required
​
savings
number
​
left_amount
number
​
estimated_cashback_usd
number
​
partner_commission_ton
number
​
mev_protection_fee
number

Fees for the usage of MEV protection.