Rango Docs
API SwaggerWidget PlaygroundAppWebsite
  • 👋Welcome to Rango
  • 🏠Introduction
  • 💁How It Works
  • ✅Integrations
  • ⚖️Rango vs. Competitors
  • 🔐Security
  • 🛣️Roadmap
  • 🦎Tokenomics
  • 💰Airdrop
  • ❓FAQ
  • 🐞Bug Bounty
  • API Integration
    • 🔡Terminology
    • 🚄API Key & Rate Limits
    • 🤝Choosing the Right API
    • 🦄Basic API - Single Step
      • 🛝API Flow
      • ⚙️API Reference
        • Get Blockchains & Tokens
        • Get Quote
        • Create Transaction (Swap)
        • Check Transaction Status
        • Check Approve Transaction Status
        • Get Address Assets & Balances
        • Get Token Balance
        • Report Transaction Failure
        • Get Direct Tokens
        • Get Custom Token
        • Message Passing
      • 🎓Tutorial
        • 🍰SDK Example
      • 💰Monetization
      • 🎹Sample Transactions
      • ✅Integration Checklist
    • 🦎Main API - Multi Step
      • 🛝API Flow
      • ⚙️API Reference
        • Get Blockchains & Tokens
        • Get Best Route
        • Get All Possible Routes
        • Confirm Route
        • Create Transaction
        • Check Transaction Status
        • Check Approve Transaction Status
        • Report Transaction Failure
        • Get Custom Token
        • Get Address Token Balance
      • 🎓Tutorial
        • 🍰SDK Example
      • 💰Monetization
      • 🎹Sample Transactions
  • ℹ️API Troubleshooting
  • Technical Docs
    • 🍔Swap Aggregation
    • 💰Monetization
    • ⛽Fee Structure
    • ⛽Network Fees and Gas Estimates
    • ⌛Stuck Transactions
  • Widget Integration
    • 🧩Overview
    • 🎇Quick Start
    • ⚙️Customization
    • 💰Monetization
    • 🛣️React Router
    • 🎵Events
    • 💳External Wallets
  • Smart Contracts
    • 👩‍💼Architecture
    • 🔎Audit Reports
    • 🏗️Deployment Addresses
    • 📩Message Passing
  • Ask for Integration
    • 🙋‍♂️DEXs & DEX Aggregators
    • 📱Rango Mobile SDK
  • Useful Links
    • Twitter
    • Discord Server
    • TG Announcements
    • TG Group
  • Terms of Use
  • Privacy policy
Powered by GitBook
On this page
  • Scenario
  • Flow Chart

Was this helpful?

  1. API Integration
  2. Basic API - Single Step

API Flow

Rango Exchange Basic API Flow

PreviousBasic API - Single StepNextAPI Reference

Last updated 7 months ago

Was this helpful?

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

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

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.

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)
  }
}
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
}

Flow Chart

5. dApp calls the 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.
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.

7. dApp periodically calls 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
  }
}
9. dApp optionally calls 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 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'
    }
  }
);

If tx field in 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.

🦄
🛝
Swap
Is Approved
Status
Report Failure
SDK Example tutorial
Meta
Quote
Read more about Assets Format.
swap response