Routing API

Get the best route for swapping X to Y

Get Best Route

It goes through all the possible DEX & bridges to find the best possible route based on user experience, fee amount, and output of swap.

Get the best route for swapping X to Y

It goes through all the possible DEX & bridges to find the best possible route based on user experience, fee amount, and output of swap

POSThttps://api.rango.exchange:443/routing/best

Query parameters

Header parameters

Body

application/json

affiliateRefstring

The affiliate ref that client likes to send to Rango, so in cases of 1inch, Thorchain, etc. that support affiliation, client will earn some money if user accept the route and signs the transactions

amountnumber (bigdecimal)

The human-readable amount of asset X that is going to be swapped

blockchainsarray of string

The list of all accepted blockchains, empty list means no filter is required

checkPrerequisitesboolean

It should be false when client just likes to preview the route to user, and true when user really accepted to swap. If true, server will be much slower to respond, but will check some pre-requisites including balance of X and required fees in user's wallets

connectedWalletsarray of UserWalletBlockchain

The list of all connected wallets of user in all blockchains

disableMultiStepTxboolean

It should be true when client don't want multi step transactions

fromAssetReq

An asset unique by triple of (blockchain, symbol, address)

previousRequestIdstring

previous response will compare with current request response in order to detect changes

selectedWalletsobject

The list of selected wallets of user for do the swapping operation

swappersarray of string

The list of all accepted swappers, empty list means no filter is required

toAssetReq

An asset unique by triple of (blockchain, symbol, address)

transactionTypesarray of enum

The list of all accepted transaction types containing [EVM, TRANSFER, COSMOS], empty list means no filter is required

Response

200201401403404

OK

Body

*/*

compareStatus*enum

IDENTICALNOTHING_TO_COMPAREPREVIOUS_NOT_FOUNDPREVIOUS_ROUTE_IS_EMPTYREQUESTS_NOT_MATCHEDROUTE_IS_EMPTYSWAPPERS_AND_TOKENS_CHANGEDSWAPPERS_CHANGEDTOKENS_CHANGED

diagnosisMessagesarray of string

A list of string messages that might be cause of not finding the route. It's just for display purposes

fromAssetRes

An asset unique by triple of (blockchain, symbol, address)

missingBlockchainsarray of enum

A warning if not empty, containing list of blockchains that user have no connected wallets for

processingLimitReachedboolean

A warning that indicates that it took too much time to find the best route and server could not find any routes from X to Y

requestAmountnumber (bigdecimal)

The amount from request

requestIdstring

The unique requestId generated for this request by server. It should be passed down to all other endpoints if this swap continues on

resultSimulationResult

Full information of a path of multiple swaps that should be executed by user to swap X to Y

toAssetRes

An asset unique by triple of (blockchain, symbol, address)

validationStatusarray of BlockchainValidationStatus

Pre-requisite check result, it will be null if request.checkPrerequisites is false

walletNotSupportingFromBlockchainboolean

A warning indicating that none of your wallets have the same blockchain as X asset

Request

JavaScriptCurl

const response = await fetch('https://api.rango.exchange:443/routing/best', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "compareStatus": "IDENTICAL",
  "diagnosisMessages": [
    "text"
  ],
  "from": {
    "address": "0x947950bcc74888a40ffa2593c5798f11fc9124c4",
    "blockchain": "ETH",
    "symbol": "SUSHI"
  },
  "missingBlockchains": [
    "AKASH"
  ],
  "processingLimitReached": false,
  "requestAmount": 0.28,
  "requestId": "d10657ce-b13a-405c-825b-b47f8a5096aa",
  "result": {
    "outputAmount": 1.23,
    "resultType": "HIGH_IMPACT",
    "swaps": [
      {
        "estimatedTimeInSeconds": 120,
        "fee": [
          {
            "amount": 0.004,
            "asset": {
              "address": "0x947950bcc74888a40ffa2593c5798f11fc9124c4",
              "blockchain": "ETH",
              "symbol": "SUSHI"
            },
            "expenseType": "FROM_SOURCE_WALLET",
            "name": "Network fee"
          }
        ],
        "from": {
          "address": "0x3232de...ef33",
          "blockchain": "OSMOSIS",
          "decimals": 18,
          "logo": "https://server.com/osmo.png",
          "symbol": "OSMO"
        },
        "fromAmount": 1.2,
        "fromAmountMaxValue": 2.89,
        "fromAmountMinValue": 1.34,
        "fromAmountPrecision": 0,
        "fromAmountRestrictionType": "INCLUSIVE/EXCLUSIVE",
        "fromAsset": {
          "address": "0x947950bcc74888a40ffa2593c5798f11fc9124c4",
          "blockchain": "ETH",
          "symbol": "SUSHI"
        },
        "recommendedSlippage": {
          "error": true,
          "slippage": 8
        },
        "routes": [
          {
            "nodes": [
              {
                "from": "BTC",
                "fromAddress": "0x323afe...3e2",
                "fromBlockchain": "OSMOSIS",
                "fromLogo": "https://server.com/btc.png",
                "nodes": [
                  {
                    "marketId": "Uniswap",
                    "marketName": "Uniswap",
                    "percent": 45
                  }
                ],
                "to": "ETH",
                "toAddress": "0x323afe...3e2",
                "toBlockchain": "AKASH",
                "toLogo": "https://server.com/eth.png"
              }
            ]
          }
        ],
        "swapChainType": "INTER_CHAIN",
        "swapperId": "OneInchBsc",
        "swapperType": "DEX",
        "timeStat": {},
        "to": {
          "address": "0x3232de...ef33",
          "blockchain": "OSMOSIS",
          "decimals": 18,
          "logo": "https://server.com/osmo.png",
          "symbol": "OSMO"
        },
        "toAmount": 1.8,
        "toAsset": {
          "address": "0x947950bcc74888a40ffa2593c5798f11fc9124c4",
          "blockchain": "ETH",
          "symbol": "SUSHI"
        },
        "warnings": [
          "text"
        ]
      }
    ]
  },
  "to": {
    "address": "0x947950bcc74888a40ffa2593c5798f11fc9124c4",
    "blockchain": "ETH",
    "symbol": "SUSHI"
  },
  "validationStatus": [
    {
      "blockchain": "AKASH",
      "wallets": [
        {
          "address": "text",
          "addressIsValid": false,
          "requiredAssets": [
            {
              "asset": {
                "address": "0x947950bcc74888a40ffa2593c5798f11fc9124c4",
                "blockchain": "ETH",
                "symbol": "SUSHI"
              },
              "currentAmount": {
                "amount": 1000000000000000000,
                "decimals": 18
              },
              "ok": false,
              "reason": "FEE",
              "requiredAmount": {
                "amount": 1000000000000000000,
                "decimals": 18
              }
            }
          ],
          "validResult": false
        }
      ]
    }
  ],
  "walletNotSupportingFromBlockchain": false
}

Typescript

const bestRoute = await rangoClient.getBestRoute({
    amount: "1",
    from: {"blockchain": "BSC", "symbol": "BNB", "address": null},
    to: {"blockchain": "TERRA", "symbol": "Luna", "address": null},
    checkPrerequisites: false,
    connectedWallets: [
        {blockchain: "TERRA", addresses: ["terra18vnrzlzm2c4xfsx382pj2xndqtt00rvhu24sqe"]},
        {blockchain: "BSC", addresses: ["0xeae6d42093eae057e770010ffd6f4445f7956613"]}
    ],
    selectedWallets: {
        "TERRA": "terra18vnrzlzm2c4xfsx382pj2xndqtt00rvhu24sqe",
        "BSC": "0xeae6d42093eae057e770010ffd6f4445f7956613",
    },
})

cURL

curl 'https://api.rango.exchange/routing/best?apiKey=YOUR_API_KEY' \
  -H 'content-type: application/json;charset=UTF-8' \
  -H 'x-rango-id: USER_RANDOM_UUID' \
  --data-raw '{"from":{"blockchain":"BSC","symbol":"BNB","address":null},"to":{"blockchain":"TERRA","symbol":"Luna","address":null},"amount":"1","connectedWallets":[],"selectedWallets":{},"checkPrerequisites":false,"affiliateRef":null}' \
  --compressed

It is recommended to set checkPrerequisitesto false when you want to just give the user the best route preview and mark it as true when the user wants to do the actual swap.

There are extra parameters to limit blockchains of your interest, DEX/bridges list, types of transactions, complexitiy of implementation, etc.

Best Route Request

Param	Description
from *	The source asset
to *	The destination asset
amount *	The human-readable amount of asset X that is going to be swapped, e.g. 0.28
checkPrerequisites *	It should be false when a client just likes to preview the route to the user, and true when the user really accepted to swap. If true, the server will be much slower to respond but will check some pre-requisites including balance of X and required fees in user's wallets.
connectedWallets *	List of all user connected wallet addresses per each blockchain.
selectedWallets *	Map of blockchain to the selected address.
affiliateRef	The affiliate ref that client likes to send to Rango, so in cases of 1inch, Thorchain, etc. that support affiliation, the referrer will earn some money if the user accepts the route and signs the transactions. e.g. K3ldk3
maxLength	Maximum number of steps allowed in best route response
disableMultiStepTx	It should be true when the client doesn't want multi-step transactions.
blockchains	List of all accepted blockchains, an empty list means no filter is required.
swappers	List of all accepted swappers, an empty list means no filter is required.
transactionTypes	List of all accepted transaction types including EVM, TRANSFER and COSMOS

Best Route Response

Field	Description
requestId	The unique request Id which is generated for this request by the server. It should be passed down to all other endpoints if this swap continues on. e.g. d10657ce-b13a-405c-825b-b47f8a5016ad
requestAmount	The human readable input amount from the request
from	The source asset
to	The destination asset
result	The swap result route
validationStatus	Pre-requisites check result. It will be null if the request checkPrerequisites was false
diagnosisMessages	List of string messages that might be the cause of not finding the route. It's just for display purposes.
missingBlockchains	List of all blockchains which are necessary to be present for the best route and the user has not provided any connected wallets for it. A null or empty list indicates that there is no problem.
blockchains	List of all accepted blockchains, an empty list means no filter is required.
processingLimitReached	A warning indicates that it took too much time to find the best route and the server could not find any routes from X to Y.