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
  • Swap API
  • Swap Request
  • Swap Response

Was this helpful?

  1. API Integration
  2. Basic API - Single Step
  3. API Reference

Create Transaction (Swap)

Get final quote and create the transaction

PreviousGet QuoteNextCheck Transaction Status

Last updated 7 months ago

Was this helpful?

Swap API

It's similar to the quote method but gives the actual transaction data in response besides the route.

const swapResponse = await rango.swap({
    from: {"blockchain": "BSC", "address": null},
    to: {"blockchain": "AVAX_CCHAIN", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118"},
    amount: "100000000000000000",
    fromAddress: "0xeb2629a2734e272bcc07bda959863f316f4bd4cf",
    toAddress: "0xeb2629a2734e272bcc07bda959863f316f4bd4cf",
    disableEstimate: true,
    slippage: 1.0,
})
const response = await axios.get('https://api.rango.exchange/basic/swap', {
  params: {
    'from': 'BSC.BNB',
    'to': 'AVAX_CCHAIN--0xc7198437980c041c805a1edcba50c1ce5db95118',
    'amount': '100000000000000000',
    'slippage': 3,
    'fromAddress': '0x6f33bb1763eebead07cf8815a62fcd7b30311fa3',
    'toAddress': '0x6f33bb1763eebead07cf8815a62fcd7b30311fa3',
    'disableEstimate': true,
    'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32'
  }
});
curl --request GET \
     --url 'https://api.rango.exchange/basic/swap?from=BSC.BNB&to=AVAX_CCHAIN--0xc7198437980c041c805a1edcba50c1ce5db95118&amount=100000000000000000&slippage=3&fromAddress=0x6f33bb1763eebead07cf8815a62fcd7b30311fa3&toAddress=0x6f33bb1763eebead07cf8815a62fcd7b30311fa3&disableEstimate=true&apiKey=c6381a79-2817-4602-83bf-6a641a409e32'

Swap Request

  • from * String

    • Example: BSC.BNB

  • to * String

    • Example: AVAX_CCHAIN--0xc7198437980c041c805a1edcba50c1ce5db95118

  • amount * String

    • Example: 100000000000000000

  • slippage * Number

    • Description: User slippage for this swap

    • Example: 1.5 which means 1.5% slippage.

  • fromAddress * String

    • Description: User source wallet address

  • toAddress * String

    • Description: User destination wallet address

  • disableEstimate Boolean

    • Description: This field should be false when the client wants to preview the route to the user and true when the user accepts the swap. If it's true, the server will be much slower to respond but will check some prerequisites, including the balance of X and any required fees in the user's wallets. By default, when you call the swap method, Rango API performs some validations e.g. having enough balance for the input amount and the swap fee, and gives an error if doesn't meet the criteria. If you want to disable it and do it on your own side, you could pass true value for the disableEstimate argument.

    • Caution: 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.

  • referrerAddress String

    • Description: Referrer wallet address

  • referrerFee String

    • Description: Referrer fee in percent, (e.g. 0.3 means: 0.3% fee based on input amount)

  • referrerCode String

  • swappers String

    • Description: List of all accepted swappers, an empty list means no filter is required.

  • swappersExclude Boolean

    • Description: Defines the provided swappers as the include/exclude list. Default is false (include)

  • swapperGroups String

    • Description: The list of all included/excluded swappers based on tag, empty list means no filter is required.

  • swappersGroupsExclude Boolean

    • Description: Defines the provided swappers' tags as the include/exclude list. Default is false (include)

  • infiniteApprove Boolean

    • Description: Use this parameter if you want infinite approve from user

  • contractCall Boolean

    • Caution: 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.

  • messagingProtocols String

    • Description: List of all messaging protocols, an empty list means no filter is required.

  • sourceContract String

    • Description: Address of your contract on source chain (will be called in case of refund in the source chain)

  • destinationContract String

    • Description: Address of your contract on destination chain (will be called in case of success/refund in the destination chain)

  • imMessage String

  • avoidNativeFee Boolean

    • Description: When this condition is true, swappers that charge fees in native tokens will be excluded. For instance, when called from an AA account.

    • Caution: 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 single-step routes.

  • enableCentralizedSwappers Boolean

    • Description: Pass this flag true if you want to enable routing through the centralized solutions. Default 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.

export type SwapRequest = {
  from: RequestedAsset
  to: RequestedAsset
  amount: string
  fromAddress: string
  toAddress: string
  slippage: number
  disableEstimate?: boolean
  referrerCode?: string
  referrerAddress?: string | null
  referrerFee?: string | null
  swappers?: string[]
  swappersExclude?: boolean
  swapperGroups?: string[]
  swappersGroupsExclude?: boolean
  messagingProtocols?: string[]
  sourceContract?: string
  destinationContract?: string
  imMessage?: string
  contractCall?: boolean
  infiniteApprove?: boolean
  avoidNativeFee?: boolean
  enableCentralizedSwappers?: boolean
}

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

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

    • Example: d10657ce-b13a-405c-825b-b47f8a5016ad

  • resultType

    • Description: Status of the route.

    • Possible Values:

      • OK => Best route found. Everything is OK.

      • HIGH_IMPACT => The route has high price impact, we recommend not proceeding with the next step. The Rango API may give you an error in the next step to prevent potential losses.

      • INPUT_LIMIT_ISSUE => There is a limit issue for the input amount. You could suggest user to increase or decrease the input amount based on amountRestrictions field in response.

      • NO_ROUTE => No routes found.

    • Caution: This is the status of route (similar to this field in quote response). If there was any error in creating tx, it will be appear in error field. So you could check (error !== null) && (status === 'OK') to make sure everything is ok before proceeding with the next step.

  • route

    • Description: The quote route object. Similar to the quote response.

  • error

    • Description: Error message (raw string) if there is any problem in creating transaction. error == null <=> tx != null

  • tx

    • Description: Transaction data for this route.

export type SwapResponse = {
  requestId: string
  resultType: RoutingResultType
  route: QuoteSimulationResult | null
  error: string | null
  tx: EvmTransaction | CosmosTransaction | SolanaTransaction | Transfer | StarknetTransaction | TronTransaction | null
}

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 QuoteSimulationResult = {
  from: Token
  to: Token
  outputAmount: string
  outputAmountMin: string
  outputAmountUsd: number | null
  swapper: SwapperMeta
  path: QuotePath[] | null
  fee: SwapFee[]
  feeUsd: number | null
  amountRestriction: AmountRestriction | null
  estimatedTimeInSeconds: number
}

export type SwapperMeta = {
  id: string
  title: string
  logo: string
  swapperGroup: string
  types: SwapperType[]
  enabled: boolean
}

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

export type SwapFee = {
  name: string
  token: Token
  expenseType: ExpenseType
  amount: string
  meta: EVMFeeMeta | null
}

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

export type AmountRestriction = {
  min: string | null
  max: string | null
  type: AmountRestrictionType
}

export type QuotePath = {
  from: Token
  to: Token
  swapper: SwapperMeta
  swapperType: SwapperType
  inputAmount: string
  expectedOutput: string
  estimatedTimeInSeconds: number
}

export type Token = {
  blockchain: string
  chainId: string | null
  address: string | null
  symbol: string
  name: string | null
  decimals: number
  image: string
  blockchainImage: string
  usdPrice: number | null
  isPopular: boolean
  supportedSwappers: string[]
}
{
  "requestId": "a114c5f2-3f95-4c1f-ad57-7049522634b9",
  "resultType": "OK",
  "route": {
    "outputAmount": "50533592",
    "outputAmountMin": "49017584",
    "outputAmountUsd": 50.533592,
    "swapper": {
      "id": "Bridgers",
      "title": "Bridgers",
      "logo": "https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/Bridgers/icon.svg",
      "swapperGroup": "Bridgers",
      "types": [
        "DEX",
        "BRIDGE"
      ],
      "enabled": true
    },
    "from": {
      "blockchain": "BSC",
      "symbol": "BNB",
      "name": null,
      "isPopular": false,
      "chainId": "56",
      "address": null,
      "decimals": 18,
      "image": "https://rango.vip/tokens/ALL/BNB.png",
      "blockchainImage": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg",
      "usdPrice": 514.9,
      "supportedSwappers": []
    },
    "to": {
      "blockchain": "AVAX_CCHAIN",
      "symbol": "USDT.E",
      "name": null,
      "isPopular": false,
      "chainId": "43114",
      "address": "0xc7198437980c041c805a1edcba50c1ce5db95118",
      "decimals": 6,
      "image": "https://rango.vip/i/GJxbOP",
      "blockchainImage": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/AVAX_CCHAIN/icon.svg",
      "usdPrice": 1,
      "supportedSwappers": []
    },
    "fee": [
      {
        "token": {
          "blockchain": "BSC",
          "symbol": "BNB",
          "name": null,
          "isPopular": true,
          "chainId": "56",
          "address": null,
          "decimals": 18,
          "image": "https://rango.vip/tokens/ALL/BNB.png",
          "blockchainImage": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg",
          "usdPrice": 514.9,
          "supportedSwappers": [
            "ThorChain"
          ]
        },
        "expenseType": "DECREASE_FROM_OUTPUT",
        "amount": "299550000000000",
        "name": "Swapper Fee"
      },
      {
        "token": {
          "blockchain": "BSC",
          "symbol": "BNB",
          "name": null,
          "isPopular": true,
          "chainId": "56",
          "address": null,
          "decimals": 18,
          "image": "https://rango.vip/tokens/ALL/BNB.png",
          "blockchainImage": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg",
          "usdPrice": 514.9,
          "supportedSwappers": [
            "ThorChain"
          ]
        },
        "expenseType": "DECREASE_FROM_OUTPUT",
        "amount": "150000000000000",
        "name": "Rango Fee"
      },
      {
        "token": {
          "blockchain": "BSC",
          "symbol": "BNB",
          "name": null,
          "isPopular": true,
          "chainId": "56",
          "address": null,
          "decimals": 18,
          "image": "https://rango.vip/tokens/ALL/BNB.png",
          "blockchainImage": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg",
          "usdPrice": 514.9,
          "supportedSwappers": [
            "ThorChain"
          ]
        },
        "expenseType": "FROM_SOURCE_WALLET",
        "amount": "168748800000000",
        "name": "Network Fee",
        "meta": {
          "type": "EvmNetworkFeeMeta",
          "gasLimit": "153408",
          "gasPrice": "1100000000"
        }
      }
    ],
    "feeUsd": 0.08688875712,
    "amountRestriction": {
      "min": "38697000000000000",
      "max": "3888483000000000000",
      "type": "EXCLUSIVE"
    },
    "estimatedTimeInSeconds": 360,
    "path": [
      {
        "swapper": {
          "id": "Bridgers",
          "title": "Bridgers",
          "logo": "https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/Bridgers/icon.svg",
          "swapperGroup": "Bridgers",
          "types": [
            "DEX",
            "BRIDGE"
          ],
          "enabled": true
        },
        "swapperType": "BRIDGE",
        "from": {
          "blockchain": "BSC",
          "symbol": "BNB",
          "name": null,
          "isPopular": false,
          "chainId": "56",
          "address": null,
          "decimals": 18,
          "image": "https://rango.vip/tokens/ALL/BNB.png",
          "blockchainImage": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg",
          "usdPrice": 514.9,
          "supportedSwappers": []
        },
        "to": {
          "blockchain": "AVAX_CCHAIN",
          "symbol": "USDT.E",
          "name": null,
          "isPopular": false,
          "chainId": "43114",
          "address": "0xc7198437980c041c805a1edcba50c1ce5db95118",
          "decimals": 6,
          "image": "https://rango.vip/i/GJxbOP",
          "blockchainImage": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/AVAX_CCHAIN/icon.svg",
          "usdPrice": 1,
          "supportedSwappers": []
        },
        "inputAmount": "100000000000000000",
        "expectedOutput": "50533592",
        "estimatedTimeInSeconds": 360
      }
    ]
  },
  "error": null,
  "errorCode": null,
  "traceId": null,
  "tx": {
    "type": "EVM",
    "blockChain": {
      "name": "BSC",
      "defaultDecimals": 18,
      "addressPatterns": [
        "^(0x)[0-9A-Fa-f]{40}$"
      ],
      "feeAssets": [
        {
          "blockchain": "BSC",
          "symbol": "BNB",
          "address": null
        }
      ],
      "type": "EVM",
      "chainId": "56"
    },
    "from": "0x6f33bb1763eebead07cf8815a62fcd7b30311fa3",
    "txTo": "0x69460570c93f9DE5E2edbC3052bf10125f0Ca22d",
    "approveTo": null,
    "approveData": null,
    "txData": "0xb17d0e6e00000000000000000000000000000000a114c5f23f954c1fad577049522634b900000000000000000000000000000000000000000000000000000000000000000000000000000000000000000eb3a705fc54725037cc9e008bdede697f62f3350000000000000000000000000000000000000000000000000162bd0bc4d2a0000000000000000000000000000000000000000000000000000000886c98b760000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006a00000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006f33bb1763eebead07cf8815a62fcd7b30311fa300000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000b685760ebd368a891f27ae547391f4e2a289895b000000000000000000000000b685760ebd368a891f27ae547391f4e2a289895b0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000162bd0bc4d2a00000000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000010416b3b4c2000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000030314d8000000000000000000000000000000000000000000000000000000000000000f555344542e4528432d436861696e290000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002a3078366633336262313736336565626561643037636638383135613632666364376233303331316661330000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "value": "0x16345785d8a0000",
    "gasLimit": "0x442a2",
    "gasPrice": "1100000000",
    "priorityGasPrice": null,
    "maxPriorityFeePerGas": null,
    "maxGasPrice": null,
    "maxFeePerGas": null
  }
}

Description: The X that user likes to swap

Description: The Y that user wants to swap X into that

Description: The machine-readable amount of X that is going to be swapped

Caution: By default, Rango does not charge a fee on your behalf unless you setreferrerAddress and referrerFee parameters when your dApp sends a request to the swap method. In this case, Rango charges an additional fee equal to (referrerFee / 100) x inputAmount and transfer it to your referrerAddress wallet as the referral reward. Please check our document on for more details on this.

Description:

Description: The message that you want to pass to your contract on the destination chain. When transferring tokens using Rango cross-chain API, you could pass a random message from the source chain to the destination and call your contract on the destination. In order to do so, you need to pass your contracts on source & destination chains plus an arbitrary hex message. In order to do that, you should specify sourceContract, destinationContract and imMessage arguments in both quote and swap calls. You could also use messagingProtocols field to filter protocols used for message passing. You could read our document for more details.

Example:

🦄
⚙️
Basic API Monetization
message passing
Sample Basic Transactions
Swap Swagger Link
Swap (Create Transaction)rango-exchange
Logo
asset
asset
asset
Referrer code