Get Best Route

Get the best route for swapping X to Y

Get Best Route API

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

const bestRoute = await rango.getBestRoute({
    from: {"blockchain": "BSC", "symbol": "BNB", "address": null},
    to: {"blockchain": "AVAX_CCHAIN", "symbol": "USDT.E", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118"},    
    amount: "1",
    checkPrerequisites: false,
    slippage: "1.0",
    selectedWallets: {
        "AVAX_CCHAIN": "0xeae6d42093eae057e770010ffd6f4445f7956613",
        "BSC": "0xeae6d42093eae057e770010ffd6f4445f7956613",
    },
})

const response = await axios.post(
  'https://api.rango.exchange/routing/best',
  {
    'from': {
      'blockchain': 'BSC',
      'symbol': 'BNB'
    },
    'to': {
      'blockchain': 'AVAX_CCHAIN',
      'symbol': 'USDT.E',
      'address': '0xc7198437980c041c805a1edcba50c1ce5db95118'
    },
    'slippage': '1.0',
    'selectedWallets': {
      'BSC': '0xeae6d42093eae057e770010ffd6f4445f7956613',
      'AVAX_CCHAIN': '0xeae6d42093eae057e770010ffd6f4445f7956613'
    },
    'checkPrerequisites': false,
    'amount': '1'
  },
  {
    params: {
      'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32'
    },
    headers: {
      'content-type': 'application/json'
    }
  }
);

curl --request POST \
     --url 'https://api.rango.exchange/routing/best?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' \
     --header 'content-type: application/json' \
     --data '
{
  "from": {
    "blockchain": "BSC",
    "symbol": "BNB"
  },
  "to": {
    "blockchain": "AVAX_CCHAIN",
    "symbol": "USDT.E",
    "address": "0xc7198437980c041c805a1edcba50c1ce5db95118"
  },
  "slippage": "1.0",
  "selectedWallets": {
    "BSC": "0xeae6d42093eae057e770010ffd6f4445f7956613",
    "AVAX_CCHAIN": "0xeae6d42093eae057e770010ffd6f4445f7956613"
  },
  "checkPrerequisites": false,
  "amount": "1"
}
'

You need to pass checkPrerequisites value equals to true when user confirms the route.

When user confirms the route and you want to go to the next step (creating transaction), it's required to pass checkPrerequisites value equals to true. Otherwise, Rango won't create the transaction for you.

But it is recommended to set checkPrerequisites to false when you want to just give the user the best route preview.

How to filter blockchains and swappers of the route?

These parameters are used to limit blockchains of your interest, swappers, types of transactions, complexity of implementation, etc:

swappers, swappersExclude
swapperGroups, swapperGroupsExclude
blockchains, blockchainsExclude
transactionTypes

Example 1. Imagine that you are developing a dApp which only supports EVM and Solana. You could pass the transactionTypes equals to ['EVM', 'SOLANA'].

Example 2. Imagine that you want to only support some specific bridges and dexes in your dApp. you could simply pass the swapperGroups equals to list of those swappers. e.g. you could pass ['Hyphen', 'Synapse Swapper', '1Inch', 'UniSwap'].

Example 3. In multi-step routing, the optimal route may not always be a single step, and intermediary blockchains are chosen based on the best price for the route. By using blockchain parameters, you can control which blockchains are involved in the route. e.g. you could pass blockchains equals to ['ETH', 'BSC', 'ARBITRUM', 'POLYGON'].

Best Route Request

from * Asset
- Description: The source asset
- Example: {"blockchain": "BSC", "symbol": "BNB", "address": null}
to * Asset
- Description: The destination asset
- Example: {"blockchain": "AVAX_CCHAIN", "symbol": "USDT.E", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118"}
amount * String
- Description: The human-readable amount of asset from that is going to be swapped.
- Example: 0.28
selectedWallets *
- Description: The list of wallets chosen by the user for this swap. For a multi-step swap, we need the wallet address for each blockchain involved in the route. (Mapping of blockchain to wallet address)
- Example: { "AVAX_CCHAIN": "0xeae6d42093eae057e770010ffd6f4445f7956613", "BSC": "0xeae6d42093eae057e770010ffd6f4445f7956613" }
checkPrerequisites Boolean
- Description: It should be set to false when the client only wants to show a route preview to the user, and true when the user has confirmed the swap. If set to true, the server response time will be slower as it will verify certain prerequisites, such as the balance of source token and the necessary fees in the user's wallet.
- Default: false
destination String
- Description: Custom destination wallet address for the route.
connectedWallets
- Description: Optional list of all connected wallets of user in all blockchains.
slippage number
- Description: Amount of user's preferred slippage in percent. if you don't send it, it will assume 0.5% slippage. (It's used to filter the swappers or routes that are not suitable for the given slippage)
contractCall Boolean
- Description: set this parameter to true if you want to send transactions through a contract. It will filter swappers that are not possible to be called by another contract.
- Caution: if you call Rango contracts using your contract and your contract is not white listed in some underlying protocols like Thorchain, user fund may stuck forever in Thorchain contracts. In this case, you need to exclude these swappers using this flag or ask related protocols to white list your contract.
- Example: true
affiliateRef String
- Description: The affiliate unique key. In the Rango Exchange App, an affiliate key is generated using a wallet address, and this same wallet address is used to receive the fee charged by the dApp for the request.
- Example: K3ldk3
affiliatePercent String
- Description: The dApp transaction fee in percent. Rango allows affiliate percent up to maximum of 3.0 percent.
- Example: 1.5 which means 1.5 percent of the input amount
affiliateWallets
- Description: List of affiliate wallets per blockchain for referral rewards. If this parameter is not provided, the wallet used for generating the affiliateRef will be used. By passing this parameter, you can override the wallet address used for the dApp transaction fee for each blockchain.
maxLength Number
- Description: Maximum number of steps allowed in best route response. You could pass this parameter equals to 1 if you are interested in single step routes which is similar to the Basic API.
- Example: 2
disableMultiStepTx Boolean
- Description: Some bridges requires more than one transaction for each swap. For example, some bridges require transaction on both source and destination blockchains by the users. Using this flag, you could enable routing via these protocols. Default is true.
- Note: At the moment, only Voyager bridge subjects to this condition.
- Default: true
blockchains String
- Description: Pass comma separated list of blockchains if you want to filter meta blockchains to some specific ones.
- Example: POLYGON,ETH
blockchainsExclude Boolean
- Description: A boolean value indicating whether the specified blockchains should be excluded or included in the response.
- Example: true
swappers String
- Description: Pass comma separated list of swappers if you want to filter meta swappers to some specific ones.
- Example: Across,OneInchEth
swappersExclude Boolean
- Description: A boolean value indicating whether the specified swappers should be excluded or included in the response.
- Example: false
swappersGroups String
- Description: Pass comma separated list of swapper groups if you want to filter meta swapper groups to some specific ones.
- Example: Across,1Inch
swappersGroupsExclude Boolean
- Description: A boolean value indicating whether the specified swapper groups should be excluded or included in the response.
- Example: false
transactionTypes String
- Description: Pass comma separated list of transaction types if you want to filter blockchains types to some specific ones.
- Example: EVM,COSMOS
transactionTypesExclude Boolean
- Description: A boolean value indicating whether the specified transaction types should be excluded or included in the response.
- Example: false
enableCentralizedSwappers Boolean
- Description: Set this flag to true if you want to enable routing through the centralized solutions and obtain the associated metadata, including related swappers and tokens. The default value for this argument is false.
- Caution: To enable these swappers, you must pass the user's IP to the Rango API for compliance checks. Additionally, user funds may be held for KYC if their wallet is flagged as risky by the screening solutions implemented by these protocols.
- Default: false
avoidNativeFeeBoolean
- Description: When this condition is true, swappers that charge fees in native tokens will be excluded. For instance, when called from an AA account. Swappers like Stargate charge user fees in native tokens instead of the input amount, causing the transaction value to differ from the user's input amount. Alternatively, the user may need to transfer native tokens in a contract call to cover these protocol fees. Although you can disable these protocols using this flag, we do not recommend it as it reduces the coverage of routes.
- Default: false
interChainMessage
- Description: Info about inter-chain message (Source & Destination contracts and IM Message) for cross-chain messaging.
messagingProtocols
- Description: List of messaging protocols to be used for passing interchain messages.

export type BestRouteRequest = {
  from: Asset
  to: Asset
  amount: string
  selectedWallets: { [key: string]: string }
  connectedWallets?: UserWalletBlockchain[] | null
  checkPrerequisites?: boolean
  slippage?: string
  destination?: string
  forceExecution?: boolean
  affiliateRef?: string | null
  affiliatePercent?: number | null
  affiliateWallets?: { [key: string]: string }
  disableMultiStepTx?: boolean
  blockchains?: string[]
  swappers?: string[]
  swappersExclude?: boolean
  swapperGroups?: string[]
  swappersGroupsExclude?: boolean
  transactionTypes?: TransactionType[]
  messagingProtocols?: string[]
  maxLength?: number
  experimental?: boolean
  contractCall?: boolean
  interChainMessage?: InterChainMessage | null
  enableCentralizedSwappers?: boolean
  avoidNativeFee?: boolean
}

export type UserWalletBlockchain = {
  blockchain: string
  addresses: string[]
}

export enum TransactionType {
  EVM = 'EVM',
  TRANSFER = 'TRANSFER',
  COSMOS = 'COSMOS',
  SOLANA = 'SOLANA',
  TRON = 'TRON',
  STARKNET = 'STARKNET',
  TON = 'TON',
}

export type InterChainMessage = {
  sourceContract: string
  destinationContract: string
  imMessage: string
}

Best Route Response

requestId
- Description: 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
- Description: The human readable input amount from the request.
from
- Description: The source asset.
to
- Description: The destination asset.
result
- Description: The best route data.
validationStatus
- Description: Prerequisites (validation) check result. It will be null if the checkPrerequisites field was false (or not given) in the request.
diagnosisMessages
- Description: A list of string messages that might be the cause of not finding the route. It's just for display purposes.
missingBlockchains
- Description: 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
- Description: List of all accepted blockchains, an empty list means no filter is required.
processingLimitReached
- Description: 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.
walletNotSupportingFromBlockchain
- Description: A warning indicating that none of your wallets have the same blockchain as X asset.
error
- Description: Error occurred during the operation.
errorCode
- Description: Error code shows the type of error.
traceId
- Description: Trace Id helps Rango support team to trace an issue.

export type BestRouteResponse = {
  requestId: string
  requestAmount: string
  from: Asset
  to: Asset
  result: SimulationResult | null
  validationStatus: BlockchainValidationStatus[]
  diagnosisMessages: string[]
  missingBlockchains: string[]
  walletNotSupportingFromBlockchain: boolean
  error: string | null
  errorCode: number | null
  traceId: number | null
}

export type Asset = {
  blockchain: string
  address: string | null
  symbol: string
}

export type BlockchainValidationStatus = {
  blockchain: string
  wallets: WalletValidationStatus[]
}

export type WalletValidationStatus = {
  address: string
  addressIsValid: boolean
  requiredAssets: WalletRequiredAssets[]
  validResult: boolean
}

export type WalletRequiredAssets = {
  asset: Asset
  requiredAmount: Amount
  currentAmount: Amount
  ok: boolean
  reason: 'FEE' | 'FEE_AND_INPUT_ASSET' | 'INPUT_ASSET'
}

export type Amount = {
  amount: string
  decimals: number
}

export type SimulationResult = {
  outputAmount: string
  resultType: RoutingResultType
  swaps: SwapResult[]
}

export enum RoutingResultType {
  OK = 'OK',
  HIGH_IMPACT = 'HIGH_IMPACT',
  NO_ROUTE = 'NO_ROUTE',
  INPUT_LIMIT_ISSUE = 'INPUT_LIMIT_ISSUE',
  HIGH_IMPACT_FOR_CREATE_TX = 'HIGH_IMPACT_FOR_CREATE_TX',
}

export type SwapResult = {
  swapperId: string
  swapperLogo: string
  swapperType: SwapperType
  swapChainType: 'INTER_CHAIN' | 'INTRA_CHAIN'
  from: SwapResultAsset
  to: SwapResultAsset
  toAmount: string
  fromAmount: string
  fromAmountMaxValue: string | null
  fromAmountMinValue: string | null
  fromAmountPrecision: string | null
  fromAmountRestrictionType: AmountRestrictionType
  routes: SwapRoute[] | null
  internalSwaps: SwapResult[] | null
  fee: SwapFee[]
  estimatedTimeInSeconds: number
  timeStat: TimeStat | null
  includesDestinationTx: boolean
  maxRequiredSign: number
  recommendedSlippage: RecommendedSlippage | null
  warnings: string[]
}

export type SwapperType = 'BRIDGE' | 'DEX' | 'AGGREGATOR' | 'OFF_CHAIN'

export type SwapResultAsset = {
  blockchain: string
  address: string | null
  symbol: string
  logo: string
  blockchainLogo: string
  decimals: number
  usdPrice: number | null
}

export type AmountRestrictionType = 'INCLUSIVE' | 'EXCLUSIVE'

export type SwapRoute = {
  nodes: SwapSuperNode[] | null
}

export type SwapSuperNode = {
  from: string
  fromAddress: string | null
  fromBlockchain: string
  fromLogo: string
  to: string
  toAddress: string | null
  toBlockchain: string
  toLogo: string
  nodes: SwapNode[]
}

export type SwapFee = {
  name: string
  expenseType: ExpenseType
  asset: Asset
  amount: string
  price: number | null
  meta: EVMFeeMeta | null
}

export type EVMFeeMeta = {
  type: "EvmNetworkFeeMeta",
  gasLimit: string,
  gasPrice: string
}

export type ExpenseType =
  | 'FROM_SOURCE_WALLET'
  | 'DECREASE_FROM_OUTPUT'
  | 'FROM_DESTINATION_WALLET'

export type TimeStat = {
  min: number
  avg: number
  max: number
}

export type RecommendedSlippage = {
  error: boolean
  slippage: string
}

{
  "from": {
    "blockchain": "ETH",
    "symbol": "ETH",
    "address": null
  },
  "to": {
    "blockchain": "BSC",
    "symbol": "BNB",
    "address": null
  },
  "requestAmount": "1",
  "requestId": "5eeff23c-7f9b-449d-89fc-0a2f2d7c6f45",
  "result": {
    "outputAmount": "4.616725351373488449",
    "swaps": [
      {
        "swapperId": "EthereumUniswapV3",
        "swapperLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/UniSwapV2/icon.svg",
        "swapperType": "DEX",
        "from": {
          "symbol": "ETH",
          "logo": "https://rango.vip/tokens/ALL/ETH.png",
          "blockchainLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/ETH/icon.svg",
          "address": null,
          "blockchain": "ETH",
          "decimals": 18,
          "usdPrice": 2283.65
        },
        "to": {
          "symbol": "WBTC",
          "logo": "https://rango.vip/i/RTzCUB",
          "blockchainLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/ETH/icon.svg",
          "address": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
          "blockchain": "ETH",
          "decimals": 8,
          "usdPrice": 54220
        },
        "fromAmount": "1.000000000000000000",
        "fromAmountPrecision": null,
        "fromAmountMinValue": null,
        "fromAmountMaxValue": null,
        "fromAmountRestrictionType": null,
        "toAmount": "0.04206151",
        "fee": [
          {
            "asset": {
              "blockchain": "ETH",
              "symbol": "ETH",
              "address": null
            },
            "expenseType": "DECREASE_FROM_OUTPUT",
            "amount": "0.0015000000000000000000",
            "name": "Rango Fee",
            "price": 2283.65
          },
          {
            "asset": {
              "blockchain": "ETH",
              "symbol": "ETH",
              "address": null
            },
            "expenseType": "FROM_SOURCE_WALLET",
            "amount": "0.000537230097667200",
            "name": "Network Fee",
            "meta": {
              "type": "EvmNetworkFeeMeta",
              "gasLimit": "367072",
              "gasPrice": "1463555100"
            },
            "price": 2283.65
          }
        ],
        "estimatedTimeInSeconds": 120,
        "swapChainType": "INTER_CHAIN",
        "routes": [
          {
            "nodes": [
              {
                "nodes": [
                  {
                    "marketName": "EthereumUniswapV3",
                    "marketId": "EthereumUniswapV3",
                    "percent": 1,
                    "pools": [
                      "0x4585fe77225b41b697c938b018e2ac67ac5a20c0"
                    ],
                    "inputAmount": "998500000000000000",
                    "outputAmount": "4206151"
                  }
                ],
                "from": "ETH",
                "fromLogo": "",
                "fromAddress": null,
                "fromBlockchain": "ETH",
                "to": "WBTC",
                "toLogo": "",
                "toAddress": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
                "toBlockchain": "ETH"
              }
            ]
          }
        ],
        "recommendedSlippage": null,
        "warnings": [],
        "timeStat": {
          "min": 8,
          "avg": 112,
          "max": 382
        },
        "includesDestinationTx": false,
        "internalSwaps": null,
        "maxRequiredSign": 1
      },
      {
        "swapperId": "OrbiterV2",
        "swapperLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/Orbiter/icon.svg",
        "swapperType": "BRIDGE",
        "from": {
          "symbol": "WBTC",
          "logo": "https://rango.vip/i/RTzCUB",
          "blockchainLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/ETH/icon.svg",
          "address": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
          "blockchain": "ETH",
          "decimals": 8,
          "usdPrice": 54220
        },
        "to": {
          "symbol": "BTCB",
          "logo": "https://rango.vip/i/N9IbGq",
          "blockchainLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg",
          "address": "0x7130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c",
          "blockchain": "BSC",
          "decimals": 18,
          "usdPrice": 54288
        },
        "fromAmount": "0.04206151",
        "fromAmountPrecision": null,
        "fromAmountMinValue": "0.0000495",
        "fromAmountMaxValue": "0.09499999999999999555910790149937383830547332763671875",
        "fromAmountRestrictionType": "INCLUSIVE",
        "toAmount": "0.042033510000000000",
        "fee": [
          {
            "asset": {
              "blockchain": "ETH",
              "symbol": "WBTC",
              "address": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599"
            },
            "expenseType": "DECREASE_FROM_OUTPUT",
            "amount": "0.00002800000000",
            "name": "Swapper Fee",
            "price": 54220
          },
          {
            "asset": {
              "blockchain": "ETH",
              "symbol": "ETH",
              "address": null
            },
            "expenseType": "FROM_SOURCE_WALLET",
            "amount": "0.000200354838969600",
            "name": "Network Fee",
            "meta": {
              "type": "EvmNetworkFeeMeta",
              "gasLimit": "136896",
              "gasPrice": "1463555100"
            },
            "price": 2283.65
          }
        ],
        "estimatedTimeInSeconds": 120,
        "swapChainType": "INTRA_CHAIN",
        "routes": null,
        "recommendedSlippage": null,
        "warnings": [],
        "timeStat": {
          "min": 11,
          "avg": 119,
          "max": 308
        },
        "includesDestinationTx": false,
        "internalSwaps": null,
        "maxRequiredSign": 1
      },
      {
        "swapperId": "BSCPancakeV3",
        "swapperLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/Pancake/icon.svg",
        "swapperType": "DEX",
        "from": {
          "symbol": "BTCB",
          "logo": "https://rango.vip/i/N9IbGq",
          "blockchainLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg",
          "address": "0x7130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c",
          "blockchain": "BSC",
          "decimals": 18,
          "usdPrice": 54288
        },
        "to": {
          "symbol": "BNB",
          "logo": "https://rango.vip/tokens/ALL/BNB.png",
          "blockchainLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg",
          "address": null,
          "blockchain": "BSC",
          "decimals": 18,
          "usdPrice": 493.64
        },
        "fromAmount": "0.042033510000000000",
        "fromAmountPrecision": null,
        "fromAmountMinValue": null,
        "fromAmountMaxValue": null,
        "fromAmountRestrictionType": null,
        "toAmount": "4.616725351373488449",
        "fee": [
          {
            "asset": {
              "blockchain": "BSC",
              "symbol": "BNB",
              "address": null
            },
            "expenseType": "FROM_SOURCE_WALLET",
            "amount": "0.000406595200000000",
            "name": "Network Fee",
            "meta": {
              "type": "EvmNetworkFeeMeta",
              "gasLimit": "369632",
              "gasPrice": "1100000000"
            },
            "price": 493.64
          }
        ],
        "estimatedTimeInSeconds": 45,
        "swapChainType": "INTER_CHAIN",
        "routes": [
          {
            "nodes": [
              {
                "nodes": [
                  {
                    "marketName": "BSCPancakeV3",
                    "marketId": "BSCPancakeV3",
                    "percent": 1,
                    "pools": [
                      "0x6bbc40579ad1bbd243895ca0acb086bb6300d636"
                    ],
                    "inputAmount": "42033510000000000",
                    "outputAmount": "4616725351373488449"
                  }
                ],
                "from": "BTCB",
                "fromLogo": "",
                "fromAddress": "0x7130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c",
                "fromBlockchain": "BSC",
                "to": "BNB",
                "toLogo": "",
                "toAddress": null,
                "toBlockchain": "BSC"
              }
            ]
          }
        ],
        "recommendedSlippage": null,
        "warnings": [],
        "timeStat": {
          "min": 1,
          "avg": 45,
          "max": 203
        },
        "includesDestinationTx": false,
        "internalSwaps": null,
        "maxRequiredSign": 1
      }
    ],
    "resultType": "OK"
  },
  "validationStatus": null,
  "walletNotSupportingFromBlockchain": false,
  "missingBlockchains": [],
  "diagnosisMessages": [],
  "error": null,
  "errorCode": null,
  "traceId": null
}

PreviousGet Blockchains & Tokens NextGet All Possible Routes

Last updated 2 months ago