🛝API Flow

Rango Exchange Basic API Flow

If you'd like to skip ahead to the code, please refer to the SDK Example tutorial.

Scenario

Here is a sample interaction scenario between a dApp and Rango Basic API/SDK. This flow is designed to be as straightforward as possible, but additional steps can be taken to enhance functionality.

1. The dApp calls Meta API to get list of all supported blockchains, swappers and tokens which are used to show a proper swap box for the user.

Sample Code:

const meta = await axios.get('https://api.rango.exchange/basic/meta', {
  params: {
    'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32'
  }
});

Use the fetched metadata to display available blockchains and their tokens to the user. Allow the user to select the source and destination tokens.

2. The user selects to swap 1 BSC.BNB to AVAX_CCHAIN.USDT--0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7.

Here is the sample code:

const tokens = meta.tokens;
const BNB_ADDRESS = null
const USDT_ADDRESS = '0xc7198437980c041c805a1edcba50c1ce5db95118'

// You can omit the following lines if you don't want to display token 
// details like the icon or price to the user before retrieving the quote.
const BSC_BNB = tokens.find(t => t.address === BNB_ADDRESS && t.blockchain === 'BSC')
const AVAX_USDT = tokens.find(t => t.address === USDT_ADDRESS && t.blockchain === 'AVAX_CCHAIN')

3. The dApp retrieves the best possible route between the tokens by calling the Quote API. If the user doesn't confirm the quote within the timeout period (e.g. after 15s), this step should be repeated to ensure the output amount and quote are up to date.

Read more about Assets Format. Here is the sample code:

const quote = await axios.get('https://api.rango.exchange/basic/quote', {
  params: {
    'from': 'BSC.BNB',
    'to': 'AVAX_CCHAIN--0xc7198437980c041c805a1edcba50c1ce5db95118',
    'amount': '100000000000000000',
    'slippage': '3',
    'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32'
  }
});

// check if the route was okay
if (!quote.result) {
  // there was no route
} else if (quote.resultType === 'HIGH_IMPACT') {
  // there was a quote but price impact was too high 
} else if (quote.resultType === 'INPUT_LIMIT_ISSUE') {
  // there was a quote but not suitable for this input amount.
  // user should increase or decrease the input amount
} else if (quote.resultType === 'OK') {
  // everything was okay
}

4. The user confirms the quote to start the swap.

5. dApp calls the Swap API to get transaction data required for the route. If output amount in swap response, is less than quote response, dApp could fail the swap or get double confirmation from the user.

If tx field in swap response is non-empty, it means that transaction is created successfully. If tx field is null or resultType is not OK, dApp shows an error to the user and flow breaks. Here is the sample code.

const swap = await axios.get('https://api.rango.exchange/basic/swap', {
  params: {
    'from': 'BSC.BNB',
    'to': 'AVAX_CCHAIN.USDT.E--0xc7198437980c041c805a1edcba50c1ce5db95118',
    'amount': '100000000000000000',
    'slippage': '3',
    'fromAddress': '0x6f33bb1763eebead07cf8815a62fcd7b30311fa3',
    'toAddress': '0x6f33bb1763eebead07cf8815a62fcd7b30311fa3',
    'disableEstimate': true,
    'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32'
  }
});

if (swap.tx && swap.resultType === 'OK') {
  // transaction is created susccessfully
  // you could compare confirmed quote with the swap output amount 
  // and warn the user if there is noticable difference
  // e.g. check if new quote output is 2% less than previous one
  const confirmedOutput = new BigNumber(quote.route?.outputAmount)
  const finalOutput = new BigNumber(swap.route?.outputAmount)
  if (finalOutput.lt(confirmedOutput.multipliedBy(new BigNumber(0.98))) {
    // get double confirmation from the user
  } else {
    // proceed to sign flow  
  }
} else if (!swap.tx && swap.resultType === 'OK') {
  // getting quote was successful but there was a problem
  // in creating the transaction
  console.log(swap.error)
} else {
  // there was a problem getting the quote
} 

How to set disableEstimate parameter in swap method?

If you are checking the balance and fee amount on your client side, it is recommended to set this parameter to true, as it will significantly reduce the response time.

6. If the transaction is related to a blockchain with approve requirement, i.e. all EVM based blockchains, Starknet and Tron, and user doesn't have enough approval dApp could generate approve transaction and ask user to sign it.

Is it possible to generate approve transaction on client side without using Rango API?

It is important to use approve transaction data generated by Rango API and not hard-coding something on your client side for creating approve transaction, because for some protocols (some bridges), the contract that should be approved is dynamically generated via their API based on the quote.

Sample Code for EVM transactions:

// sample type guard
export const isEvmTransaction = (tx: {
  type: TransactionType
}): transaction is EvmTransaction => tx.type === TransactionType.EVM

// how to build and sign EVM approve transaction
const tx = swap.tx
if (isEvmTransacation(tx)) {
  if (tx.approveData && tx.approveTo) {
    // user doesn't have enough approval and needs to sign approve tx
    const approveTx = {
      from: tx.from,
      to: tx.approveTo,
      data: tx.approveData,
      value: '0x',
    }
    const approveTxHash = (await signer.sendTransaction(approveTx)).hash
  } else {
    // user already has enough approve amoaunt
    // we could proceed to 8th step (main transaction)
  }
}

7. dApp periodically calls Is Approved API to make sure approve transaction is mined successfully and user has enough approval for the swap.

For checking approval transaction status, you could also check it directly from the RPC endpoint if you prefer and skip calling Rango API for this purpose.

Here is the sample code:

const response = await axios.get('https://api.rango.exchange/basic/is-approved', {
  params: {
    'requestId': 'e4b0d1e7-ae1f-4aed-ab91-f1ea3ba9383b',
    'txId': '0xd7a18c6e2f9afe5aefd1b5969f753513f01c6670a4fc57a2d1349ad539ae2f7f',
    'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32'
  }
});

if (response.isApproved) {
  // user has enough approve amount now
  // we could proceed to the next step
} else {
  if (response.txStatus === 'failed') {
    // approve transaction with given hash fails on blockchain
    // it could happen for different reasons, e.g. low gas price 
    // action => ask user to signs the approve transaction again.  
  } else { 
    // scenario: response.txStatus === 'success'
    // approve transaction succeeds but user doesn't have still enough approval
    // it could happen in rare cases for example when user changes dapp
    // suggested approve amount in Metamask and override it with a lower one
  }
}

8. dApp generates the main swap transaction and asks user to sign it.

Sample code for EVM transactions:

// sample type guard
export const isEvmTransaction = (tx: {
  type: TransactionType
}): transaction is EvmTransaction => tx.type === TransactionType.EVM

// how to build and sign EVM main transaction 
const tx = swap.tx
if (isEvmTransacation(tx)) {
  let swapTx = {
    from: tx.from,
    to: tx.to,
    data: tx.data,
    value: tx.value,
    gasLimit: tx.gasLimit
  }
  if (tx.gasPrice) {
    swapTx = { gasPrice: tx.gasPrice, ...swapTx }
  } else if (tx.maxPriorityFeePerGas && tx.maxFeePerGas) {
      swapTx = { 
        maxFeePerGas: tx.maxFeePerGas, 
        maxPriorityFeePerGas: tx.maxPriorityFeePerGas, 
        ...swapTx 
      }
  }
  const swpTxHash = (await signer.sendTransaction(swapTx)).hash
}

9. dApp optionally calls Status API periodically to see if it was successful or failed.

By calling this method, dApp could get the outbound transaction hash and make sure if the outbound transaction on the destination blockchain succeeds or transaction failed and user was refunded.

const response = await axios.get('https://api.rango.exchange/basic/status', {
  params: {
    'requestId': 'b3a12c6d-86b8-4c21-97e4-809151dd4036',
    'txId': '0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5',
    'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32'
  }
});


if (response.status) {
  // show latest status of the swap to the user
  if (response.status === TransactionStatus.SUCCESS) {
      // swap suceeded
  } else if (response.status === TransactionStatus.FAILED) {
      // swap failed
  } else {
      // swap is still running
      // we need to call status method again after a timeout (10s)
  }
}

10. If the swap fails because of a client side error like RPC errors in signing the transaction, dApp optionally calls Report Failure API to report the failure to Rango API.

Sample code:

const response = await axios.post(
  'https://api.rango.exchange/basic/report-tx',
  {
    'requestId': '2823418f-9e18-4110-8d36-b569b0af025e',
    'eventType': 'SEND_TX_FAILED',
    'reason': 'Transaction is underpriced.'
  }, 
  {
    params: {
      'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32'
    },
    headers: {
      'content-type': 'application/json'
    }
  }
);

Flow Chart