# Welcome to Rango Rango is a cutting-edge routing and aggregation protocol for all cross-chain and on-chain swaps, aggregating bridges and DEXs in crypto world. **Rango Exchange** offers the building blocks for cross-chain and on-chain swaps. The current state of crypto ecosystem includes hundreds of blockchains which are connected with tens of bridges, and thousands of DEXs and DeFi protocols on these chains. Rango is a new layer on top of all Bridges and DEXs, aggregating all of them to enable seamless on-chain and cross-chain swaps, finding the most efficient, safe, cheap and fast route for swapping from any token on any blockchain to any other token to any blockchain. ## New to Rango? If you are not familiar with Rango or Crosschain Bridge/DEX aggregation, we recommend you to start off reading [**Introduction to Rango Exchange**](/introduction). ## Rango For DeFi Users :person\_tipping\_hand: [**How Rango Works?**](/how-it-works)\ Find out what you can do using Rango Exchange [**⚖️ Rango vs. Other Aggregators**](/rango-vs.-competitors)\ What sets Rango apart from it's competitors and other aggregators. [**✅ Integrations**](/integrations)\ Blockchains, DEXs and Bridges integrated/aggregated by Rango [**🛣 Roadmap**](/roadmap)\ See what integrations lie ahead and what you can expect from Rango in the future [**🦎Tokenomics**](/tokenomics)\ Want to know more about the RANGO Token? Every details are given in the Tokenomics section [**💵 Affiliate & Referral Program**](/technical/monetization)\ For those who want to start earning money by using Rango affiliate system [**💰Airdrop**](/airdrop)\ Anything related to RANGO token airdrop for our users [**❓FAQ**](/faq)\ Check what questions other users of Rango have frequently asked [**📰 Monthly Updates & Exclusive Content**](https://blog.rango.exchange/)\ Follow our [Medium blog](https://blog.rango.exchange/) for updates and in-depth analytical content 🙋‍♀️**Other Stuff**\ Want to know more? Get in touch on [Telegram](https://t.me/rangoexchange), [Discord](https://discord.com/invite/q3EngGyTrZ) or [Twitter](https://twitter.com/RangoExchange)! ## Rango For dApps, Wallets and other Web3 Protocols dApp owners and other protocols can harness the capabilities of Rango's cross-chain route finding and message passing framework using our API/SDK and Widget. 🔹Check out our [SDK Integration Guide](/api-integration/basic-api-single-step/tutorial/sdk-example) to learn how to use our SDK and get to know the API flows. 🔹Use our [Widget Integration Guide](/widget-integration/overview) to effortlessly add cross-chain swap functionality to your website. ## Rango For DEXs, Bridges and Liquidity Protocols 🔹If you are a decentralized/on-chain liquidity protocol or a bridge, you can contact us regarding integration of your services. Make sure to send technical info and integration docs as our tech team might need to review them before planning/deciding for integration. # Introduction Rango Exchange, The First Multi-chain Bridge & DEX Aggregator, All-in-one swap for all coins in all blockchains ## About Rango Rango Exchange is the most powerful multi-chain platform for DEX and bridges all around the crypto world, based on reach-ability and support of top blockchains. It doesn’t matter where the user is and where he or she wants to go, Rango will be able to find the most secure, fast, and easy path for it. We currently support more than 55 blockchains, 100 DEXes, 22 bridges, and 24 different wallets, with a modern and user-friendly UX in the market. Unlike most of the other “multi-chain” products in the market, we are not limited to any specific type of blockchain. Rango supports most of the top EVM-based, Cosmos-based, Solana and UTXO blockchains, and will soon tame Near, Polkadot, Cardano, and many more. What makes Rango unique is to integrate top on-chain services in the market to provide the best liquidity and user experience at the same time and remove the need to use multiple services with different interfaces. All wallets can be connected to Rango to check for any tokens in any blockchains and they can be swapped to each other no matter where the source or destination is. ## Useful Links * [Rango Website](https://rango.exchange/) * [Rango dApp](https://app.rango.exchange/) * [Rango Github](https://github.com/rango-exchange/) * [Rango Twitter](https://twitter.com/RangoExchange) * [Rango Discord](https://discord.com/invite/q3EngGyTrZ) * [Rango Medium](https://medium.com/@rangoexchange) * [Rango Announcement Channel in Telegram](https://t.me/rango_info) * [Rango Group Chat in Telegram (Support)](https://t.me/rango_info) # How It Works How does Rango Exchange Work? To provide the best routing across every blockchain through decentralized protocols, Rango has built the industry leading routing engine covering every ecosystem. When a request for routing is submitted to Rango’s routing engine, the engine goes through combinations of 100 dexes and 24 bridges across more than 50 blockchains to arrive at desirable paths.
Rango’s architecture is designed to be chain agnostic and hence, we support protocols across EVMs, Bitcoin, Cosmos, Solana, Starknet and other ecosystems. Rango’s infrastructure gathers data from every protocol to find good routes among thousands of possible paths. Rango provides access to all types of network from a single interface and API:
Rango covers a wide range of protocols and models such as RFQ, burn/mint, cross-chain pools and IBC. Rango leverages decentralized message passing systems such as GMP, LayerZero and IBC Memos to make sure the message passing and execution of the routes are handled through decentralized protocols. # Integrations List of all Blockchains and Protocols supported by Rango Rango is the best cross-chain aggregator protocol supporting a wide range of technologies including Ethereum, Solana, Cosmos, UTXO, etc. Here you can explore the latest integrated blockchains, DEXes, and bridges supported by Rango. You can also retrieve this information via Rango API as described in the link below. {% content-ref url="/pages/Wvp6KKsOm4covYKpOJU8" %} [Get Blockchains & Tokens](/api-integration/basic-api-single-step/api-reference/get-blockchains-and-tokens) {% endcontent-ref %} ## Supported Blockchains ### EVM Based
StatusBlockchain Name (ID)Blockchain TitleChain ID
✅ARBITRUMArbitrum 0xA4B1
✅AURORAAurora0x4E454152
✅AVAX_CCHAINAvalanche0xA86A
✅BASEBase0x2105
✅BLASTBlast0x13E31
✅BOBABoba 0x120
⏸️BOBA_AVALANCHEBoba Avalanche0xA918
✅BOBA_BNBBoba Bnb0xDBE0
✅BSCBNB Smart Chain0x38
⏸️BRISEBrise0x7F08
✅CELOCelo0xA4EC
✅CRONOSCronos0x19
✅ETHEthereum0x1
⏸️EVMOSEvmos0x2329
⏸️FANTOMFantom0xFA
⏸️FUSEFuse0x7A
⏸️GNOSISGnosis0x64
⏸️HARMONYHarmony0x63564C40
✅HECOHeco0x80
⏸️KCCKCC0x141
✅LINEALinea0xE708
✅METISMetis0x440
✅MODEMode0x868B
✅MOONBEAMMoonbeam0x504
✅MOONRIVERMoonriver0x505
✅OKCOKX Chain (OKC)0x42
✅OPTIMISMOptimism0xA
✅POLYGONPolygon0x89
✅POLYGONZKPolygon zkEVM0x44D
✅SCROLLScroll0x82750
⏸️TELOSTelos0x28
✅ZKSYNCZkSync era0x144
✅SONICSonic0x146
✅TAIKOTaiko0x167000
✅ZORAZora0x8453
✅BERACHAINBerachain0x80094
✅XLAYERXLayer0x196
✅IOTAIOTA0x8822
✅SHIMMERShimmer0x148
### Cosmos Based
StatusBlockchain Name (ID)Blockchain TitleChain ID
✅AKASHAkashakashnet-2
⏸️AXELARAxelaraxelar-dojo-1
✅BANDCHAINBandChainlaozi-mainnet
✅BNBBinance ChainBinance-Chain-Tigris
✅BITCANNABitCannabitcanna-1
✅BITSONGBitSongbitsong-2b
✅CHIHUAHUAChihuahuachihuahua-1
✅COMDEXComdexcomdex-1
✅COSMOSCosmoscosmoshub-4
✅CRYPTO_ORGCrypto.orgcrypto-org-chain-mainnet-1
✅DESMOSDesmosdesmos-mainnet
✅DYDXDyDxdydx-mainnet-1
✅EMONEYE-Moneyemoney-3
✅INJECTIVEInjectiveinjective-1
✅IRISIRISNetirishub-1
✅JUNOJunojuno-1
✅KIKikichain-2
✅KONSTELLATIONKonstellationdarchub
✅KUJIRAKujirakaiyo-1
✅LUMNETWORKLum Networklum-network-1
✅MARSMarsmars-1
✅MAYAMayamayachain-mainnet-v1
✅MEDIBLOCMediBlocpanacea-3
✅NEUTRONNeutronneutron-1
✅NOBLENoblenoble-1
✅OSMOSISOsmosisosmosis-1
✅PERSISTENCEPersistencecore-1
✅REGENRegenregen-1
✅SECRETSecretsecret-4
✅SENTINELSentinelsentinelhub-2
✅STARGAZEStargazestargaze-1
✅STARNAMEStarnameiov-mainnet-ibc
✅STRIDEStridestride-1
⏸️SIFSifchainsifchain-1
✅TERRATerraphoenix-1
⏸️TERRA_CLASSICTerra Classiccolumbus-5
✅THORThorchainthorchain-mainnet-v1
✅UMEEUmeeumee-1
### Others
StatusBlockchain Name (ID)Blockchain TitleType
✅BTCBitcoin TRANSFER
✅BCHBitcoin CashTRANSFER
✅DASHDashTRANSFER
✅DOGEDogeTRANSFER
✅LTCLiteCoinTRANSFER
✅SOLANASolanaSOLANA
✅TRONTronTRON
✅STARKNETStarkNetSTARKNET
✅TONTon
✅SUISuisui-mainnet
## Supported DEXes ### EVM Based
StatusSupported Dex or AggregatorActive Chains in Rango
✅1inchArbitrum, BSC, Ethereum, Gnosis, Optimism, Polygon
✅AuroraSwapAurora
✅BeamSwapMoonbeam
✅CherrySwapOKC
✅CronaSwapCronos
✅DiffusionEvmos
✅MDexHecoHeco
✅MMFinanceCronos
✅OolongSwapBoba
✅OpenOceanFantom
✅PancakeSwapBSC
✅ParaswapAvax, Polygon, BSC, Arbitrum, Fantom, Optimism, Polygon
✅PangolinAvax
✅QuickSwapPolygon
✅SolarbeamSwapMoonriver
✅SpookySwapFantom
✅StellaSwapMoonbeam
✅SushiswapHarmony, OKExChain, HECO, Arbitrum, BSC
✅TrisolarisSwapAurora
✅UniswapV2Ethereum
✅ViperswapHarmony
✅VoltageSwapFuse
✅VVSFinanceCronos
⌛DODOHECO
⌛UbeSwapCelo
### Others
StatusSupported Dex or AggregatorActive Chains in Rango
✅JupiterSolana
✅OsmosisAll cosmos-based chains active in Rango
## Supported Bridges ### EVM Based
StatusBridgeActive Chains in Rango
✅AcrossArbitrum, Ethereum, Optimism, Polygon
✅Arbitrum BridgeArbitrum, Ethereum
✅Avalanche BridgeAvax, Ethereum
⏸️Binance BridgeAvax, Bitcoin, BSC, Cosmos, Doge, Ethereum, Fantom, Litecoin, Polygon
✅CBridge v2Arbitrum, Aurora, Avax, BSC, Ethereum, Fantom, Fuse, Gnosis, Moonriver, Optimism, Polygon
✅HopArbitrum, Ethereum, Gnosis, Optimism, Polygon
⏸️Horizon BridgeBSC, Ethereum, Harmony
✅HyphenAvax, Arbitrum, BSC, Ethereum, Optimism, Polygon
✅Polygon Bridge (PoS)Ethereum, Polygon
⏸️Multichain (Anyswap)Arbitrum, Aurora, Avax, BSC, Ethereum, Fantom, Fuse, Gnosis, Moonriver, Optimism, Polygon
✅Rainbow BridgeEthereum, Aurora
✅StargateArbitrum, Avax, BSC, Ethereum, Fantom, Optimism, Polygon
✅WormholeAvax, BSC, Ethereum, Fantom, Polygon
⌛deBridge
⌛Synapse
⌛Connext
### Others
StatusBridgeActive Chains in Rango
✅OsmosisIBC for all cosmos-based chains active in Rango
✅Satellite (Axelar)Ethereum, Osmosis, Polygon
✅SifchainEthereum, Sifchain
✅ThorchainEthereum, Bitcoin, Bitcoin Cash, Doge, Litecoin, Terra, Thorchain
✅WormholeAvax, BSC, Ethereum, Fantom, Polygon, Solana, Terra
[^1]: It is disabled after Multichain protocol hack and Fantom stable coin depeg. [^2]: It is disabled after Harmony Hack. # Rango vs. Competitors Rango is not only the first, but the TRUE cross-chain aggregator available. Rango offers the most advanced cross-chain and on-chain aggregation. The difference between Rango and other aggregators can be viewed from different perspectives: ## Rango vs. EVM Aggregators Most of the cross-chain aggregators only support aggregation between EVM blockchains. On the other hand, Rango supports a handful of blockchain ecosystems, including: * **UTXO** blockchains (BTC, LiteCoin, BitcoinCash, etc.) * **EVM** blockchains * **Cosmos** blockchains * **ZK-Rollups** (Starknet, zkSync, zkEVM Polygon) * **Solana** blockchain * **Tron** blockchain We believe by supporting different ecosystem, Rango not only helps crypto natives to transfer funds easier to other chains, but also encourages and supports innovation which is being taken place in different parts of crypto ecosystem. We believe that Rango's mission is to support the whole crypto market, both users and also any protocol that is trying to address users' needs and improve the experience & usability of the decentralized world. ## Rango vs. Single Chain Aggregators Protocols like **1inch**, **ParaSwap**, **0x**, **OpenOcean** and other DEX aggregators also provide route-finding service for users, but they are limited to single chain transactions. Rango is standing on the shoulder of these giants by aggregating their solutions with tens of **bridges**, enabling cross-chain any-to-any swap route-finding for all of the decentralized world. Moreover, by integrating all of these DEX aggregators, Rango can be used also as an on-chain swap aggregation solution, finding the most efficient route by comparing outputs from all of the DEX aggregators. ## Core Values of Rango * **Security & Agility:** For Rango, as a DeFi project with high maintenance cost and frequent changes in underlying protocols, agility and speed in development, particularly in Contracts Development, are crucial. However, this agility must not compromise user safety by deploying non-audited contracts into production. Our experience indicates that projects ignoring this rule often face hacks or pose high risks to users. After three years of launching and maintaining Rango, we are proud to say that we have never deployed our contracts into production without thorough audits. * **Integrity & Fairness:** Rango focuses solely on the best results for the user and does not favor any protocol over another. The only factors examined by Rango are availability of the service, transparency of how the protocol works, the degree of decentralization and the speed of transaction processing. * **Accountability:** We value answer-ability and transparent communication with the users in case of swap failure, which could not be achieved without providing online support and guidance to our users. Any swap on Rango has a unique identifier which could be easily used to seek help from the support team. The support team members are active in our Telegram group and Discord server and can help you find out what has gone wrong in your transaction. * **Creativity & Innovation:** We believe that innovation plays a key role in development and adoption of crypto-currencies. Therefore, anyone who innovates to improve the quality of services/experience of the decentralized world deserves to be encouraged and supported. As long as the security constraints allow us, we try to integrate more protocols and blockchains to help users with migrating funds and using available services and opportunities. # Security Rango Exchange Security Security is one of the highest priorities for us in Rango and we aim to make sure our users are not. \ To achieve this goal we abide by security best practices in industry. #### **Smart Contracts:** Rango never deploys un-audited smart contracts and we avoid exposing users to risks. Our smart contracts go through rigorous internal and external audits before being used in production. ( Link to Audit reports ) Rango uses multi-signature admins wherever necessary. **Protocol Security** Rango never implements a weak protocol. All bridges/DEXs go through a security vetting mechanism before implementation to ensure user safety. Rango Operation Department always monitors on-chain activity and disables affected protocols which have confirmed incident(s) or security breaches. **SSL, WAF, Dos & DDoS Protection & Rate Limits** Rango uses ssl for all communications, all traffic is encrypted from user to edge and origin servers with trusted SSL keys.In addition Rango uses WAF with adaptive rules to detect any attacks and prevent suspicious activity. IDP systems are in place for rapid response to any security issue(s) or attacks as they arise. **Application Layer** Rango has implemented circuit breakers, pausing mechanisms and health checks. If any protocol does not look healthy in terms of uptime or liquidity, it is dynamically dropped out of our routing system. The tokens available on our platform are dynamically retrieved from underlying bridges and dexes. We also check for honeypots and tax tokens using third party APIs. **Infrastructure:** Our infra uses several hardware and software-based firewalls. # Roadmap This is our next two years roadmap. As the crypto world is always changing, we might decide to re-order the priority of the integrations of the road map a bit in the future. Receiving grants for Rango, changes in blockchains/wallets trends, community requests could be some of the reasons for these sorts of plan updates. ## ✔ 2021 Q3 {% tabs %} {% tab title="Integrations" %} * [x] Thorchain * [x] 1inch (Ethereum, BSC, Polygon) * [x] Terra Swap * [x] Terra Bridge * [x] Lido (Terra, Eth) * [x] Binance Bridge * [x] Osmosis {% endtab %} {% tab title="Wallets" %} * [x] Metamask * [x] Terra Station * [x] Binance Chain * [x] Keplr * [x] XDefi {% endtab %} {% tab title="Misc" %} * [x] Affiliate Service * [x] Documentations {% endtab %} {% tab title="Reports" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} {% endtab %} {% endtabs %} ## ✔ 2021 Q4 {% tabs %} {% tab title="Integrations" %} * [x] Anyswap * [x] CBridge * [x] Paraswap * [x] Spookyswap * [x] Horizon Bridge * [x] Uniswap * [x] Avax * [x] Fantom * [x] Harmony * [x] Sifchain {% endtab %} {% tab title="Wallets" %} * [x] Harmony One {% endtab %} {% tab title="Token" %} * [x] Finalize Tokenomics * [x] Private Sale Round 1 * [x] $Rango token related smart contracts {% endtab %} {% tab title="Misc" %} * [x] Revamping designs * [x] Multi-Hop contract on Terra {% endtab %} {% tab title="Reports" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} {% endtab %} {% endtabs %} ## ✔ 2022 Q1 {% tabs %} {% tab title="Integrations" %} * [x] Astroport * [x] Loop Markets * [x] Pancake Swap * [x] Chain Swap * [x] Open Ocean * [x] Arbitrum * [x] Chihuahua * [x] Thorchain Terra support * [x] Axelar (Terra) {% endtab %} {% tab title="Wallets" %} * [x] Leap {% endtab %} {% tab title="Misc" %} * [x] JS SDK * [x] Gitbook Docs {% endtab %} {% tab title="Reports" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} {% endtab %} {% endtabs %} ## ✔ 2022 Q2 {% tabs %} {% tab title="Integrations" %} * [x] Wormhole * [x] Synapse * [x] Optimism * [x] Jupiter * [x] Juno * [x] Comdex * [x] Stargaze * [x] Starname * [x] Desmos * [x] Bitcanna * [x] Moonriver * [x] Fuse * [x] Aurora {% endtab %} {% tab title="Wallets" %} * [x] Phantom * [x] Wallet Connect {% endtab %} {% tab title="Reports" %} {% embed url="" %} {% endtab %} {% endtabs %} ## ✔ 2022 Q3 {% tabs %} {% tab title="Integrations" %} * [x] Rainbow Bridge * [x] CherrySwap * [x] Diffusion * [x] MDexHeco * [x] TrisolarisSwap * [x] Stargate * [x] Hop * [x] MMFinance * [x] Nomad * [x] Hyphen * [x] OolongSwap * [x] VVSFinance * [x] THORChain Aggregator * [x] ViperSwap * [x] StellaSwap * [x] BeamSwap * [x] Across * [x] SushiArbitrum * [x] QuickSwap {% endtab %} {% tab title="Wallets" %} * [x] Coinbase Wallet * [x] Coin98 Wallet * [x] Clover Wallet * [x] Math Wallet {% endtab %} {% tab title="Reports" %} {% embed url="" %} {% endtab %} {% endtabs %} ## ✔ 2022 Q4 {% tabs %} {% tab title="Integrations" %} * [x] OKX Chain * [x] Bitgert Chain * [x] Cronos Chain * [x] BandChain * [x] Umee Chain * [x] Symbiosis * [x] OkcSwap * [x] FinKujira * [x] Voyager (Router Protocol) {% endtab %} {% tab title="Wallets" %} * [x] Cosmostation Wallet * [x] SafePal Wallet * [x] TocketPocket Wallet * [x] Excodus Wallet * [x] CoinBase Wallet * [x] Brave Wallet * [x] Trustwallet Extension {% endtab %} {% endtabs %} ## ✔ 2023 Q1 {% tabs %} {% tab title="Integrations" %} * [x] XY finance bridge * [x] Aurora chain * [x] Allbridge core {% endtab %} {% tab title="Wallets" %} * [x] SafePal Wallet * [x] Exodus Wallet {% endtab %} {% tab title="Features" %} * [x] Rango’s official Discord {% endtab %} {% tab title="Reports" %} {% embed url="" %} {% endtab %} {% endtabs %} ## ✔ 2023 Q2 {% tabs %} {% tab title="Integrations" %} * [x] Starknet chain * [x] Orbiter Birdge * [x] 10KSwap * [x] Kucoin Community Chain (KCC) * [x] Maya protocol * [x] Stride chain {% endtab %} {% tab title="Wallets" %} * [x] Argent Wallet {% endtab %} {% tab title="Features" %} * [x] Rango V2 smart-contract {% endtab %} {% endtabs %} ## ✔ 2023 Q3 {% tabs %} {% tab title="Integrations" %} * [x] Polygon zkEVM chain * [x] XY finance integration for Polygon zkEVM * [x] PancakeSwap V3 integration for Polygon zkEVM * [x] OpenOcean integration for Polygon zkEVM * [x] zkSync chain * [x] XY finance integration for zkSync * [x] Orbiter Finance integration for zkSync * [x] SpaceFiSwap integration * [x] Linea chain * [x] PancakeV3 integration for Linea * [x] Orbiter integration for Linea * [x] Debridge integration for Linea * [x] XY finance integration for Linea {% endtab %} {% endtabs %} ## ✔ 2023 Q4 {% tabs %} {% tab title="Integrations" %} * [x] AVNU integration * [x] THORChain streaming * [x] Noble chain {% endtab %} {% tab title="Features" %} * [x] Rango's re-branding * [x] Launching the new UI {% endtab %} {% endtabs %} ## ✔ 2024 Q1 {% tabs %} {% tab title="Integrations" %} * [x] Base chain * [x] Enabling Stargate for Base * [x] Enabling Debrigde for Base. * [x] Enabling Across for Base. * [x] Enabling Curve for Base. * [x] Uniswap v3 for Base. * [x] 1inch integration for Base. * [x] zkSwap integration * [x] Blast chain * [x] Thruster integration for Blast. * [x] XY finance bridge integration for Blast * [x] XO swap integration
{% endtab %} {% tab title="Wallets" %} * [x] Braavos Wallet {% endtab %} {% tab title="Features" %} * [x] Multi-routing {% endtab %} {% tab title="Reports" %} {% embed url="" %} {% embed url="" %} {% endtab %} {% endtabs %} ## ✔ 2024 Q2 {% tabs %} {% tab title="Integrations" %} * [x] Scroll chain * [x] Zebra Swap integration * [x] Enabling XY finance for Scroll * [x] ChainFlip * [x] SWFT and Bridgers. * [x] Celo chain * [x] Enabling SWFT for Celo * [x] Enabling Axelar For Celo * [x] Enabling Allbridge for Celo * [x] Uniswap V3 integration for Celo * [x] UbeSwap integration for Celo {% endtab %} {% tab title="Wallets" %} * [x] Tomo Wallet * [x] Solana Snap Wallet {% endtab %} {% tab title="Features" %} * [x] Rango Brand-New Dapp * [x] Rango Statitics page {% endtab %} {% tab title="Reports" %} {% embed url="" %} {% embed url="" %} {% endtab %} {% endtabs %} ## ✔ 2024 Q3 {% tabs %} {% tab title="Integrations" %} * [x] Maya’s Arbitrum liquidity integration * [x] Mode integration * [x] Enabling Across for Mode * [x] Enabling Orbiter Finance for Mode * [x] Swap Mode integration * [x] Xlayer integration * [x] PotatoSwap integration * [x] XY finance integration for XLayer * [ ] Shimmer integration * [x] ChainFlip Arbitrum liquidity pool integration.. * [x] ChainFlip Solana liquidity pool integration. * [x] Stargate V2 {% endtab %} {% tab title="Wallets" %} * [x] Rabby Wallet * [x] Ledger * [x] Trezor {% endtab %} {% tab title="Features" %} * [x] User profile and scoring system {% endtab %} {% tab title="Reports" %} {% embed url="" %} {% endtab %} {% endtabs %} ## ✔ 2024 Q4 {% tabs %} {% tab title="Integrations" %} * [x] Taiko * [x] Ton * [x] IOTA * [x] Fantom (re-enable) {% endtab %} {% tab title="Wallets" %} * [x] Tonkeeper {% endtab %} {% tab title="Features" %} * [x] Rango new version and audit for smart-contract * [x] Rango’s gamified campaign * [x] Bitcoin PSBT {% endtab %} {% endtabs %} ## ✔ 2025 {% tabs %} {% tab title="Integrations" %} * [x] XRP Ledger * [x] Zora * [x] Sonic * [x] Sui * [x] Unichain * [x] Monad * [x] Soneium * [x] Berachain {% endtab %} {% tab title="Wallets" %} * [x] Slush * [x] Xverse * [x] UniSat * [x] GemWallet {% endtab %} {% tab title="Features" %} * [x] Rango ReFuel * [x] Rango aggregator smart contract upgrade * [x] Rango public leaderboard * [x] Rango profile leaderboard * [x] Rango Learn Center {% endtab %} {% endtabs %} ## 2026 Q1 {% tabs %} {% tab title="Integrations" %} * [x] Stellar * [x] MegaETH {% endtab %} {% tab title="Wallets" %} * [x] Freighter Wallet {% endtab %} {% tab title="Features" %} * [x] Gasless Swaps on Solana * [x] Gasless Swaps on EVM * [x] Swap Intents for TON * [x] Swap Intents for EVM * [x] Swap Intents for Tron {% endtab %} {% endtabs %} ## 2026 Q2 {% tabs %} {% tab title="Integrations" %} * [ ] TBA {% endtab %} {% tab title="Wallets" %} * [ ] TBA {% endtab %} {% tab title="Features" %} * [ ] Gasless Swaps expansion on more networks * [ ] Payment Intents for TON * [ ] Payment Intents for EMV * [ ] Launch of Generalized Intent Composer * [ ] Lending Intent on EVMs * [ ] AI Assisted Intent Execution for Swaps and Payments * [ ] Perps Trading {% endtab %} {% endtabs %} ## 2026 Q3 {% tabs %} {% tab title="Integrations" %} * [ ] TBA {% endtab %} {% tab title="Wallets" %} * [ ] TBA {% endtab %} {% tab title="Features" %} * [ ] Swap/Payment/Lending intent extension for other networks * [ ] Trading commands * [ ] Swap Intents for Solana * [ ] Payment Intents for Solana * [ ] Swap Intents for Bitcoin * [ ] Payment Intents for Bitcoin {% endtab %} {% endtabs %} ## 2026 Q4 {% tabs %} {% tab title="Integrations" %} * [ ] TBA {% endtab %} {% tab title="Wallets" %} * [ ] TBA {% endtab %} {% tab title="Features" %} * [ ] DCA Intents across all chains * [ ] Limit Order Intents across all chains * [ ] Yield Bearing DCA strategies * [ ] AI assisted execution for DCA Intents * [ ] AI assisted execution for Limit Order Intents * [ ] AI assisted execution for NFT purchase * [ ] Spot Trading * [ ] Mobile App Experience Improvements {% endtab %} {% endtabs %} * **New updates coming** # Tokenomics ## Rango Token `$RANGO` is the token of Rango Protocol. It can be used in the governance of the project as in creating polls and voting but also can be used to incentivize growth, usage and also reward early supporters of the project. The token is not available for sale/trade yet before the IDO. ## Token Distribution **New tokenomics will be announced very soon, stay tuned.**
# Airdrop Due to Rango's tokenomics, 8% of the total share of $RANGO is allocated to airdrops. Airdrops are given to the platform and non-platform users for various reasons. The main goal of airdrops is to bring more users to the platform and increase adoption, so using our platform in general, may lead to airdrops for anyone. Currently, two different campaigns for airdrop are explicitly announced and the other options will be announced eventually: ## Badge Trading Competition In this competition, the scoring is based on badges which you get rewarded based on your usage in Rango. Each badge is given for some specific actions. And there are badges that are hidden. These badges are available until the end of the IDO. By the end of the IDO, we will give 10% of $Rango’s airdrop share to the top 1,000 users based on their badge scores. Read more details in the competition medium post. **Status: Ended** {% embed url="" %} {% file src="/files/yLZJZ5YOsjbGDkZirk50" %} Badge Competition Airdrop Eligible Chameleons {% endfile %} ## Upcoming campaigns Stay tuned for more upcoming Airdrop campaigns! In the meantime, you can frequently interact with Rango and perform cross-chain swaps. # FAQ Here is the list of questions Rango users have frequently asked.
1. What is Rango? Rango is a cross-chain DEX aggregator. It combines the power of DEX aggregators inside blockchains (e.g. 1Inch) with multiple bridges (e.g. Stargate Bridge) and cross-chain liquidity providers (e.g. Thorchain) to give you access to better liquidity. Rango can provide you with complex routes from any coin in any blockchain to another coin in other blockchains. Alternatively, we should search and compare multiple DeFi tools yourself, while Rango aggregates all of them in an easy-to-use and elegant UI and much better user experience.
2. What is the difference between ETH.ETH and BSC.ETH? Since Rango is a multi-chain swapper, users can swap tokens inside a network and/or from one network to another. So you might see the same token in multiple networks, that's why tokens' names in Rango are shown in `X.Y` format, which means token name `Y` on `X` network. So `ETH.ETH` means ETH token on Ethereum network \[aka ETH native token], while `BSC.ETH` means wrapped ETH token on Binance Smart Chain network. As another example, if you like to swap to USDT, you have at least four options including `ETH.USDT`, `BNB.USDT`, `BSC.USDT`, `Polygon.USDT`. All of them are USDT but each one is in a different network.
3. What is Routing? Routing is the process that Rango computes the best path for your swap. Unlike Uniswap or Sushiswap which work inside a blockchain (e.g. `Ethereum`), Rango helps your chain multiple intra-chain and inter-chain products to achieve your goal. Example: If you like to swap your `SHIB` (in `Ethereum` network) to `DOGGY` (on `BSC`) here is a possible routing of 3 steps: 1. Convert `SHIB` to native `ETH` via 1inch-Ethereum. 2. Use Binance Bridge to transfer your `native ETH` to `wrapped ETH` on `BSC` network. 3. Convert `Wrapped ETH` to `DOGGY` via 1inch-BSC.
4. Why finding a route is sometimes slow? Rango finds the best route among tens of thousands of possible routes on real-time exchange rates from multiple sources. Sometimes these sources have slow API or fail to answer in a certain amount of time. So Rango retries and waits for them to make sure the best route is finally offered to the user.
5. Is Rango secure? **Yes, definitely**. We are secure due to multiple reasons: 1. all your money is always in your own wallets 2. rango integrates the very best solutions and products like 1Inch and Thorchain which are backed by professional teams and powerful ecosystems 3. You can always view the details of transactions and revise them before accepting or rejecting them 4. Rango always find the best and most profitable route for you, so you'll experience the lowest possible slippage
6. What wallets should I have to swap cross-chain? Currently, we support Metamask, Binance Chain Wallet, Terra Station, XDefi, Harmony One, Keplr, and we are going to support many more wallets soon. Example: Assume you want to do a complex cross-chain swap, e.g. convert your DOGGY (which is in BSC network) to Anchor protocol (ANC) in Terra, you should connect a BSC enabled wallet (ex: Metamask or Binance Smart chain Wallet) and also your Terra Station wallet. The rest of the process is easy and you are guided via the Rango app.
7. Which blockchains do you currently support? Rango currently supports 16 blockchains, including Bitcoin, Ethereum, Binance Chain, Binance Smart Chain, Terra, Osmosis, Cosmos, Akash, Polkadot, Doge, etc. And we are planning to include many more chains in near future.
8. Why I see 'No path found'? It can sometimes happen due to these reasons: 1. Your input amount is lower than some limits, ex: Terra Bridge needs the input to be at least 10$. 2. Your input amount is too high, some bridges or LPs (Especially for low market cap tokens) do have some daily or per-transaction limits. 3. Your requested coin is not supported by any of our bridges, LPs, and DEX aggregators.
My transaction was unsuccessful, is my funds safe? How to recover funds? Do not get worried. Your funds are safe and in your own wallets, maybe in form of tokens not shown by default in your wallet. Feel free to join our [telegram group](https://t.me/rangoexchange) and ask support about your transaction. The support team will help you to recover the missing funds. Note that admins **NEVER** send your direct/private messages before you send them a direct message. Ask your question in telegram group and wait for admins to reply in the group. Or send a DM to the admins of telegram group with the request id of your transaction. **Remember**: **RANGO admins will never DM you first**.
# Bug Bounty If you found a vulnerability in our smart contracts or system, please send an email to ## Out of Scope & Rules ### The following vulnerabilities are excluded from the rewards and/or prohibited: * Attacks that the reporter has already exploited themselves, leading to damage * Attacks requiring access to leaked keys/credentials * Attacks requiring access to privileged addresses (governance, multisigs, admins) ### Websites and Apps * Theoretical vulnerabilities without any proof or demonstration * Attacks requiring physical access to the victim device * Attacks requiring access to the local network of the victim * Reflected plain text injection ex: url parameters, path, etc. * This does not exclude reflected HTML injection with or without javascript * This does not exclude persistent plain text injection * Self-XSS * Captcha bypass using OCR without impact demonstration * CSRF with no state modifying security impact (ex: logout CSRF) * Missing HTTP Security Headers (such as X-FRAME-OPTIONS) or cookie security flags (such as “httponly”) without - monstration of impact * Server-side non-confidential information disclosure such as IPs, server names, and most stack traces * Vulnerabilities used only to enumerate or confirm the existence of users or tenants * Vulnerabilities requiring un-prompted, in-app user actions that are not part of the normal app workflows * Lack of SSL/TLS best practices * DDoS vulnerabilities * Feature requests * Issues related to the frontend without concrete impact and PoC * Best practices issues without concrete impact and PoC * Vulnerabilities primarily caused by browser/plugin defects * Leakage of non sensitive api keys ex: etherscan, Infura, Alchemy, etc. * Any vulnerability exploit requiring browser bugs for exploitation. ex: CSP bypass * Best practice concerns * Recently (less than 30 days) disclosed vulnerabilities in the supply chain * Vulnerabilities affecting users of outdated browsers and/or platforms * Social engineering or phishing attemps * Vulnerabilities that require specific third party software on the user’s machine that is not part of the general - ecase (i.e. browser + wallet add-on) * Clickjacking/Tapjacking unless performed on a subdomain of rango.exchange * Tabjacking unless performed on a subdomain of rango.exchange * The blog hosted at blog.rango.exchange ### The following activities are prohibited by this bug bounty program: * Any testing with mainnet or public testnet contracts; all testing should be done on private testnets * Any testing with pricing oracles or third party smart contracts * Attempting phishing or other social engineering attacks against our employees and/or customers * Any testing with third party systems and applications (e.g. browser extensions) as well as websites (e.g. SSO providers, advertising networks) * Any denial of service attacks * Automated testing of services that generates significant amounts of traffic * Public disclosure of an unpatched vulnerability in an embargoed bounty ### Smart Contracts and Blockchain * Incorrect data supplied by third party oracles (Not to exclude oracle manipulation/flash loan attacks) * Basic economic governance attacks (e.g. 51% attack) * Lack of liquidity * Best practice critiques * Sybil attacks * Centralization risks # Terminology Terms and Naming Conventions in Rango Exchange In this document, we will briefly review the concepts related to Rango's API or SDK to make on-boarding across different sections of the documentation easier for you. ## Affiliate (Referral) We use the terms `affiliate` or `referral` to describe our program available to both individual users and dApps. By joining the program, individuals can refer new users to our platform and earn an affiliate fee for the swap transactions initiated by their referrals. Additionally, dApps can charge users an extra fee per transaction, which will be deducted from the user's input amount. For more detailed information about our affiliate program, please refer to [this document](/technical/monetization). ### Affiliate Ref (Referrer Code) The `Affiliate Reference (affiliateRef)` or `Referrer Code (referrerCode)` is an unique key that you could generate on our [Affiliate Page](https://app.rango.exchange/affiliate) in Rango Exchange dApp. If you use this, we will send the affiliate fees to the wallet that created this link.

Sample for affiliateRef Code in Rango Exchange App

## Asset (Token) Rango uses the terms `asset` or `token` to identify tokens across different blockchains. Currently, Rango supports over 10,000 tokens and also enables the trading of `custom tokens` on all EVM-based and Solana blockchains. In Rango, each token is identified by three properties: Blockchain, Symbol, and Address. While the combination of Blockchain and Address is sufficient to identify a unique token in EVM-based blockchains, Rango also supports various other blockchains, such as Cosmos-based ones. To maintain a consistent API across all endpoints, the Symbol property is also included. {% hint style="info" %} ### Asset Format When dealing with asset formats, it's crucial to distinguish between native and non-native coins. Below is the format you should use for each type: #### 1. Native Coins: * **Format:** `Blockchain.Symbol` or simply use `Blockchain` * **Examples:** * `BSC.BNB (or BSC), SOLANA.SOL (or SOLANA),` `OSMOSIS.OSMO (or OSMOSIS)` This denotes the blockchain on which the native coin operates, followed by the symbol of the coin itself. #### 2. Non-Native Coins: * **Format:** `Blockchain--TokenAddress` * **Other Acceptable Format:** `Blockchain.Symbol--TokenAddress` \ (This 2nd format is only required for Cosmos tokens and will be deprecated soon.) * **Examples:** * `BSC--0x55d398326f99059ff775485246999027b3197955` * `BSC.USDT--0x55d398326f99059ff775485246999027b3197955` This format consists of the blockchain and the token's address on the blockchain, which are separated by a double dash (--). {% endhint %} {% hint style="info" %} **Native Token Address** For native tokens, we do not use addresses like `0xeeeeeeeeeeeeeeeeee...` or `0x000000000000000...` \ Instead, we simply use a null address. {% endhint %} ## Blockchain Rango facilitates swaps and bridges across various blockchains, including UTXO blockchains, EVM blockchains, Solana, Cosmos-based blockchains, Starknet, Tron, and more. In Rango, the terms "blockchain" or "chain" are typically used to refer to these networks. \ You could see list of all supported blockchains in [Integrations](/integrations) article. You could also dynamically get list of all supported blockchains based on this [document](/api-integration/basic-api-single-step/api-reference/get-blockchains-and-tokens). ### Blockchain Name In Rango, each blockchain has a unique identifier `name` which is used in all related API calls or sdk methods. These are some samples: | Blockchain | Name (ID) | | ---------- | ------------- | | Ethereum | `ETH` | | Arbitrum | `ARBITRUM` | | Avalanche | `AVAX_CCHAIN` | | Scroll | `SCROLL` | | Cosmos | `COSMOS` | | Bitcoin | `BTC` | You could see list of all blockchain names in [Integrations document](/integrations) or get it dynamically using [meta](https://docs.rango.exchange/api-integration/pages/Wvp6KKsOm4covYKpOJU8#id-1.-get-full-metadata-test) or [blockchains](https://docs.rango.exchange/api-integration/pages/Wvp6KKsOm4covYKpOJU8#id-2.1.-get-list-of-blockchains-test) endpoint. ### Blockchain Type (Transaction Type) Rango distinguishes between various blockchains based on their technical structures and underlying transaction models. Each blockchain and transaction is assigned a property called `type`. Here are the currently supported blockchain types: | Type | Sample Blockchains | | ---------- | ------------------------------ | | `EVM` | Ethereum, Polygon, Scroll, ... | | `TRANSFER` | Bitcoin, Litecoin, Doge, ... | | `COSMOS` | Cosmos, Osmosis, Akash, ... | | `SOLANA` | Solana | | `STARKNET` | Starknet | | `TRON` | Tron | | `TON` | Ton | ## Swapper Rango supports various protocols for swapping and bridging tokens, including DEXes (e.g., Uniswap, Pancake Swap), Bridges (e.g., Across, Stargate), DEX Aggregators (e.g., 1inch, Paraswap, OpenOcean), and centralized solutions (e.g., XO Swap, SWFT). In our API and related documents, we use the `Swapper` to refer to all these protocols. {% hint style="info" %} Centralized (off-chain) swappers are disabled by default in the Rango API due to the risk of blocking user tokens because of KYC requirements for risky addresses and the need for additional information like user IP. However, if you wish to enable them, you can do so by passing a flag (`enableCentralizedSwappers`) to the relevant API calls. {% endhint %} ### Swapper Type Each swappers in Rango is at least one of the following types: (usually one of them) | Type | Sample Swappers | Description | | ------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------- | | `DEX` | Jupiter, JunoSwap, 1Inch, ... | On-chain DEXes or DEX aggregators | | `BRIDGE` | Synapse Bridge, Satellite, ... | Bridges via chains | | `AGGREGATOR` | CBridge Aggregator, Stargate Aggregator, ThorChain Aggregator, ... | [Swap Aggregators](/technical/swap-aggregation) implemented by Rango | | `OFF_CHAIN` | SWFT, XO Swap | Centralized solutions | ## Swap Aggregation Introducing Rango as a DEX and bridge aggregator means it not only routes through various protocols but also aggregates multiple transactions into a single one. For more information about swap aggregation, please refer to [this document](/technical/swap-aggregation). # API Key & Rate Limits Rango Exchange API Key & Rate Limits ## API Key To use our API endpoints, you should create a ticket on **users-support channel** of our our **Discord server** and [request an API key](https://discord.gg/q3EngGyTrZ), describing your dApp, the blockchains you like to connect to, and your dApp domain if it's a website to enable CORS headers for your API key. You should attach your API key to all your request as: ```bash curl 'https://api.rango.exchange/path/to/resource?apiKey=' ``` ## Test API Key Prior to getting an API key, you can use the test API key `c6381a79-2817-4602-83bf-6a641a409e32` for **testing purposes**. It has a fixed low rate limit and **should not be used in production**, but you can easily used it for testing the integrating Rango APIs/Widget in your product. ## Rate Limits We provide our API free of charge to our B2B partners, but it comes with default rate limits per IP and API key. If you require custom rate limits, please [get in touch with us](https://discord.gg/q3EngGyTrZ) on our Discord by creating a ticket. Examples of scenarios where higher rate limits might be necessary: * You are making server-side calls to Rango, requiring us to whitelist your servers' IPs or increase your rate limit per IP. * You are a dApp or wallet with a large user base, necessitating a higher rate limit for your API key. ## Dedicated API For our enterprise B2B customers, we offer dedicated API endpoints to isolate their API calls and enhance monitoring capabilities. # Choosing the Right API Choosing the Right API: A Tailored Comparison for Your Needs ## Introduction Rango API enables you to get the best cross-chain route for converting a token on the source blockchain to another token in the destination blockchain. It also enables dApps to relay an arbitrary message to the destination blockchain without any difficulties. We have currently *two versions of APIs / SDKs* which are maintained and actively under development. Here is a brief comparison between them: {% hint style="success" %} For almost all the scenarios, we recommend you to use **Basic API** except if you have a special requirement. {% endhint %} | Feature | Basic API (Single-step TX) | Main API (Multi-step TXs) | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | [Support all the blockchains](/integrations) | ✔ | ✔ | | [Swap Aggregation](/technical/swap-aggregation) | ✔ | ✔ | | [Referral Support](/technical/monetization) | ✔ | ✔ | | [Relaying arbitrary message](/api-integration/basic-api-single-step/api-reference/message-passing) | ✔ | ✔ | | Multi-Routing Support | ✘ (Not implemented yet) | ✔ | | Pros. & Cons. |

✔ Only one TX needed

✔ Better UX

✔ Easier to integrate

|

✔ Multi-Step Routes
✘ Multiple transactions are needed to be signed

✘ May need the gas on the destination or middle networks

| | Routing (Price & Coverage) |

✔ Optimal price for 95% scenarios

✔ Sub-optimal price for 5% scenarios

✔ Covers 85% of routes

| ✔ Best rates for all paths | | SDK NPM Package | [rango-sdk-basic](https://www.npmjs.com/package/rango-sdk-basic) | [rango-sdk](https://badge.fury.io/js/rango-sdk) | | Github | | | To summarize, if you are only interested in single-step TXs or you want to use our message relaying features, you need to use Basic SDK. Otherwise, if you want the best rates for the price and like multi-steps routes, Multi Step SDK is suitable for you. ## Basic API (Single-Step TX) If you are only interested in one-step (single-tx) routes (one action by user), this is what you need. Besides basic single step routes for the different blockchains (EVM, TRON, Solana, Cosmos, ...), it also supports aggregated cross-chain swaps for EVM blockchains in which users could perform a multistep route (dex-bridge-dex) in a single transaction. It's a popular use case in the multi-chain areas to perform a cross-chain swap. By cross-chain swap, we mean:\ **\[DEX swap on source chain] + Bridge + \[DEX swap on destination chain]** {% content-ref url="/pages/5iWxyDC58KNpr5ztOkIB" %} [Basic API - Single Step](/api-integration/basic-api-single-step) {% endcontent-ref %} {% embed url="" %} ## Main API (Multi-Step TXs) If you like multi-steps routes which you might already see in the [Rango dApp](https://app.rango.exchange/), this version of API/SDK is suitable for you.

Sample multi-step route by Rango

As you see in the picture above, Rango API gives multiple routes with multiple steps to the user for [swapping STARKNET.ETH to SOLANA.SOL](https://app.rango.exchange/bridge?fromBlockchain=STARKNET\&fromToken=ETH--0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7\&toBlockchain=SOLANA\&toToken=SOL\&fromAmount=1) and the user needs to sign at least one transaction for each step to complete this route. Users also need to have enough network fees on all middle chains. (If the route goes through some middle blockchains other than the source and the destination blockchains.) {% content-ref url="/pages/wTo2PNReeMdVDbl9g1jh" %} [Main API - Multi Step](/api-integration/main-api-multi-step) {% endcontent-ref %} {% embed url="" %} # Basic API - Single Step Rango Exchange Basic API (Single Step) # API Flow Rango Exchange Basic API Flow If you'd like to skip ahead to the code, please refer to the [SDK Example tutorial](/api-integration/basic-api-single-step/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: ```typescript 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: ```typescript 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. ](/api-integration/terminology#asset-token) Here is the sample code: ```typescript 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](/api-integration/basic-api-single-step/api-reference/create-transaction-swap#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. ```typescript 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:** ```typescript // 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: ```typescript 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: ```typescript // 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. ```typescript 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: ```typescript 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
# API Reference OpenAPI Json Schema file {% file src="/files/EsrXvOjOsHXzDUhQUtOC" %} # Get Blockchains & Tokens Get all supported blockchains, tokens and swappers meta data ## Get Full Metadata API This service gathers all the essential data needed for a swap's UI, including list of all [blockchains](/api-integration/terminology#blockchain), [tokens](/api-integration/terminology#asset-token) and [protocols](/api-integration/terminology#swapper) (DEXes & Bridges) metadata. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript // basic usage const meta = await rango.meta() ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```javascript const response = await axios.get('https://api.rango.exchange/basic/meta', { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/meta?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript // sample for filtering response const meta = await rango.meta({ blockchains: ['ETH', 'POLYGON'], blockchainsExclude: false, swappers: ['Across', 'OneInchEth'], swappersExclude: false, swappersGroups: ['Across', '1Inch'], swappersGroupsExclude: false, transactionTypes: ['EVM'], transactionTypesExclude: false, excludeNonPopulars: false }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```javascript const response = await axios.get('https://api.rango.exchange/basic/meta', { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32', 'blockchains': 'ETH,POLYGON', 'blockchainsExclude': false, 'swappers': 'Across,OneInchEth', 'swappersExclude': false, 'swapperGroups': 'Across,1Inch', 'swappersGroupsExclude': false, 'transactionTypes': 'EVM', 'transactionTypesExclude': false, 'excludeNonPopulars': false } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/meta?apiKey=c6381a79-2817-4602-83bf-6a641a409e32&blockchains=ETH,POLYGON&blockchainsExclude=false&swappers=Across,OneInchEth&swappersExclude=false&swapperGroups=Across,1Inch&swappersGroupsExclude=false&transactionTypes=EVM&transactionTypesExclude=false&excludeNonPopulars=false' ``` {% endtab %} {% endtabs %} {% embed url="" %} GET Metadata Swagger {% endembed %} {% hint style="info" %} **Why is it recommended to obtain the list of supported blockchains from Rango API?** * For working with other API methods like `quote` or `swap`, you need to have identifier (name) of each blockchain. You could hard code blockchain names if you want to have limited chains support or get them dynamically via the API. (You could store a map of each blockchain `chainId` to Rango `name` if required.) * Because of different reasons like blockchains maintenance, Rango maintenance, DeFi protocols hacks, and etc, a blockchain could be disabled in Rango. You could check which blockchains are enabled now using `enabled` flag for each blockchain in meta response. {% endhint %} {% hint style="info" %} **When is it required to obtain the list of supported tokens from Rango API?** Even if dApp has its own list of tokens and blockchains, it's still useful to get list of supported tokens by Rango: * To avoid unnecessary API calls when a token is not supported by Rango: For EVM and Solana blockchains, Rango supports custom tokens, so it's fine to pass tokens outside the list of Rango token list. However, for the other blockchains, we currently only support tokens that are on our existing token list (meta response). * For Cosmos-based blockchains, the token's symbol is required to retrieve a quote for each token. Thi will be addressed in a future update. {% endhint %} ### Metadata Request {% tabs %} {% tab title="API Definition" %} * **`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[^1] 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` * **`excludeSecondaries`** Boolean * Description: It indicates whether secondary tokens should be excluded from the response. By secondary tokens, we mean tokens that are imported from our secondary tokens lists. * Example: `false` * **`excludeNonPopulars`** Boolean * Description: It indicates whether non-popular tokens should be excluded from the response. By popular tokens, we mean native token and stable coins of each blockchain. * 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. * Example: `true` {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type MetaRequest = { blockchains?: string[] blockchainsExclude?: boolean swappers?: string[] swappersExclude?: boolean swappersGroups?: string[] swappersGroupsExclude?: boolean transactionTypes?: TransactionType[] transactionTypesExclude?: boolean excludeSecondaries?: boolean excludeNonPopulars?: boolean ignoreSupportedSwappers?: boolean enableCentralizedSwappers?: boolean } export enum TransactionType { EVM = 'EVM', TRANSFER = 'TRANSFER', COSMOS = 'COSMOS', SOLANA = 'SOLANA', TRON = 'TRON', STARKNET = 'STARKNET', TON = 'TON', } ``` {% endtab %} {% endtabs %} ### Metadata Response {% tabs %} {% tab title="API Definition" %} * **`blockchains`** * Description: List of all supported [blockchains](/api-integration/terminology#blockchain) * **`tokens`** * List of all [tokens](/api-integration/terminology#asset-token) * **`swappers`** * List of all supported [protocols](/api-integration/terminology#swapper) (DEXes & Bridges) {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type MetaResponse = { blockchains: BlockchainMeta[] tokens: Token[] swappers: SwapperMeta[] } export type BlockchainMeta = | EvmBlockchainMeta | CosmosBlockchainMeta | TransferBlockchainMeta | SolanaBlockchainMeta | StarkNetBlockchainMeta | TronBlockchainMeta | TonBlockchainMeta export type SwapperMeta = { id: string title: string logo: string swapperGroup: string types: SwapperType[] enabled: boolean } 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[] } ``` {% endtab %} {% tab title="Sample Response" %} ```json { "tokens": [ { "blockchain": "ETH", "symbol": "USDT", "name": "USDT", "isPopular": true, "chainId": "1", "address": "0xdac17f958d2ee523a2206206994597c13d831ec7", "decimals": 6, "image": "https://rango.vip/i/r3Oex6", "blockchainImage": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/ETH/icon.svg", "usdPrice": 1.001, "supportedSwappers": [ "ThorChain", "Arbitrum Bridge", "Hyphen" ] } ], "blockchains": [ { "name": "ETH", "defaultDecimals": 18, "addressPatterns": [ "^(0x)[0-9A-Fa-f]{40}$" ], "feeAssets": [ { "blockchain": "ETH", "symbol": "ETH", "address": null } ], "type": "EVM", "chainId": "0x1", "logo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/ETH/icon.svg", "displayName": "Ethereum", "shortName": "ETH", "sort": 0, "color": "#ecf0f1", "enabled": true, "info": { "infoType": "EvmMetaInfo", "chainName": "Ethereum Mainnet", "nativeCurrency": { "name": "ETH", "symbol": "ETH", "decimals": 18 }, "rpcUrls": [ "https://rpc.ankr.com/eth" ], "blockExplorerUrls": [ "https://etherscan.io" ], "addressUrl": "https://etherscan.io/address/{wallet}", "transactionUrl": "https://etherscan.io/tx/{txHash}", "enableGasV2": true } } ], "swappers": [ { "id": "MDexHeco", "title": "MDex", "logo": "https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/MDex/icon.svg", "swapperGroup": "MDex", "types": [ "DEX" ], "enabled": true } ] } ``` {% endtab %} {% endtabs %} ## Get Specific Part of Metadata If you only want to load a specific part of metadata rather than full metadata, i.e. only blockchains data, tokens list or supported protocols, you can use the following methods/endpoints: ### Get List of Blockchains API {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const chains = await rango.chains() ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```javascript const response = await axios.get('https://api.rango.exchange/basic/meta/blockchains', { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/meta/blockchains?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} GET Blockchains Swagger {% endembed %} ### Get List of Swappers API {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const swappers = await rango.swappers() ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```javascript const response = await axios.get('https://api.rango.exchange/basic/meta/swappers', { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/meta/swappers?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} GET Swappers Swagger {% endembed %} ### Get List of Cross-Chain Messaging Protocols API {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const protocols = await rango.messagingProtocols() ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```javascript const response = await axios.get('https://api.rango.exchange/basic/meta/messaging-protocols', { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/meta/messaging-protocols?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} GET Messaging Protocols Swagger {% endembed %} [^1]: # Get Quote Get the best single-step route for swapping X to Y ## Quote API Using the quote method, you can get a preview of the best route for this cross-chain swap. It goes through all the possible DEXs, bridges and aggregators to find the best possible single-step route based on user experience, fee amount, and swap output. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const quote = await rango.quote({ from: {"blockchain": "BSC", "address": null}, to: {"blockchain": "AVAX_CCHAIN", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118"}, amount: "100000000000000000", // 0.1 BSC.BNB slippage: 1.5 }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```javascript const response = await axios.get('https://api.rango.exchange/basic/quote', { params: { 'from': 'BSC.BNB', 'to': 'AVAX_CCHAIN--0xc7198437980c041c805a1edcba50c1ce5db95118', 'amount': '100000000000000000', 'slippage': 1.5, 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/quote?from=BSC.BNB&to=AVAX_CCHAIN--0xc7198437980c041c805a1edcba50c1ce5db95118&slippage=1.5&amount=100000000000000000&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} Get Quote Swagger Link {% endembed %} ### Quote Request {% tabs %} {% tab title="API Definition" %} * **`from`** \* String * Description: The source [asset](/api-integration/terminology#asset-token) * Example: `BSC.BNB` * **`to`** \* String * Description: The destination [asset](/api-integration/terminology#asset-token) * Example: `AVAX_CCHAIN--0xc7198437980c041c805a1edcba50c1ce5db95118` * **`amount`** \* String * Description: The machine readable amount of [asset](/api-integration/terminology#asset-token) X that is going to be swapped * Example: `100000000000000000000` for 100 Fantom.FTM * **`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. * Example: `1.5` means 1.5% slippage * **`referrerCode`** String * Description: [Referrer code](/api-integration/terminology#affiliate-ref-referrer-code) * **`referrerFee`** String * Description: Referrer fee in percent * **`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) * **`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 contracts. * **`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 * Description: The message that you want to pass to your contract on the destination chain. * **`messagingProtocols`** String * Description: Message protocols which will be used to relay message in a cross-chain swap. An empty list means no filter is required. * **`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. {% endtab %} {% tab title="SDK Models (Typescript)" %} 
export type QuoteRequest = {
  from: RequestedAsset
  to: RequestedAsset
  amount: string
  slippage?: number
  swappers?: string[]
  swappersExclude?: boolean
  swapperGroups?: string[]
  swappersGroupsExclude?: boolean
  messagingProtocols?: string[]
  sourceContract?: string
  destinationContract?: string
  imMessage?: string
  contractCall?: boolean
  enableCentralizedSwappers?: boolean
  avoidNativeFee?: boolean
  referrerCode?: string
  referrerFee?: number
}

export type RequestedAsset = {
  blockchain: string
  address: string | null
  symbol?: string
}
{% endtab %} {% endtabs %} ### Quote Response {% tabs %} {% tab title="API Definition" %} * **`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. * **`route`** * Description: The quote route object {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type QuoteResponse = { requestId: string resultType: RoutingResultType route: QuoteSimulationResult | null error: string | null errorCode: number | null traceId: number | 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 AmountRestriction = { min: string | null max: string | null type: AmountRestrictionType } export type SwapFee = { name: string token: Token expenseType: ExpenseType amount: string meta: EVMFeeMeta | null } export type ExpenseType = | 'FROM_SOURCE_WALLET' | 'DECREASE_FROM_OUTPUT' | 'FROM_DESTINATION_WALLET' 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 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[] } ``` {% endtab %} {% tab title="Sample Response" %} ```json { "requestId": "50365411-295c-4431-8ade-d848f84c46f2", "resultType": "OK", "route": { "outputAmount": "50348915", "outputAmountMin": "49593681", "outputAmountUsd": 50.44961283, "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": 513.49, "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.002, "supportedSwappers": [] }, "fee": [ { "token": { "blockchain": "BSC", "symbol": "BNB", "name": "BNB", "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": 513.49, "supportedSwappers": [ "ThorChain", "XO Swap", "ParaSwap Bsc", "OneInchBsc", "SWFT", "BSCPancakeV3", "Bridgers", "Satellite", "PancakeSwapBsc", "ThorChainStreamingSwap" ] }, "expenseType": "DECREASE_FROM_OUTPUT", "amount": "299550000000000", "name": "Swapper Fee" }, { "token": { "blockchain": "BSC", "symbol": "BNB", "name": "BNB", "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": 513.49, "supportedSwappers": [ "ThorChain", "XO Swap", "ParaSwap Bsc", "OneInchBsc", "SWFT", "BSCPancakeV3", "Bridgers", "Satellite", "PancakeSwapBsc", "ThorChainStreamingSwap" ] }, "expenseType": "DECREASE_FROM_OUTPUT", "amount": "150000000000000", "name": "Rango Fee" }, { "token": { "blockchain": "BSC", "symbol": "BNB", "name": "BNB", "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": 513.49, "supportedSwappers": [ "ThorChain", "XO Swap", "ParaSwap Bsc", "OneInchBsc", "SWFT", "BSCPancakeV3", "Bridgers", "Satellite", "PancakeSwapBsc", "ThorChainStreamingSwap" ] }, "expenseType": "FROM_SOURCE_WALLET", "amount": "168748800000000", "name": "Network Fee", "meta": { "type": "EvmNetworkFeeMeta", "gasLimit": "153408", "gasPrice": "1100000000" } } ], "feeUsd": 0.086650821312, "amountRestriction": { "min": "38760000000000000", "max": "3893361000000000000", "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": 513.49, "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.002, "supportedSwappers": [] }, "inputAmount": "100000000000000000", "expectedOutput": "50348915", "estimatedTimeInSeconds": 360 } ] }, "error": null, "errorCode": null, "traceId": null } ``` {% endtab %} {% endtabs %} #### Limits (Amount Restriction) The `route.amountRestriction` field indicates the minimum and maximum possible input amount for this quote. `EXCLUSIVE` field means that `min{ // other fields ..., "amountRestriction": { "min": "40666469010361176", "max": "67777448350601960000000", "type": "INCLUSIVE" }, } #### Fee (Expense Type) These are two possible types of fees (`expenseType` field in the `route.fee` array). * `FROM_SOURCE_WALLET` * Description: The gas fee. This fee should be available in the user's wallet for the swap to succeed. * `DECREASE_FROM_OUTPUT` * Some hidden fees in swapper which will be reduced from the user's output amount automatically. This fee is already calculated in the estimated output. And this is a sample fee object you get through the `quote/swap` endpoint. You could show the user `feeUsd` amount as the total fee he/she should pay for this route. 
{
  // other fields ...,
  "feeUsd": 0.2527750142059618,
  "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": 585.3830924582086,
          "supportedSwappers": [
            "ThorChain"
          ]
        },
        "expenseType": "FROM_SOURCE_WALLET",
        "amount": "784565100000000",
        "name": "Network Fee",
        "meta": {
          "type": "EvmNetworkFeeMeta",
          "gasLimit": "713241",
          "gasPrice": "1100000000"
        }
      },
  ],
}
# Create Transaction (Swap) Get final quote and create the transaction ## Swap API It's similar to the quote method but gives the actual transaction data in response besides the route. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript 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, }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```javascript 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' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash 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' ``` {% endtab %} {% endtabs %} {% embed url="" %} Swap Swagger Link {% endembed %} ## Swap Request {% tabs %} {% tab title="API Definition" %} * **`from`** \* String * Description: The [asset](/api-integration/terminology#asset-token) X that user likes to swap * Example: `BSC.BNB` * **`to`** \* String * Description: The [asset](/api-integration/terminology#asset-token) Y that user wants to swap X into that * Example: `AVAX_CCHAIN--0xc7198437980c041c805a1edcba50c1ce5db95118` * **`amount`** \* String * Description: The machine-readable amount of [asset](/api-integration/terminology#asset-token) X that is going to be swapped * 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) * **Caution:** By default, Rango does not charge a fee on your behalf unless you set`referrerAddress` 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 [Basic API Monetization](/api-integration/basic-api-single-step/monetization) for more details on this. * **`referrerCode`** String * Description: [Referrer code](/api-integration/terminology#affiliate-ref-referrer-code) * **`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 * 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 [message passing](/api-integration/basic-api-single-step/api-reference/message-passing) document for more details. * **`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. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript 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 } ``` {% endtab %} {% endtabs %} ### Swap Response {% tabs %} {% tab title="API Definition" %} * **`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. * Example: [Sample Basic Transactions](/api-integration/basic-api-single-step/sample-transactions) {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript 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[] } ``` {% endtab %} {% tab title="Sample Response" %} ```json { "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 } } ``` {% endtab %} {% endtabs %} # Check Transaction Status Track Status of Transaction ## Check Status API After that user signed a transaction on his/her wallet, you should call this endpoint periodically to see what's the status of that transaction. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const response = await rango.status({ requestId: 'b3a12c6d-86b8-4c21-97e4-809151dd4036', txId: '0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5', }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```javascript 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' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} {% code overflow="wrap" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/status?requestId=b3a12c6d-86b8-4c21-97e4-809151dd4036&txId=0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endcode %} {% endtab %} {% endtabs %} {% embed url="" %} Check Transaction Status Swagger {% endembed %} {% hint style="info" %} * This endpoint is not suitable for checking approval transaction and it is only for the original transaction. For checking approval transaction status, please check [this section](#3.-check-approval-status). * In on-chain transactions, you could also check transaction status by checking transaction receipt (via RPC) if you prefer. But in cross-chain swaps (e.g. bridges), you could use this method to make sure outbound transaction (transaction on destination chain) succeeds without any problem. {% endhint %} ### Check Transaction Status Request {% tabs %} {% tab title="API Definition" %} * **`requestId`** \* String * Description: The unique ID which is generated in the swap endpoint. * Example: `b3a12c6d-86b8-4c21-97e4-809151dd4036` * **`txId`** \* String * Description: Transaction hash that wallet returned. * Example: `0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5` {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type StatusRequest = { requestId: string txId: string } ``` {% endtab %} {% endtabs %} ### Check Transaction Status Response {% tabs %} {% tab title="API Definition" %} * **`status`** * Description: Status of the transaction, while the status is `running` (or `null`), the client should retry until it turns into `success` or `failed`. * **`error`** * Description: A message in case of failure, that could be shown to the user. * **`output`** * Description: The output asset and amount, could be different from the destination asset in case of failures or refunds. \ In the context of a cross-chain swap, the process combines up to three transactions (\[dex]+bridge+\[dex]) into a single transaction. Consequently, several scenarios could arise if a user ends up receiving a token that differs from their initial expectation. These are possible cases for `output.type`: * `DESIRED_OUTPUT` When your transaction status is marked as successful, it indicates that the bridge or swap process has been successfully completed, and the user has received the intended `DESIRED_OUTPUT` token as part of the output. * `REVERTED_TO_INPUT` If user transaction reverted on first dex step, transaction will be reverted on the blockchain and user will receive back the input token. * `MIDDLE_ASSET_IN_SRC` If the dex step succeeded but the bridge step failed because of slippage or lack of liquidity or ... * `MIDDLE_ASSET_IN_DEST` If the \[dex]+bridge step succeeded but, the last dex step failed because of slippage. * **`explorerUrl`** * Description: List of explorer URLs for the transactions of this swap. Including inbound transaction link, outbound transaction link and etc. * **`diagnosisUrl`** * Description: If a transaction becomes stuck within a bridge, requiring user intervention to initiate a refund through the bridge's user interface, we offer a diagnosis URL. This URL directs the user to a guide detailing the steps they need to take in order to successfully refund their tokens from the route underlying protocol. * Example: * **`bridgeData`** * Description: Status of bridge. At the moment, this field is only filled when we have a bridge/swap transaction between two EVM chains. (e.g. from Polygon to Avax) It contains both data of inbound and outbound transactions/tokens. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type StatusResponse = { status: TransactionStatus | null error: string | null output: StatusOutput | null explorerUrl: SwapExplorerUrl[] | null diagnosisUrl: string | null bridgeData: BridgeData | null } export enum TransactionStatus { FAILED = 'failed', RUNNING = 'running', SUCCESS = 'success', } export type StatusOutput = { amount: string receivedToken: Token type: | 'REVERTED_TO_INPUT' | 'MIDDLE_ASSET_IN_SRC' | 'MIDDLE_ASSET_IN_DEST' | 'DESIRED_OUTPUT' } 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[] } export type BridgeData = { srcChainId: number srcTxHash: string | null srcToken: string | null srcTokenAmt: string srcTokenDecimals: number srcTokenPrice: string | null destChainId: number destTxHash: string | null destToken: string | null destTokenAmt: string | null destTokenDecimals: number destTokenPrice: string | null } ``` {% endtab %} {% tab title="Sample Response" %} ```json { "status": "success", "error": null, "diagnosisUrl": null, "explorerUrl": [ { "url": "https://arbiscan.io/tx/0xf25f22c8dec8512c179c723e9d4c494ac35b991f6f4a9b0c10e63ac94d059f81", "description": "Inbound" }, { "url": "https://basescan.org/tx/0x676d7120d941588340a7ef76287cc9d3ad846be0cdcc30609472a10b30c171b2", "description": "Outbound" } ], "output": { "amount": "50914691310462592", "receivedToken": { "blockchain": "BASE", "symbol": "ETH", "name": null, "isPopular": false, "chainId": "8453", "address": null, "decimals": 18, "image": "https://rango.vip/tokens/ALL/ETH.png", "blockchainImage": null, "usdPrice": null, "supportedSwappers": [ ] }, "type": "DESIRED_OUTPUT" }, "bridgeData": { "srcChainId": 42161, "srcTxHash": "0xf25f22c8dec8512c179c723e9d4c494ac35b991f6f4a9b0c10e63ac94d059f81", "srcToken": null, "srcTokenAmt": "51000000000000000", "srcTokenDecimals": 18, "srcTokenPrice": "2609.9", "destChainId": 8453, "destTxHash": "0x676d7120d941588340a7ef76287cc9d3ad846be0cdcc30609472a10b30c171b2", "destToken": null, "destTokenDecimals": 18, "destTokenAmt": "50914691310462592", "destTokenPrice": "2609.9" } } ``` {% endtab %} {% endtabs %} # Check Approve Transaction Status Check status of approve transaction ## Check Approval API In `EVM`, `TRON` and `STARKNET` blockchains where [swap](/api-integration/basic-api-single-step/api-reference/create-transaction-swap#swap-response) returns a non-null value for approve transaction (e.g. `approveData` and `approveTo` fields in case of the `EVM`), you need to use these values to prepare the approve transaction for the user and call `isApproved` periodically to see if the approval transaction is completed. After a successful check, you should ask the user to sign the main transaction. {% hint style="warning" %} **Caution:** 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 route. {% endhint %} {% hint style="info" %} For checking approval transaction status, you could check it directly from the RPC endpoint if you prefer and skip calling Rango API for this purpose. {% endhint %} {% tabs %} {% tab title="Typescript‌ (SDK)" %} ```typescript const transaction = await rango.isApproved( requestId = 'e4b0d1e7-ae1f-4aed-ab91-f1ea3ba9383b', txId = '0xd7a18c6e2f9afe5aefd1b5969f753513f01c6670a4fc57a2d1349ad539ae2f7f' ) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```javascript 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' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} {% code overflow="wrap" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/is-approved?requestId=e4b0d1e7-ae1f-4aed-ab91-f1ea3ba9383b&txId=0xd7a18c6e2f9afe5aefd1b5969f753513f01c6670a4fc57a2d1349ad539ae2f7f&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endcode %} {% endtab %} {% endtabs %} {% embed url="" %} Check Approval Transaction Status Swagger {% endembed %} You could stop checking is-approved method if: 1. Approval transaction succeeded. => `isApproved === true` 2. Approval transaction failed. => `!isApproved && txStatus === 'failed'` 3. Approval transaction succeeded but `currentApprovedAmount` is still less than `requiredApprovedAmount` (e.g. user changed transaction data in wallet and enter another approve amount in MetaMask instead of default approve amount proposed by Rango API) => `!isApproved && txStatus === 'success'` ### Check Approval Request {% tabs %} {% tab title="API Definition" %} * **`requestId`** \* String * Description: The unique ID which is generated in the best route endpoint. * Example: `e4b0d1e7-ae1f-4aed-ab91-f1ea3ba9383b` * **`txId`** \* String * Description: Transaction hash that wallet returned for approve transaction. * Example: `0xd7a18c6e2f9afe5aefd1b5969f753513f01c6670a4fc57a2d1349ad539ae2f7f` {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript function isApproved(requestId: string, txId?: string) ``` {% endtab %} {% endtabs %} ### Check Approval Response {% tabs %} {% tab title="API Definition" %} * **`isApproved`** * Description: A flag which indicates that the approve tx is done or not. * **`txStatus`** * Description: Status of approve transaction in blockchain (possible values are `success`, `running` and `failed`) If `isArppoved` is false and `txStatus` is failed, it means that approve transaction is failed in the blockchain. * **`requiredApprovedAmount`** * Description: Required amount to be approved by user * **`currentApprovedAmount`** * Description: Current approved amount by user {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type CheckApprovalResponse = { isApproved: boolean txStatus: TransactionStatus | null requiredApprovedAmount: string | null currentApprovedAmount: string | null } export enum TransactionStatus { FAILED = 'failed', RUNNING = 'running', SUCCESS = 'success', } ``` {% endtab %} {% tab title="Sample Response" %} ```json { "isApproved": true, "txStatus": "success", "currentApprovedAmount": "0.903658", "requiredApprovedAmount": "0.903658" } ``` {% endtab %} {% endtabs %} # Get Address Assets & Balances Get details of a list of wallet addresses, including their explorer Url & balance ## Get Balance API You can use this API to retrieve a list of all tokens and their respective balances associated with a user's wallet address on the desired blockchain {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const walletDetails = await rango.balance({ blockchain: "BSC", address: "0xeb2629a2734e272bcc07bda959863f316f4bd4cf" }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.get('https://api.rango.exchange/basic/balance', { params: { 'blockchain': 'BSC', 'address': '0xeb2629a2734e272bcc07bda959863f316f4bd4cf', 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} {% code overflow="wrap" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/balance?blockchain=BSC&address=0xeb2629a2734e272bcc07bda959863f316f4bd4cf&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endcode %} {% endtab %} {% endtabs %} {% embed url="" %} Balance Swagger {% endembed %} {% hint style="info" %} Note that this endpoint is slow since it queries for all tokens an address is holding and balance of each one. We recommend to use [single token balance](/api-integration/basic-api-single-step/api-reference/get-token-balance) endpoint whenever possible. {% endhint %} ### Balance Request {% tabs %} {% tab title="API Definition" %} * **`blockchain`**\* String * Description: The desired blockchain. * **`address`**\* String * Description: User wallet address for the desired blockchain. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type WalletAddress = { blockchain: string address: string }; ``` {% endtab %} {% endtabs %} ### Balance Response {% tabs %} {% tab title="API Definition" %} * **`wallets`** * Description: List of wallet assets {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type WalletDetailsResponse = { wallets: WalletDetail[] } export type WalletDetail = { failed: boolean blockChain: string address: string balances: AssetAndAmount[] | null explorerUrl: string } export type AssetAndAmount = { amount: Amount asset: Asset } export type Amount = { amount: string decimals: number } export type Asset = { blockchain: string address: string | null symbol: string } ``` {% endtab %} {% tab title="Sample Response" %} ```typescript { "wallets": [ { "blockChain": "BSC", "address": "0xeb2629a2734e272bcc07bda959863f316f4bd4cf", "failed": false, "explorerUrl": "https://bscscan.com/address/0xeb2629a2734e272bcc07bda959863f316f4bd4cf", "balances": [ { "asset": { "blockchain": "BSC", "symbol": "BNB", "address": null }, "amount": { "amount": "911814661733430075", "decimals": 18 } } ] } ] } ``` {% endtab %} {% endtabs %} # Get Token Balance Get details of a list of wallet addresses, including their explorer Url & balance ## Get Token Balance API This endpoint returns the balance of a specific token for the provided address. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const balance = await rango.tokenBalance({ walletAddress: "0x9F8cCdaFCc39F3c7D6EBf637c9151673CBc36b88", blockchain: "BSC", symbol: "BNB", address: null, }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.get('https://api.rango.exchange/basic/token-balance', { params: { 'walletAddress': '0x9F8cCdaFCc39F3c7D6EBf637c9151673CBc36b88', 'blockchain': 'BSC', 'symbol': 'BNB', 'address': null, 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} {% code overflow="wrap" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/token-balance?walletAddress=0x9F8cCdaFCc39F3c7D6EBf637c9151673CBc36b88&blockchain=BSC&symbol=BNB&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endcode %} {% endtab %} {% endtabs %} {% embed url="" %} Token Balance Swagger {% endembed %} ### Token Balance Request {% tabs %} {% tab title="API Definition" %} * **`blockchain`**\* String * Description: The blockchain which this token belongs to. * Example: `BSC` * **`symbol`**\* String * Description: The token symbol. * Example: `BNB` * **`address`** String * Description: Smart contract address of token, null for native tokens. * Example: `null` * **`walletAddress`**\* String * Description: User wallet address for the desired blockchain. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type TokenBalanceRequest = { blockchain: string symbol: string address: string | null walletAddress: string } ``` {% endtab %} {% endtabs %} ### Token Balance Response {% tabs %} {% tab title="API Definition" %} * **`balance`** * Description: balance amount * Example: `46077752529840023` * **`error`** * Description: Error message if there was any problem * **`errorCode`** * Description: Error code if there was any problem * **`traceId`** * Description: Trace id help Rango support to resolve the issue {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type TokenBalanceResponse = { balance: string | null error: string | null errorCode: number | null traceId: number | null } ``` {% endtab %} {% tab title="Sample Response" %} ```typescript { "balance": "46077752529840023", "error": null, "errorCode": null, "traceId": null } ``` {% endtab %} {% endtabs %} # Report Transaction Failure Report failures on signing or sending the transaction ## Report Failure API Use it when the user rejects the transaction in the wallet or the wallet fails to handle the transaction. Calling this endpoint is not required, but is useful for reporting and we recommend calling it. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript await rango.reportFailure({ requestId: '2823418f-9e18-4110-8d36-b569b0af025e' eventType: 'SEND_TX_FAILED', reason: 'Transaction is underpriced.' }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript 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' } } ); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request POST \ --url 'https://api.rango.exchange/basic/report-tx?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' \ --header 'content-type: application/json' \ --data ' { "requestId": "2823418f-9e18-4110-8d36-b569b0af025e", "eventType": "SEND_TX_FAILED", "reason": "Transaction is underpriced." } ' ``` {% endtab %} {% endtabs %} {% embed url="" %} Report TX Failure Swagger {% endembed %} {% hint style="info" %} It's an optional action and does not affect the flow of swap, but it can help us improve our API and also accurately measure failures rates of transactions for each dApp. {% endhint %} ### Report Failure Request {% tabs %} {% tab title="API Definition" %} * **`requestId`**\* String * Description: The unique ID which is generated in the best route endpoint. * **`eventType`**\* String * Description: Type of failure. * Possible values are: `FETCH_TX_FAILED`, `USER_REJECT`, `USER_CANCEL`, `CALL_WALLET_FAILED`, `SEND_TX_FAILED`, `CLIENT_UNEXPECTED_BEHAVIOUR`, `TX_EXPIRED`, `INSUFFICIENT_APPROVE` * **`reason`**\* String * Description: Failure reason * **`tags`** Object * Description: An optional dictionary of pre-defined tags. Current allowed tags are `wallet` and `errorCode`. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type ReportTransactionRequest = { requestId: string eventType: APIErrorCode reason?: string tags?: { wallet?: string; errorCode?: string } } export type APIErrorCode = | 'TX_FAIL' | 'TX_EXPIRED' | 'FETCH_TX_FAILED' | 'USER_REJECT' | 'USER_CANCEL' | 'USER_CANCELED_TX' | 'CALL_WALLET_FAILED' | 'SEND_TX_FAILED' | 'CALL_OR_SEND_FAILED' | 'TX_FAILED_IN_BLOCKCHAIN' | 'CLIENT_UNEXPECTED_BEHAVIOUR' | 'INSUFFICIENT_APPROVE' ``` {% endtab %} {% endtabs %} # Get Direct Tokens List of all tokens which can be swapped from a given token ## Connected Assets API This is an *experimental* endpoint that you could use to find which tokens can be swapped from a given token using one single step transaction. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const connectedAssets = await rango.connectedAssets({ from: { "blockchain": "ETH", "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.get('https://api.rango.exchange/basic/connected-assets', { params: { 'from': 'ETH--0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/connected-assets?from=ETH--0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} Connected Assets Swagger {% endembed %} {% hint style="warning" %} **Experimental API Warning** This experimental API provides a **rough estimate** of direct tokens available from each token. It is **not recommended** for general use unless you have a specific requirement that cannot be met with other methods. Typically, you can use the quote or swap methods directly without needing to check connected assets in advance. {% endhint %} ### Connected Assets Request {% tabs %} {% tab title="API Definition" %} * **`from`**\* String * Description: The [asset](/api-integration/terminology#asset-token) which is going to be swapped into other assets. * Example: `ETH--0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type ConnectedAssetsRequest = { from: RequestedAsset } export type RequestedAsset = { blockchain: string address: string | null symbol: string } ``` {% endtab %} {% endtabs %} ### Connected Assets Response Returns a list of blockchains + assets of that blockchain that is directly available. Note: If list of assets is empty, it means almost all tokens on this specific chain are accessible from the given token. {% tabs %} {% tab title="API Definition" %} * **`data`** * Description: List of all possible destination assets for the provided source asset. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type ConnectedAssetsResponse = { data: ConnectedAsset[] } export type ConnectedAsset = { blockchain: string assets: Asset[] } export type Asset = { blockchain: string address: string | null symbol: string } ``` {% endtab %} {% tab title="Sample Response" %} This response indicates that the asset in request is nearly swappable with all assets on the ETH and BSC blockchains, but it only has a direct route to certain specific tokens on BOBA or EVMOS. ```json { "data": [ { "blockchain": "ETH", "assets": [] }, { "blockchain": "BSC", "assets": [] }, { "blockchain": "BOBA", "assets": [ { "blockchain": "BOBA", "symbol": "USDC", "address": "0x66a2a913e447d6b4bf33efbec43aaef87890fbbc" } ] }, { "blockchain": "EVMOS", "assets": [ { "blockchain": "EVMOS", "symbol": "CEUSDC", "address": "0xe46910336479f254723710d57e7b683f3315b22b" } ] } ] } ``` {% endtab %} {% endtabs %} # Get Custom Token Get metadata of a custom token ## Custom Token API Provides token details for a user-specified token that is not included in Rango's official list. Currently supports blockchains based on Solana and EVM. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const tokenResponse = await rango.token({ "blockchain": "SOLANA", "address": "3yoMkf3X6bDxjks6YaWwNk4SAbuaysLg1a4BjQKToQAA" }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.get('https://api.rango.exchange/basic/meta/custom-token', { params: { 'blockchain': 'SOLANA', 'address': '3yoMkf3X6bDxjks6YaWwNk4SAbuaysLg1a4BjQKToQAA', 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/meta/custom-token?blockchain=SOLANA&address=3yoMkf3X6bDxjks6YaWwNk4SAbuaysLg1a4BjQKToQAA&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} Custom Token Swagger {% endembed %} ### Custom Token Request {% tabs %} {% tab title="API Definition" %} * **`blockchain`**\* String * Description: The blockchain which the token belongs to. * Example: `SOLANA` * **`address`**\* String * Description: Smart contract address of the token. * Example: `3yoMkf3X6bDxjks6YaWwNk4SAbuaysLg1a4BjQKToQAA` {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type CustomTokenRequest = { blockchain: string address: string } ``` {% endtab %} {% endtabs %} ### Custom Token Response {% tabs %} {% tab title="API Definition" %} * **`token`** * Description: The token's metadata * **`error`** * Description: Error message if there was any problem * **`errorCode`** * Description: Error code if there was any problem * **`traceId`** * Description: Trace id help Rango support to resolve the issue {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type CustomTokenResponse = { token: Token error: string | null errorCode: number | null traceId: number | null } 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[] } ``` {% endtab %} {% tab title="Sample Response" %} ```json { "token": { "blockchain": "SOLANA", "symbol": "Brett", "name": "Brett", "isPopular": false, "chainId": "mainnet-beta", "address": "3yoMkf3X6bDxjks6YaWwNk4SAbuaysLg1a4BjQKToQAA", "decimals": 9, "image": "https://bafkreifi5rkzrqyze3cqoqt5xm6ullqpyh5g52ut46pmwva6cju2yyy3ay.ipfs.nftstorage.link", "blockchainImage": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/SOLANA/icon.svg", "usdPrice": 0.09683140474717515, "supportedSwappers": [] }, "error": null, "errorCode": null, "traceId": null } ``` {% endtab %} {% endtabs %} # Message Passing How to relay message in a cross-chain swap? 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. Here is a brief guide on what you need to do in terms of SDK usage and the smart contract side. ## SDK Usage You should specify `sourceContract`, `destinationContract` and `imMessage` arguments in both `quote` and `swap` methods if you want to pass a message from the source contract to the destination. {% tabs %} {% tab title="Quote Sample" %} ```typescript const quoteResponse = await rango.quote({ from: { "blockchain": "OPTIMISM", "symbol": "ETH", "address": null }, to: { "blockchain": "ARBITRUM", "symbol": "ETH", "address": null }, amount: "100000000000000000000", messagingProtocols: ['LAYER_ZERO'], sourceContract: "", destinationContract: "", imMessage: "0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000007E8A8b130272430008eCa062419ACD8B423d339D" }) ``` {% endtab %} {% tab title="Swap Sample" %} ```typescript const swapResponse = await rango.swap({ from: { "blockchain": "OPTIMISM", "symbol": "ETH", "address": null }, to: { "blockchain": "ARBITRUM", "symbol": "ETH", "address": null }, amount: "100000000000000000000", fromAddress: fromAddress, toAddress: fromAddress, disableEstimate: false, referrerAddress: null, referrerFee: null, slippage: '1.0', messagingProtocols: ['LAYER_ZERO'], sourceContract: "", destinationContract: "", imMessage: "0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000007E8A8b130272430008eCa062419ACD8B423d339D" }) if (!!swapResponse && !swapResponse.error && swapResponse.resultType === "OK" && swapResponse.tx?.type === TransactionType.EVM) { const evmTx = swapResponse.tx as EvmTransaction const {value, txData} = evmTx console.log({value, txData}) // pass value and txData to your own contract } ``` {% endtab %} {% endtabs %} {% hint style="info" %} You could also limit `messagingProtocols` used to a custom list like `['LAYER_ZERO']`. (Please note that as the message is relayed alongside with token in a single transaction if you limit messaging protocols to`LAYER_ZERO`, we use the same bridge for transferring tokens. {% endhint %} Make sure to check out [Message Passing](/smart-contracts/message-passing) in order to implement proper interface in your smart contracts to receive messages from Rango contracts. # Tutorial Basic API Tutorial # SDK Example Basic SDK Example for Integrating Rango Exchange ## Overview You could read this guide to understand the flow of integrating Rango-Basic-SDK. If you prefer to dive directly into the code and explore it there, you can use the links below. * [EVM Example](https://github.com/rango-exchange/rango-sdk/tree/master/examples/basic/node-evm) * [Solana Example](https://github.com/rango-exchange/rango-sdk/tree/master/examples/basic/node-solana) * [Tron Example](https://github.com/rango-exchange/rango-sdk/tree/master/examples/basic/node-tron) * [Starknet Example](https://github.com/rango-exchange/rango-sdk/tree/master/examples/basic/node-starknet) ## Install TS SDK If you decide not to use our TypeScript SDK and prefer integration in other programming languages, feel free to skip this step. To integrate Rango SDK inside your dApp or wallet, you need to install `rango-sdk-basic` using npm or yarn. ```bash npm install --save rango-sdk-basic # or yarn add rango-sdk-basic ``` Then you need to instantiate `RangoClient` and use it in the next steps. ```typescript import { RangoClient } from "rango-sdk-basic" const rango = new RangoClient(RANGO_API_KEY) ``` ## Get Tokens & Blockchains Data To get the list of available blockchains, tokens, and protocols (dex or bridge) supported by Rango, you could use the `meta` method like this: ```typescript const meta = await rango.meta() ``` ## Get Quote Using information retrieved from the meta, you could implement your own SwapBox including your blockchain and token selector. The next step is to show the preview of the best route possible when the user selects the source and the destination tokens. The *blockchain* and *symbol* names must be exactly what is fetched from Rango's Meta API. ```typescript // Converting 0.1 BSC BNB to AVAX_CCHAIN USDT.E const quote = await rango.quote({ from: { "blockchain": "BSC", "address": null }, to: { "blockchain": "AVAX_CCHAIN", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118" }, amount: "100000000000000000" }) ``` You could call this method periodically to get the updated route before the user confirms the swap. ## Creating Transaction Whenever the user decides to accept the quote and submit the swap, you should call the SDK swap method to get the latest route and transaction data needed to proceed. ```typescript // Swap 0.1 BSC BNB to AVAX_CCHAIN USDT.E const quote = await rango.swap({ from: { "blockchain": "BSC", "address": null }, to: { "blockchain": "AVAX_CCHAIN", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118" }, amount: "100000000000000000", fromAddress: "0xbe807dddb074639cd9fa61b47676c064fc50d62c", toAddress: "0xbe807dddb074639cd9fa61b47676c064fc50d62c", slippage: 1.5, disableEstimate: false, referrerAddress: null, // your dApp wallet address for referral referrerFee: null, // your dApp desired referral fee percent }) ``` The `route` field in response is similar to what you've seen in the quote section and the `tx` field section is the data of the transaction that needed to be passed to the proper wallet to be signed by the user. ## Tracking Swap Status After signing the transaction by the user and receiving transaction hash, you could periodically call Rango check-status API to track the transaction status. In Rango, each swap step could have 3 different states: `running`, `failed` and `success`. You only need to keep checking the status until you find out whether the transaction failed or succeeded. Here's a sample request for the check-status API, along with the corresponding response it receives: ```typescript const transaction = await rango.status({ requestId: "b3a12c6d-86b8-4c21-97e4-809151dd4036", txId: '0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5', }) ``` ## Complete Code Flow {% embed url="" %} {% code title="Node.JS Example" %} ```typescript // run `node --import=tsx index.ts` in the terminal import { RangoClient, TransactionStatus, TransactionType } from "rango-sdk-basic"; import { findToken } from './utils/meta.js' import { TransactionRequest, ethers } from "ethers"; import { setTimeout } from 'timers/promises' // setup wallet & RPC provider const privateKey = 'YOUR_PRIVATE_KEY'; const wallet = new ethers.Wallet(privateKey); const rpcProvider = new ethers.JsonRpcProvider('https://bsc-dataseed1.defibit.io'); const walletWithProvider = wallet.connect(rpcProvider); // initiate sdk using your api key const API_KEY = "c6381a79-2817-4602-83bf-6a641a409e32" const rango = new RangoClient(API_KEY) // some example tokens for test purpose const sourceBlockchain = "BSC" const sourceTokenAddress = "0x55d398326f99059ff775485246999027b3197955" const targetBlockchain = "BSC" const targetTokenAddress = null const amount = "10000000000000" // get quote const quoteRequest = { from: { blockchain: sourceBlockchain, address: sourceTokenAddress }, to: { blockchain: targetBlockchain, address: targetTokenAddress }, amount, slippage: 1.0, } const quote = await rango.quote(quoteRequest) const swapRequest = { ...quoteRequest, fromAddress: wallet.address, toAddress: wallet.address, } // create transaction const swap = await rango.swap(swapRequest) const tx = swap.tx if (!tx) { throw new Error(`Error creating the transaction ${swap.error}`) } if (tx.type === TransactionType.EVM) { if (tx.approveData && tx.approveTo) { // sign the approve transaction const approveTransaction: TransactionRequest = { from: tx.from, to: tx.approveTo, data: tx.approveData, maxFeePerGas: tx.maxFeePerGas, maxPriorityFeePerGas: tx.maxPriorityFeePerGas, gasPrice: tx.gasPrice, } const { hash } = await walletWithProvider.sendTransaction(approveTransaction); // wait for approval while (true) { await setTimeout(10_000) const { isApproved, currentApprovedAmount, requiredApprovedAmount, txStatus } = await rango.isApproved(swap.requestId, hash) if (isApproved) break else if (txStatus === TransactionStatus.FAILED) throw new Error('Approve transaction failed in blockchain') else if (txStatus === TransactionStatus.SUCCESS) throw new Error(`Insufficient approve, current amount: ${currentApprovedAmount}, required amount: ${requiredApprovedAmount}`) } } // signing the main transaction const transaction: TransactionRequest = { from: tx.from, to: tx.txTo, data: tx.txData, value: tx.value, gasLimit: tx.gasLimit, maxFeePerGas: tx.maxFeePerGas, maxPriorityFeePerGas: tx.maxPriorityFeePerGas, gasPrice: tx.gasPrice, } const { hash } = await walletWithProvider.sendTransaction(transaction); // track swap status while (true) { await setTimeout(10_000) const state = await rango.status({ requestId: swap.requestId, txId: hash }) const status = state.status if (status && [TransactionStatus.FAILED, TransactionStatus.SUCCESS].includes(status)) { break } } } ``` {% endcode %} # Monetization How to take fees from the users using Rango Basic API? ## How Rango affiliate system works? {% content-ref url="/pages/XLBy76udAgbv1sqg98A8" %} [Monetization](/technical/monetization) {% endcontent-ref %} ## How to set affiliate parameters? * The Single-step API provides two endpoints for getting a quote and creating transactions, [quote](/api-integration/basic-api-single-step/api-reference/get-quote) and [swap](/api-integration/basic-api-single-step/api-reference/create-transaction-swap) endpoints. * In the quote endpoint, you should include the `referrerFee` field, which represents the fee amount you want to charge the user as a percentage (1.12 means 1.12 percent). Note that the maximum amount fee you could charge the user is 3 percent. It is required to calculated quote fee correctly for the user. The default fee is 10 bps or 0.1 percent. * In the swap endpoint, you should pass both `referrerAddress` and `referrerFee` fields. The `referrerFee` is the same as the field in `quote` endpoint, and the `referrerAddress` is the wallet address which you wish to receive your collected fees. \ For the `referrerAddress`, you can use EVM, Starknet, or Osmosis wallet addresses depending on the route. While we also support fee charging on the Solana blockchain, this feature is not yet available for all dApps due to its complexity and is not ready for public use. Here is a sample code for setting affiliate fee parameters in [quote](/api-integration/basic-api-single-step/api-reference/get-quote) method: {% tabs %} {% tab title="Typescript" %} ```typescript const quote = await rango.quote({ from: {"blockchain": "BSC", "symbol": "BNB", "address": null}, to: {"blockchain": "AVAX_CCHAIN", "symbol": "USDT.E", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118"}, amount: "100000000000000000", // 0.1 BSC.BNB slippage: "1.0", referrerFee: "0.1" // charge users 0.1% fee for the input token }) ``` {% endtab %} {% tab title="cURL" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/quote?from=BSC.BNB&to=AVAX_CCHAIN.USDT.E--0xc7198437980c041c805a1edcba50c1ce5db95118&amount=100000000000000000&slippage=3&referrerFee=0.1&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} Here is a sample code for setting affiliate fee parameters in [swap](/api-integration/basic-api-single-step/api-reference/create-transaction-swap) method: {% tabs %} {% tab title="Typescript" %} 
const swap = await rango.swap({
    from: {"blockchain": "BSC", "symbol": "BNB", "address": null},
    to: {"blockchain": "AVAX_CCHAIN", "symbol": "USDT.E", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118"},
    amount: "100000000000000000" // 0.1 BSC.BNB
    slippage: "1.0",
    fromAddress: "0xeb2629a2734e272bcc07bda959863f316f4bd4cf",
    toAddress: "0xeb2629a2734e272bcc07bda959863f316f4bd4cf",
    disableEstimate: true,
    referrerFee: "0.1",
    referredAddress: "0x7g44bb1763eebead07cf8815a62fcd7b30311fb1"
})
{% endtab %} {% tab title="cURL" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/basic/swap?from=BSC.BNB&to=AVAX_CCHAIN.USDT.E--0xc7198437980c041c805a1edcba50c1ce5db95118&amount=100000000000000000&slippage=3&fromAddress=0x9F8cCdaFCc39F3c7D6EBf637c9151673CBc36b88&toAddress=0x9F8cCdaFCc39F3c7D6EBf637c9151673CBc36b88&referrerFee=0.1&referrerAddress=0x7g44bb1763eebead07cf8815a62fcd7b30311fb1&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} # Sample Transactions Sample transactions for all types of transactions in basic API ## Overview Here are some samples of the transaction object that is created in [swap](/api-integration/basic-api-single-step/api-reference/create-transaction-swap) method. Rango currently returns 6 different types of transactions based on the blockchain that the transaction is happening on. This includes: * **EVM**: For all EVM-based blockchains, including Ethereum, Polygon, Avalanche, etc. * **COSMOS**: For all the cosmos-based networks, including the Cosmos itself, Osmosis, Akash, Thorchain, Maya and etc. * **TRANSFER**: For UTXO blockchains, including Bitcoin, Litecoin, Doge, etc. * **SOLANA:** For Solana transactions. * **TRON:** For Tron Transactions. * **STARKNET:** For Starknet transactions. * **SUI:** For SUI transactions. * **XRPL:** For XRPL transactions. * **STELLAR**: For Stellar transactions Let's see some examples here. ## EVM Sample Transaction: [(Test)](https://api.rango.exchange/basic/swap?from=POLYGON.MATIC\&to=OPTIMISM.ETH\&amount=1000000000000000000000\&slippage=8\&fromAddress=0x9F8cCdaFCc39F3c7D6EBf637c9151673CBc36b88\&toAddress=0x6f33bb1763eebead07cf8815a62fcd7b30311fa3\&disableEstimate=true\&apiKey=c6381a79-2817-4602-83bf-6a641a409e32) Here is the structure of an EVM transaction in the code below. If the user does not have a sufficient approval amount for the transaction, the data for the approval transaction will be included in the `approveData` and `approveTo` fields. In this case, the user needs to sign the approval transaction first, ensure he has enough approval, and then signs the main transaction. However, if the `approveData` and `approveTo` fields are null, it indicates that the user already has enough approval for this quote and can directly sign the main transaction. {% hint style="info" %} For the gas price of the transaction, if the blockchain supports the new versions of gas price, such as `maxPriorityFeePerGas` and `maxFeePerGas`, these fields will be populated. However, for blockchains that have not yet updated their gas model, the gas price will be set in the `gasPrice` field as before. You can check the list of all chains that support the new gas price versions in the `meta` or `blockchains` methods. (There is an `enableGasV2` field in the response body, included for each blockchain.) {% endhint %} ```json "tx": { // This field equals to EVM for all EVM Transactions "type": "EVM", // The blockchain that this transaction is going to run in "blockChain": { "name": "POLYGON", "defaultDecimals": 18, "addressPatterns": [ "^(0x)[0-9A-Fa-f]{40}$" ], "feeAssets": [ { "blockchain": "POLYGON", "symbol": "MATIC", "address": null } ], "type": "EVM", "chainId": "137" }, // The source wallet address, can be null "from": "0xeb2629a2734e272bcc07bda959863f316f4bd4cf", // Address of dex/bridge smart contract that is going to be called // It's usually rango contract address "txTo": "0x69460570c93f9DE5E2edbC3052bf10125f0Ca22d", // Address of source token erc20 contract for increasing approve amount "approveTo": null, // The data of approve transaction (null value means no approve needed) "approveData": null, // The data of main transaction, it can be null in case of native token transfer "txData": "0x0b320d9500000000000000000000000000000000000000000000000000000000000000000000000000000000000000006626c47c00f1d87902fc13eecfac3ed06d5e8d8a00000000000000000000000000000000000000000000000566fb0f266083987400000000000000000000000000000000000000000000000004cc4f07028c678c0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000034d8edb091aed6929f535b0f06407964e2b935cc000000000000000000000000000000000000000000000000000000000000003800000000000000000000000000000000000000000000000000000181a0615b7d0000000000000000000000000000000000000000000000000000000000007917000000000000000000000000000000000000000000000000054da24e2a77c01e000000000000000000000000000000000000000000000000000000000000034000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000f491e7b69e4244ad4002bc14e878a34207e38c29000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000e47ff36ab50000000000000000000000000000000000000000000000078bed27ba3317dd2a00000000000000000000000000000000000000000000000000000000000000800000000000000000000000002a7813412b8da8d18ce56fe763b9eb264d8e28a80000000000000000000000000000000000000000000000000000000062b871de000000000000000000000000000000000000000000000000000000000000000200000000000000000000000021be370d5312f44cb42ce377bc9b8a0cef1a4c830000000000000000000000006626c47c00f1d87902fc13eecfac3ed06d5e8d8a000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000038000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010ed43c718714eb63d5aa57b78b54704e256024e0000000000000000000000004691937a7508860f876c9c0a2a617e7d9e945d4b000000000000000000000000bb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c00000000000000000000000000000000000000000000000001af7aa59c0e923100000000000000000000000000000000000000000000000000000000000001c00000000000000000000000000000000000000000000000000000000062b875630000000000000000000000000000000000000000000000000000000000000001000000000000000000000000eb2629a2734e272bcc07bda959863f316f4bd4cf0000000000000000000000002702d89c1c8658b49c45dd460deebcc45faec03c00000000000000000000000000000000000000000000000000000000000002200000000000000000000000001f5aaeedaa649712ccca0af8b3af0a4721c58cd2000000000000000000000000cb2a1486bcec00242b8e1934d2cb6a8075da18d900000000000000000000000000000000000000000000000000000000000000020000000000000000000000004691937a7508860f876c9c0a2a617e7d9e945d4b000000000000000000000000bb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000010000000000000000000000007e8a8b130272430008eca062419acd8b423d339d", // The amount of transaction in case of native token transfer "value": "0x57115007b8d87c01e", // The suggested gas limit for this transaction "gasLimit": "0x9eb10", // The suggested gas price for this transaction "gasPrice": null, // e.g. 3308471992 // Recommended max priority fee per gas for this transaction // Used only for blockchains with enableGasV2 = true (in meta endpoint) "maxPriorityFeePerGas": "46350100970", // Suggested max fee per gas for this transaction (max value for BaseGasPrice + PriorityGasPrice) // Used only for blockchains with enableGasV2 = true (in meta endpoint) "maxFeePerGas": "46350100971" } ``` ## COSMOS Sample Transaction: For Cosmos based blockchains, we have two type of transactions based on `signType` field: `AMINO` and `DIRECT`. ### Cosmos Amino Sample Transaction: [(Test)](https://api.rango.exchange/basic/swap?from=OSMOSIS.OSMO\&to=OSMOSIS.ATOM--ibc%2F27394fb092d2eccd56123c74f36e4c1f926001ceada9ca97ea622b25f41e5eb2\&amount=1000000\&slippage=8\&fromAddress=osmo1unf2rcytjxfpz8x8ar63h4qeftadptg5t0nqcl\&toAddress=osmo1unf2rcytjxfpz8x8ar63h4qeftadptg5t0nqcl\&disableEstimate=true\&apiKey=c6381a79-2817-4602-83bf-6a641a409e32) 
"tx": {
  // This field equals to COSMOS for all COSMOS Transactions
  "type": "COSMOS",

  // Source wallet address for this transaction
  "fromWalletAddress": "osmo1unf2rcytjxfpz8x8ar63h4qeftadptg5t0nqcl",

  // The blockchain that this transaction is going to run in
  "blockChain": "OSMOSIS",

  // A real cosmos message, most fields of this object should be directly passed
  // to wallet for signing by user, the important part is msgs field that contains
  // all the cosmos actions that should be performed.
  "data": {
      "chainId": "osmosis-1",
      "account_number": 102721,
      "sequence": "686",
      "msgs": [
        {
          "type": "osmosis/gamm/swap-exact-amount-in",
          "value": {
            "sender": "osmo1unf2rcytjxfpz8x8ar63h4qeftadptg5t0nqcl",
            "routes": [
              {
                "pool_id": "5",
                "token_out_denom": "ibc/9712DBB13B9631EDFA9BF61B55F1B2D290B2ADB67E3A4EB3A875F3B6081B3B84"
              },
              {
                "pool_id": "6",
                "token_out_denom": "ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2"
              }
            ],
            "token_in": {
              "denom": "uosmo",
              "amount": "1000000"
            },
            "token_out_min_amount": "49999"
          }
        }
      ],
      "protoMsgs": [
        {
          "type_url": "/osmosis.gamm.v1beta1.MsgSwapExactAmountIn",
          "value": [
            10,
            43,
            // ...
          ]
        }
      ],
      "memo": "",
      "source": null,
      "fee": {
        "gas": "900000",
        "amount": [
          {
            "denom": "uosmo",
            "amount": "22500"
          }
        ]
      },
      // Sign type, could be AMINO or DIRECT
      "signType": "AMINO",
      "rpcUrl": "https://osmosis-rpc.polkachu.com"
    },
    
    // @deprecated An alternative to CosmosMessage object for the cosmos wallets 
    // that do not support generic Cosmos messages 
    "rawTransfer": null
  }
}
### Cosmos Direct Sample Transaction: [(Test)](https://api.rango.exchange/basic/swap?from=JUNO.JUNO\&to=JUNO.ATOM--ibc%2Fc4cff46fd6de35ca4cf4ce031e643c8fdc9ba4b99ae598e9b0ed98fe3a2319f9\&amount=1000000\&slippage=8\&fromAddress=juno1unf2rcytjxfpz8x8ar63h4qeftadptg54xrtf3\&toAddress=juno1unf2rcytjxfpz8x8ar63h4qeftadptg54xrtf3\&disableEstimate=true\&apiKey=c6381a79-2817-4602-83bf-6a641a409e32) This type is only used in limited swappers like WYNDDex (and Juno Blockchain) and we are going to deprecate support for Cosmos Direct transaction types whenever possible. You could sign this type of transactions using Stargate Client library. 
"tx": {
  // This field equals to COSMOS for all COSMOS Transactions
  "type": "COSMOS",

  // Source wallet address for this transaction
  "fromWalletAddress": "juno1unf2rcytjxfpz8x8ar63h4qeftadptg54xrtf3",
  "blockChain": "JUNO",
  "data": {
    "chainId": "juno-1",
    "account_number": 125507,
    "sequence": "309",
    "msgs": [
      {
        "typeUrl": "/cosmwasm.wasm.v1.MsgExecuteContract",
        "value": {
          "sender": "juno1unf2rcytjxfpz8x8ar63h4qeftadptg54xrtf3",
          "contract": "juno1pctfpv9k03v0ff538pz8kkw5ujlptntzkwjg6c0lrtqv87s9k28qdtl50w",
          "msg": "eyJleGVjdXRlX3N3YXBfb3BlcmF0aW9ucyI6eyJvcGVyYXRpb25zIjpbeyJ3eW5kZXhfc3dhcCI6eyJhc2tfYXNzZXRfaW5mbyI6eyJuYXRpdmUiOiJpYmMvQzRDRkY0NkZENkRFMzVDQTRDRjRDRTAzMUU2NDNDOEZEQzlCQTRCOTlBRTU5OEU5QjBFRDk4RkUzQTIzMTlGOSJ9LCJvZmZlcl9hc3NldF9pbmZvIjp7Im5hdGl2ZSI6InVqdW5vIn19fV0sIm1heF9zcHJlYWQiOiIwLjAxIn19",
          "funds": [
            {
              "denom": "ujuno",
              "amount": "1000000"
            }
          ]
        }
      }
    ],
    "protoMsgs": [],
    "memo": "",
    "source": null,
    "fee": {
      "gas": "1000000",
      "amount": [
        {
          "denom": "ujuno",
          "amount": "2500"
        }
      ]
    },
    // Sign type, could be AMINO or DIRECT
    "signType": "DIRECT",
    "rpcUrl": "https://rpc-juno.itastakers.com:443/"
  },

  // @deprecated An alternative to CosmosMessage object for the cosmos wallets 
  "rawTransfer": null
}
## Transfer Sample Transaction: [(Test)](https://api.rango.exchange/basic/swap?from=BCH.BCH\&to=ETH.ETH\&amount=10000000000\&slippage=8\&fromAddress=qruy9zr8x9k335pkvqpfas3jsjfesq5gzu4nreyn4j\&toAddress=0x6f33bb1763eebead07cf8815a62fcd7b30311fa3\&disableEstimate=true\&apiKey=c6381a79-2817-4602-83bf-6a641a409e32) Here is the structure of an UTXO (Transfer) transaction: ```json { "tx": { // This field equals to TRANSFER for all UTXO Transactions "type": "TRANSFER", // The method that should be passed to wallet including deposit, transfer "method": "transfer", // Source wallet address that can sign this transaction "fromWalletAddress": "qruy9zr8x9k335pkvqpfas3jsjfesq5gzu4nreyn4j", // Destination wallet address that the fund should be sent to "recipientAddress": "qzumtx6ufk3qu92slcsg5ajehujehzcquydmhaq0eh", // The memo of transaction, can be null "memo": "=:ETH.ETH:0x6f33bb1763eebead07cf8815a62fcd7b30311fa3:1080176077:rg:0", // The machine-readable amount of transaction "amount": "10000000000", // The decimals of the asset "decimals": 8, // An asset with its ticker "asset": { "blockchain": "BTC", "symbol": "BTC", "address": null, "ticker": "BTC" } }, // Partially signed bitcoin transaction "psbt": { "unsignedPsbtBase64": "cHNidP8BAH0CAAAAAdeeknt27QIuENUtqyEuDWKi0HjMR6J8OyFIH0AeCowYAAAAAAD/////AoCWmAAAAAAAIlEgD5gCxhBANQBrbG92Di7Y0wPGEgBXxa9K7mVT0IIvONIM+SMCAAAAABYAFOoXzf1rD8gSxTM022thJ3/639UBAAAAAAABAR9QkbwCAAAAABYAFOoXzf1rD8gSxTM022thJ3/639UBAAAA", "inputsToSign": [ { "address": "bc1qagtumlttplyp93fnxndkkcf80ladl4gpnmv25u", "signingIndexes": [0] } ] } } ``` ## Tron Sample Transaction: [(Test)](https://api.rango.exchange/basic/swap?from=TRON.TRX\&to=TRON.USDT--TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t\&amount=1000000\&slippage=8\&fromAddress=TGmhZwFoCZYBcbJt82TmKQ3HXCmcV2UrGT\&toAddress=TGmhZwFoCZYBcbJt82TmKQ3HXCmcV2UrGT\&disableEstimate=true\&apiKey=c6381a79-2817-4602-83bf-6a641a409e32) Here is the structure of a Tron transaction. Similar to EVM transactions, if user doesn't have enough approval for this quote, he needs to sign approve transaction first based on `approve_payload`, `approve_raw_data`, and `approve_raw_data_hex` fields and then sign the main transaction. ```json "tx": { // This field equals to TRON for all TRON Transactions "type": "TRON", // Transaction blockchain "blockChain": { "name": "TRON", "defaultDecimals": 18, "addressPatterns": [ "^T[1-9A-HJ-NP-Za-km-z]{33}$" ], "feeAssets": [ { "blockchain": "TRON", "symbol": "TRX", "address": null } ], "type": "TRON", "chainId": "728126428" }, // The data of smart contract call "raw_data": { "contract": [ { "parameter": { "value": { "data": "b24ebddb000000000000000000000000000000000000000000000000000000000001160500000000000000000000000000000000000000000000000000000189ea5a08a000000000000000000000000000000000000000000000000000000000000f4240", "owner_address": "414a9bbc3fe169c752a08de9c7becfb4921034ae4a", "contract_address": "41a2726afbecbd8e936000ed684cef5e2f5cf43008", "call_value": 1000000 }, "type_url": "type.googleapis.com/protocol.TriggerSmartContract" }, "type": "TriggerSmartContract" } ], "ref_block_bytes": "1091", "ref_block_hash": "5310b46b57c59d0d", "expiration": 1691853975000, "fee_limit": 1500000000, "timestamp": 1691853916537 }, "approve_raw_data": null, "raw_data_hex": "0a02109122085310b46b57c59d0d40d8dbebd29e315ad301081f12ce010a31747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e54726967676572536d617274436f6e74726163741298010a15414a9bbc3fe169c752a08de9c7becfb4921034ae4a121541a2726afbecbd8e936000ed684cef5e2f5cf4300818c0843d2264b24ebddb000000000000000000000000000000000000000000000000000000000001160500000000000000000000000000000000000000000000000000000189ea5a08a000000000000000000000000000000000000000000000000000000000000f424070f992e8d29e31900180dea0cb05", "approve_raw_data_hex": null, "__payload__": { "call_value": 1000000, "contract_address": "41a2726afbecbd8e936000ed684cef5e2f5cf43008", "fee_limit": 1500000000, "function_selector": "trxToTokenSwapInput(uint256,uint256,uint256)", "owner_address": "414a9bbc3fe169c752a08de9c7becfb4921034ae4a", "parameter": "000000000000000000000000000000000000000000000000000000000001160500000000000000000000000000000000000000000000000000000189ea5a08a000000000000000000000000000000000000000000000000000000000000f4240", "chainType": 0 }, "approve_payload": null, "txID": "45a6390a1c1fe80832bd654cbb08bd5c6e804f4fe7f0fc4014421b84280e044c", "approveTxID": null, "visible": false, "approveVisible": null } ``` ## Starknet Sample Transaction: [(Test)](https://api.rango.exchange/basic/swap?from=STARKNET.ETH--0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7\&to=STARKNET.DAI--0xda114221cb83fa859dbdb4c44beeaa0bb37c7537ad5ae66fe5e0efd20e6eb3\&amount=1000000\&slippage=8\&fromAddress=0x473ab17973104e37d341d8127e1b109e7960443a7b08abb63a76e1e3e405067\&toAddress=0x473ab17973104e37d341d8127e1b109e7960443a7b08abb63a76e1e3e405067) Here is the structure of a Starknet transaction. Similar to EVM transactions, if user doesn't have enough approval for this quote, he needs to sign approve transaction first based on `approveCalls` field first and then sign the main transaction. ```json "tx": { // This field equals to STARKNET for all STARKNET Transactions "type": "STARKNET", // Transaction blockchain "blockChain": "STARKNET", // List of calldata to sign a multiple transaction "calls": [ { "contractAddress": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", "entrypoint": "approve", "calldata": [ "0x07a6f98c03379b9513ca84cca1373ff452a7462a3b61598f0af5bb27ad7f76d1", "0x000000000000000000000000000f4240", "0x00000000000000000000000000000000" ] }, { "contractAddress": "0x07a6f98c03379b9513ca84cca1373ff452a7462a3b61598f0af5bb27ad7f76d1", "entrypoint": "swapExactTokensForTokens", "calldata": [ "0x000000000000000000000000000f4240", "0x00000000000000000000000000000000", "0x00000000000000000000000065434224", "0x00000000000000000000000000000000", "2", "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", "0xda114221cb83fa859dbdb4c44beeaa0bb37c7537ad5ae66fe5e0efd20e6eb3", "0x473ab17973104e37d341d8127e1b109e7960443a7b08abb63a76e1e3e405067", "1691858292" ] } ], // List of approves calldata if needed "approveCalls": null, // Max fee for the transaction "maxFee": null } ``` ## Solana Sample Transaction: [(Test)](https://api.rango.exchange/basic/swap?from=SOLANA.SOL\&to=SOLANA.USDC--EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\&amount=1000000000\&slippage=3.0\&disableEstimate=true\&fromAddress=3HsNMDtxPRUzwLpDJemmNVbasm11Ei5CGGCjktgHh27F\&toAddress=3HsNMDtxPRUzwLpDJemmNVbasm11Ei5CGGCjktgHh27F\&apiKey=c6381a79-2817-4602-83bf-6a641a409e32) {% hint style="warning" %} **Base64 Encoding** Remember to broadcast the signed transaction to Solana RPCs with **base64** encoding. The **base58 encoding is deprecated**, but it is still the default method in Solana [docs](https://solana.com/docs/rpc/http/sendtransaction). {% endhint %} {% hint style="info" %} **Versioned vs Legacy** All supported routes for Solana are `VERSIONED` transactions except a special case of converting `SOL` to `WSOL` or vice versa via Solana Wrapper. (which you can ignore it.) * [Sample for versioned transaction](https://api.rango.exchange/basic/swap?from=SOLANA.SOL\&to=SOLANA.USDC--EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\&amount=1000000000\&slippage=3.0\&disableEstimate=true\&fromAddress=3HsNMDtxPRUzwLpDJemmNVbasm11Ei5CGGCjktgHh27F\&toAddress=3HsNMDtxPRUzwLpDJemmNVbasm11Ei5CGGCjktgHh27F\&apiKey=c6381a79-2817-4602-83bf-6a641a409e32) * [Sample for legacy transaction](https://api.rango.exchange/basic/swap?from=SOLANA.SOL\&to=SOLANA.WSOL--So11111111111111111111111111111111111111112\&amount=1000000000\&slippage=3.0\&disableEstimate=true\&fromAddress=3HsNMDtxPRUzwLpDJemmNVbasm11Ei5CGGCjktgHh27F\&toAddress=3HsNMDtxPRUzwLpDJemmNVbasm11Ei5CGGCjktgHh27F\&apiKey=c6381a79-2817-4602-83bf-6a641a409e32) {% endhint %} 
"tx": {
     // This field equals to SOLANA for all SOLANA Transactions
    "type": "SOLANA",
    
    // Transaction blockchain
    "blockChain": "SOLANA",
    
    // Wallet address of transaction initiator
    "from": "3HsNMDtxPRUzwLpDJemmNVbasm11Ei5CGGCjktgHh27F",
    
    // Transaction identifier in case of retry
    "identifier": "Swap",
    
    // List of instructions
    "instructions": [ ],

    // Recent blockHash. Nullable. Filled only if message is already partially signed
    "recentBlockhash": null,
    
    // List of signatures. Filled only if message is already partially signed
    "signatures": [ ],
    
    // When serialized message appears, there is no need for other fields and you just sign and send it
    "serializedMessage": [1, 0, 95, 96, ..., 1, 253], 
    
    // Could be LEGACY or VERSIONED
    "txType": "VERSIONED"
  }
## SUI Sample Transaction: [(Test)](https://api.rango.exchange/basic/swap?from=SUI.SUI\&to=SOLANA.SOL\&amount=10000000000\&slippage=3.0\&disableEstimate=true\&fromAddress=3HsNMDtxPRUzwLpDJemmNVbasm11Ei5CGGCjktgHh27F\&toAddress=3HsNMDtxPRUzwLpDJemmNVbasm11Ei5CGGCjktgHh27F\&apiKey=c6381a79-2817-4602-83bf-6a641a409e32) {% hint style="info" %} **Key Notes:** * The **unsignedPtbBase64** field is a base64-encoded string that contains the transaction's raw data. This is typically used to create the signed transaction, which would then be broadcasted to the blockchain. {% endhint %} 
"tx": {
    "type": "SUI",
    "blockChain": "SUI",
    // Base64-encoded unsigned transaction data
    "unsignedPtbBase64": "AAAA...<base64_encoded_data>..."
  }
## XRPL Sample Transaction: [(Test)](https://api.rango.exchange/basic/swap?from=XRPL.XRP\&to=BASE.ETH\&amount=5000000) {% hint style="info" %} **Key Notes:** * **Trust lines (IOUs):** When the destination token is not the native XRP, you need to set up a trust line to the issuer account before the swap (wallets can sign this as a pre-tx) {% endhint %} {% hint style="warning" %} Make sure to check and implement the [Transaction Prerequisites](/api-integration/basic-api-single-step/transaction-prerequisites) before integration of XRPL network. {% endhint %} ```json "tx": { "type": "XRPL", "blockChain": "XRPL", "data": { "TransactionType": "Payment", "Destination": "rM27yzkCw6WA3T4g1sPaeC1kpxHUhuxRWn", "Amount": "10231000", "Memos": [ { "Memo": { "MemoData": "7B2266726F6D546F6B656E223A22307865656565656565656565656565656565656565656565656565656565656565656565656565656565222C22746F546F6B656E223A2258525041594E45547C72616E676F4465787C302E3031222C2273656E646572223A22724769537053387177614B4E62386E6D6A3234616831794767724434346B36543663222C2264657374696E6174696F6E223A22724769537053387177614B4E62386E6D6A3234616831794767724434346B36543663222C226D696E52657475726E416D6F756E74223A22393136393338353234373034303030303030303030303030222C2266726F6D416D6F756E74223A223130323331303030227D" } } ] }, "type": "XRPL" } ``` ```json "tx": { "type": "XRPL", "blockChain": "XRPL", "data": { "TransactionType": "Payment", "Destination": "rM27yzkCw6WA3T4g1sPaeC1kpxHUhuxRWn", "Amount": "10231000", "Memos": [ { "Memo": { "MemoData": "7B2266726F6D546F6B656E223A22307865656565656565656565656565656565656565656565656565656565656565656565656565656565222C22746F546F6B656E223A2258525041594E45547C72616E676F4465787C302E3031222C2273656E646572223A22724769537053387177614B4E62386E6D6A3234616831794767724434346B36543663222C2264657374696E6174696F6E223A22724769537053387177614B4E62386E6D6A3234616831794767724434346B36543663222C226D696E52657475726E416D6F756E74223A22393136393338353234373034303030303030303030303030222C2266726F6D416D6F756E74223A223130323331303030227D" } } ] }, "prerequisites": [ { "type": "XRPL_CHANGE_TRUSTLINE", "currency": "The Xrpl output asset currency, such as USDC", "issuer": "The Xrpl output asset issuer", "value": "Minimum expected value of trust for the Xrpl asset", "wallet": "User's wallet address which must have this trustline allowed for the Xrpl asset" } ], } ``` ```json "tx": { "type": "XRPL", "blockChain": "XRPL", "data": { "TransactionType": "Payment", "Destination": "rM27yzkCw6WA3T4gsPaeC1kpxHUhuxRWn", "Amount": { "currency": "CSC", "value": "256461.000000000000000000", "issuer": "rCSCManTZ8ME9EoLrSHHY1KW8PPwWMgkwr" }, "Memos": [ { "Memo": { "MemoData": "7B2266726F6D546F6B656E223A22724353434D616E545A384D4539456F4C72534848594B5738505077574D676B7772222C22746F546F6B656E223A22307865656565656565656565656565656565656565656565656565656565656565656565656565656565222C2273656E646572223A22724769537053387177614B4E62386E6D6A3234616831794767724434346B36543663222C2264657374696E6174696F6E223A22724769537053387177614B4E62386E6D6A3234616831794767724434346B36543663222C226D696E52657475726E416D6F756E74223A2237303230333339222C2266726F6D416D6F756E74223A22323536343631303030303030303030303030303030303030227D" } } ] }, "prerequisites": [ { "type": "XRPL_CHANGE_TRUSTLINE", "currency": "The Xrpl output asset currency, such as USDC", "issuer": "The Xrpl output asset issuer", "value": "Minimum expected value of trust for the Xrpl asset", "wallet": "User's wallet address which must have this trustline allowed for the Xrpl asset" } ], } ``` ## Stellar Sample Transaction: [(Test)](https://api.rango.exchange/basic/swap?from=STELLAR.XLM\&to=STELLAR.USDC--USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN\&amount=50000000) In order to execute a transaction on stellar network, Rango provides you a base64 encoded External Data Representation or XDR for operations and memo of the transaction, and preconditions of a PreconditionsV2. You can check the [official Stellar docs regarding XDRs](https://developers.stellar.org/docs/learn/fundamentals/data-format/xdr) in Stellar Network. This value must be signed by user's wallet. {% hint style="info" %} **Key Notes:** * **Trust lines:** When the destination token is not the native XLM, the API returns a trust-line prerequisites which must be signed and broadcasted before signing and broadcasting the swap transaction. In some of the swaps, Rango would be able to include the `ChangeTrustOperation` in the transaction itself, and so no trust-line prerequisite would be returned by the API. {% endhint %} {% hint style="warning" %} Make sure to check and implement the [Transaction Prerequisites](/api-integration/basic-api-single-step/transaction-prerequisites) before integration of Stellar network. {% endhint %} Note that for non-native Stellar assets, user's wallet must allow a trustline for the asset in order to receive it. 
 "transaction": {
        "type": "STELLAR",
        "blockChain": "STELLAR",
        "data": {
                "baseFee": null, // Optional BigInt value, Recommended base fee (in stroops) for building the stellar transaction
                "preconditions": {        // CAP-21 PreconditionsV2 of transaction transaction
                        "timeBounds": { // Optional, time bounds of stellar transaction data
                                "minTime": 1778506995, // BigInt value, Unix timestamped constraint for minimum time of transaction validity
                                "maxTime": 1779506995 // BigInt value, Unix timestamped constraint for maximum time of transaction validity
                        },
                        "ledgerBounds": { // Optional, ledger bounds of stellar transaction data, Transaction only valid for ledger numbers n such that minLedger <= n < maxLedger
                                "minLedger": 1000, // BigInt value, Minimum ledger for transaction validity
                                "maxLedger": 0 // BigInt value, Maximum ledger for transaction validity, 0 here means NO maxLedger
                        },
                        "minSeqNumber": null, // BigInt value, If NULL, only valid when sourceAccount's sequence number is seqNum - 1.  Otherwise, valid when sourceAccount's sequence number n satisfies minSeqNum <= n < tx.seqNum
                        "minSeqAge": null, // BigInt value, For the transaction to be valid, the current ledger time must be at least minSeqAge greater than sourceAccount's seqTime
                        "minSeqLedgerGap": null, // BigInt value, For the transaction to be valid, the current ledger number must be at least minSeqLedgerGap greater than sourceAccount's seqLedger
                        "extraSigners": null // Optional list of strings, For the transaction to be valid, there must be a signature corresponding to every Signer in this array
                },
                "operationsXdrBase64": [ // list of operations as base 64 encoded strings
                        "AAA...",
                        "AAA..."
                ],
                "memoXdrBase64": null // base 64 encoded memo of transaction
        },
        "prerequisites": [
                {
                        "type": "STELLAR_CHANGE_TRUSTLINE",
                        "code": "The stellar output asset code, such as USDC",
                        "issuer": "The stellar asset issuer, e.g.: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
                        "value": "The minimum amount of required trustline for this stellar asset, such as 11.50",
                        "wallet": "User's wallet address which must have this trustline allowed for the stellar asset" 
                }
        ]
    }
# Transaction Prerequisites This page describes the concept of Transaction Prerequisites and how to handle it in Rango API workflow. Transaction Prerequisites are blockchain specific setup transactions that must be completed before a swap can execute successfully. Depending on the source or destination blockchain and asset type, users may need to sign/authorize another transaction before the main transaction is submitted onchain. {% hint style="warning" %} Make sure your implementation checks and handles all of the prerequisites provided by Rango API, and do not consider only the source blockchain network and source wallet. In some cases, such as bridging into non-native Stellar or XRPLedger tokens, you must provide a trustline for **the desintation token** (obviously, **on the destination blockchain network**) **before initiating the bridge/swap** on the source token. {% endhint %} The list of possible prerequisites are given in the sections below. ### Stellar Change Trust Prerequisite When bridging/swapping to SAC tokens on the Stellar network (except for the native XLM) the receiving wallet must have enough trust in that token. This can be done via a [Change Trust Operation](https://developers.stellar.org/docs/data/apis/horizon/api-reference/resources/operations/object/change-trust) on the Stellar network. In such cases, Rango provides a prerequisite in response of `/swap` endpoint which must be handled before broadcasting the main bridge or swap transaction. Example EVM Transaction with Stellar ChangeTrust prerequisite when briding from Evm chains to Stellar network. 
{
   ..., // other swap endpoint response fields
   "tx": {
      "blockChain": "ARBITRUM",
      "from": "0x....",
      "to": "0x...",
      "spender": "0x...",
      "data": "0x...",
      "value": 1000000000000000000,
      "prerequisites": [
         {
            "code": "USDC",
            "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "value": "922337203685.4775807",
            "wallet": "G....." // user's stellar wallet address
         }
      ]
   }
}
In this case, you must make sure the required trust-line for this Stellar Asset is ensured on the stellar blockchain network for the user. If it is not ensured, you must ask the user to sign a `ChangeTrust` Operation for this asset and broadcast it to the Stellar network before signing and broadcasting the EVM transaction. ### XRP Ledger Change Trust Prerequisite Similar to the Stellar Trust Line requirement, receiving tokens on XRPLedger requires a trust between the receiving wallet and the issuer of the token. This can be done by signing and broadcasting a [TrustSet](https://xrpl.org/docs/references/protocol/transactions/types/trustset) transaction on the XRP Ledger network. In such cases, Rango provides a prerequisite in response of `/swap` endpoint which must be handled before broadcasting the main bridge or swap transaction. Example EVM Transaction with XRPLedger Change Trust prerequisite when briding from Evm chains to XRPL network. 
{
   ..., // other swap endpoint response fields
   "tx": {
      "blockChain": "ARBITRUM",
      "from": "0x....",
      "to": "0x...",
      "spender": "0x...",
      "data": "0x...",
      "value": 1000000000000000000,
      "prerequisites": [
         {
            "currency": "RLUSD",
            "issuer": "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De",
            "value": "1000000000",
            "wallet": "r..." // user's xrpl wallet address
         }
      ]
   }
}
In this case, you must make sure the required trust for this asset is ensured on the XRPL blockchain network for the user. If it is not ensured, you must ask the user to sign a `TrustSet` Transaction for this asset and broadcast it to the XRPL network before signing and broadcasting the EVM transaction. # Integration Checklist Here is a checklist for dApps and wallets that have integrated Rango and are ready to launch the product. This checklist includes sample scenarios that are great to be tested before the final release. **Scenario A:** If your dApp purely supports Ethereum-based blockchains, including Ethereum, BSC, Polygon, Scroll, Arbitrum, etc. 1. An on-chain swap such as BSC.USDT -> BSC.BNB 2. A bridge such as Polygon.USDT -> AVAX.USDT.e 3. A +2 step swap such as BSC.BNB -> AVAX.USDT.e 4. Check approval scenarios such as BSC.BNB to some unpopular token in BSC which you've never had and vice versa. **Scenario B:** If your dApp is purely cosmos-based: 1. An `AMINO` IBC swap such as Cosmos.ATOM -> Osmosis.ATOM 2. An `AMINO` swap such as Osmosis.Osmo -> Osmosis.ATOM 3. A `DIRECT` swap such as Juno.Juno -> Juno.USDC via WYND DEX. **Scenario C:** if your dApp is purely solana-based: 1. An on-chain swap such as Solana.SOL -> Solana.USDC. 2. A bridge from Solana to EVM such as Solana.SOL -> BSC.USDC. 3. A bridge from EVM to Solana such as BSC.USDC -> Solana.SOL. {% hint style="info" %} **Hint:** If you are a hybrid of the above models, try to do all the list together**.** {% endhint %} # Main API - Multi Step Rango Exchange Main API (Multi Step) # API Flow Rango Exchange Main API Flow ## Scenario Here is a sample interaction scenario between a dApp and Rango Main 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 method to get list of all supported blockchains, swappers and tokens which are used to show a proper swap box for the user. Sample Code: ```typescript const metaResponse = await axios.get('https://api.rango.exchange/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: ```typescript const tokens = meta.tokens; const BNB_ADDRESS = null const USDT_ADDRESS = '0xc7198437980c041c805a1edcba50c1ce5db95118' 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 Get All Possible Routes API. If the user doesn't select and confirm one of the routes within the timeout period (e.g. after 30s), this step should be repeated to ensure the output amount and routes are up to date. Here is the sample code: ```typescript const routingResponse = await axios.post( 'https://api.rango.exchange/routing/bests', { 'from': { 'blockchain': 'BSC', 'symbol': 'BNB', 'address': null, }, 'to': { 'blockchain': 'AVAX_CCHAIN', 'symbol': 'USDT.E', 'address': '0xc7198437980c041c805a1edcba50c1ce5db95118' }, 'amount': '1', 'slippage': '1.0' }, { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' }, headers: { 'content-type': 'application/json' } } ); // check if the route was okay if (!routingResponse.results || routingResponse.error) { // no routes found // you could show diagnosis messages to user if it is not empty // sample: "diagnosisMessages":["Your input amount might be too low!"] console.log(routingResponse.diagnosisMessages) } else { // everything was okay } ```
4. The user selects one of the routes to start the executing the route. This is an example of selected route which includes two steps: * Step 1: Swap BSC.BNB to BSC.USDT via 1Inch. * Step 2: Swap BSC.USDT to AVAX\_CCHAIN.USDT via Stargate Bridge.
5. The dApp call the Confirm Route API to notify Rango that this route has been selected for execution. At this stage, it is also possible to verify if the user has sufficient balance and fees for each step of the route in advance. Here is the sample code: ```typescript const confirmResponse = await axios.post( 'https://api.rango.exchange/routing/confirm', { 'selectedWallets': { 'BSC': '0xeae6d42093eae057e770010ffd6f4445f7956613', 'AVAX_CCHAIN': '0xeae6d42093eae057e770010ffd6f4445f7956613' }, 'destination': '0x6f33bb1763eebead07cf8815a62fcd7b30311fa3', 'requestId': '33e0b996-da5e-4922-9fdc-f7206247fc34' }, { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' }, headers: { 'content-type': 'application/json' } } ); // check if the route was okay if (!confirmResponse.result || confirmResponse.error) { // there was a problem in confirming the route } else { // everything was okay // you could compare confirmed route with the route output amount // and warn the user if there is noticable difference // e.g. check if confirmed route output is 2% less than previous one const confirmedOutput = new BigNumber(routingResponse.results[selected]?.outputAmount) const finalOutput = new BigNumber(confirmResponse.result?.outputAmount) if (finalOutput.lt(confirmedOutput.multipliedBy(new BigNumber(0.98))) { // get double confirmation from the user } else { // proceed to executing the route } } ```
For every steps of the selected route, we need to repeat the next steps:
6. The dApp calls the Create Transaction API to get transaction data for this step. The response of create transaction API could be an approve transaction (`isApproval=true`) or the main transaction. (`isApproval=false`) ```typescript const createTransactionResponse = await axios.post( 'https://api.rango.exchange/tx/create', { 'requestId': '1978d8fa-335d-4915-a039-77f1a17315f5', 'step': 1, 'userSettings': { 'slippage': 3, 'infiniteApprove': false }, 'validations': { 'balance': true, 'fee': true, 'approve': true } }, { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' }, headers: { 'content-type': 'application/json' } } ); if (createTransactionResponse.transaction) { // everything was okay } else { // there was a problem in creating transaction console.log(createTransactionResponse.error) } ``` **How to set validation parameters?** If you are verifying the balance and fee amount on your client side or you've already checked them in route confirmation step, it is advisable to set the balance and fee parameters to false to prevent duplicate checks or potential errors during validation.
7. 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 route. **Sample Code for EVM transactions:** ```typescript // 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 = createTransactionResponse.transaction if (isEvmTransacation(tx)) { if (tx.isApproval) { // user doesn't have enough approval and needs to sign approve tx let approveTx = { 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 approveTxHash = (await signer.sendTransaction(approveTx)).hash } else { // user already has enough approve amoaunt // we could proceed to 8th step (main transaction) } } ```
8. The dApp periodically calls Check Approval 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: ```typescript const response = await axios.get('https://api.rango.exchange/tx/b3a12c6d-86b8-4c21-97e4-809151dd4036/check-approval', { params: { 'txId': '0x7f17aaba51d1f24204cd8b02251001d3704add46d84840a5826b95ef49b8b74f', '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. The dApp calls the Create Transaction API again to fetch the main swap transaction and asks user to sign it. (similar to the 6th and 6th steps) Sample code for EVM transactions: ```typescript // 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 = createTransactionResponse.transaction 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 } ```
10. The dApp calls Check 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. ```typescript const response = await axios.post( 'https://api.rango.exchange/tx/check-status', { 'requestId': 'b3a12c6d-86b8-4c21-97e4-809151dd4036', 'txId': '0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5', 'step': 1 }, { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' }, headers: { 'content-type': 'application/json' } } ); 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 check-status method again after a timeout (10s) } } ```
11. If the step succeeds, the dApp repeats all instructions from steps 6 to 10 for the next step of the route.
12. 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: ```typescript await axios.post( 'https://api.rango.exchange/tx/report-tx', { 'requestId': '688b308e-a06b-4a4e-a837-220d458b8642', 'step': 1, 'eventType': 'SEND_TX_FAILED', 'reason': 'RPC Error' }, { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' }, headers: { 'content-type': 'application/json' } } ); ```
## Flow Chart
# API Reference # Get Blockchains & Tokens Get all blockchains, tokens and swappers meta data ## Get Full Metadata API This service gathers all the essential data needed for a swap's UI, including list of all [blockchains](/api-integration/terminology#blockchain), [tokens](/api-integration/terminology#asset-token) and [protocols](/api-integration/terminology#swapper) (DEXes & Bridges) metadata. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript // basic usage const meta = await rango.getAllMetadata() ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.get('https://api.rango.exchange/meta', { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/meta?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript // filtering blockchains, swappers and tokens const meta = await rango.getAllMetadata({ blockchains: ['ETH', 'POLYGON'], blockchainsExclude: false, swappers: ['Across', 'OneInchEth'], swappersExclude: false, swappersGroups: ['Across', '1Inch'], swappersGroupsExclude: false, transactionTypes: ['EVM'], transactionTypesExclude: false, excludeNonPopulars: false }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.get('https://api.rango.exchange/meta', { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32', 'blockchains': 'ETH,POLYGON', 'blockchainsExclude': false, 'swappers': 'Across,OneInchEth', 'swappersExclude': false, 'swapperGroups': 'Across,1Inch', 'swappersGroupsExclude': false, 'transactionTypes': 'EVM', 'transactionTypesExclude': false, 'excludeNonPopulars': false } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/meta?blockchains=ETH&blockchains=POLYGON&blockchainsExclude=false&swappers=Across&swappers=OneInchEth&swappersExclude=false&swapperGroups=Across&swapperGroups=1Inch&swappersGroupsExclude=false&transactionTypes=EVM&transactionTypesExclude=false&excludeNonPopulars=false&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} GET Metadata Swagger {% endembed %} {% hint style="info" %} **Why is it required to obtain the list of supported tokens from Rango API?** Even if dApp has its own list of tokens and blockchains, it's still useful to get list of supported tokens by Rango: * To avoid extra API call when token is not supported by Rango * Access tokens' `symbol` which is required for getting quote for each token. {% endhint %} {% hint style="info" %} **Why is it recommended to obtain the list of supported blockchains from Rango API?** * For working with other API methods like `getBestRoute`, you need to have identifier (name) of each blockchain. You could hard code blockchain names if you want to have limited chains support or get them dynamically via the API. (You could store a map of each blockchain `chainId` to Rango `name` if required.) * Because of different reasons like blockchains maintenance, Rango maintenance, hacks, and etc, a blockchain could be disabled in Rango. You could check which blockchains are enabled now using `enabled` flag for each blockchain in meta response. {% endhint %} ### Metadata Request {% tabs %} {% tab title="API Definition" %} * **`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` * **`excludeSecondaries`** Boolean * Description: It indicates whether secondary tokens should be excluded from the response. By secondary tokens, we mean tokens that are imported from our secondary tokens lists. * Example: `false` * **`excludeNonPopulars`** Boolean * Description: It indicates whether non-popular tokens should be excluded from the response. By popular tokens, we mean native token and stable coins of each blockchain. * Example: `false` * **`ignoreSupportedSwappers`** Boolean * Description: Set this flag to false to exclude the supported swappers for each token from the response. The default value is true. * 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. * Example: `true` {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type MetaRequest = { blockchains?: string[] blockchainsExclude?: boolean swappers?: string[] swappersExclude?: boolean swappersGroups?: string[] swappersGroupsExclude?: boolean transactionTypes?: TransactionType[] transactionTypesExclude?: boolean excludeSecondaries?: boolean excludeNonPopulars?: boolean ignoreSupportedSwappers?: boolean enableCentralizedSwappers?: boolean } export enum TransactionType { EVM = 'EVM', TRANSFER = 'TRANSFER', COSMOS = 'COSMOS', SOLANA = 'SOLANA', TRON = 'TRON', STARKNET = 'STARKNET', TON = 'TON', } ``` {% endtab %} {% endtabs %} ### Metadata Response {% tabs %} {% tab title="API Definition" %} * **`blockchains`** * Description: List of all supported [blockchains](https://docs.rango.exchange/api-integration/terminology#blockchain) * **`tokens`** * Description: List of all [tokens](https://docs.rango.exchange/api-integration/terminology#asset-token) * **`popularTokens`** * Description: List of all popular tokens * **`swappers`** * Description: List of all supported [protocols](https://docs.rango.exchange/api-integration/terminology#swapper) (DEXes & Bridges) {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type MetaResponse = { blockchains: BlockchainMeta[] tokens: Token[] popularTokens: Token[] swappers: SwapperMeta[] } export type BlockchainMeta = | EvmBlockchainMeta | CosmosBlockchainMeta | TransferBlockchainMeta | SolanaBlockchainMeta | StarkNetBlockchainMeta | TronBlockchainMeta | TonBlockchainMeta export type Token = { blockchain: string address: string | null symbol: string name: string | null decimals: number image: string usdPrice: number | null isSecondaryCoin: boolean coinSource: string | null coinSourceUrl: string | null isPopular: boolean supportedSwappers?: string[] } 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 BlockchainMetaBase = { type: TransactionType name: string shortName: string displayName: string defaultDecimals: number feeAssets: Asset[] addressPatterns: string[] logo: string color: string sort: number enabled: boolean chainId: string | null info: | EVMChainInfo | CosmosChainInfo | StarkNetChainInfo | TronChainInfo | null } export interface EvmBlockchainMeta extends BlockchainMetaBase { type: TransactionType.EVM chainId: string info: EVMChainInfo } export interface CosmosBlockchainMeta extends BlockchainMetaBase { type: TransactionType.COSMOS chainId: string | null info: CosmosChainInfo | null } export interface TransferBlockchainMeta extends BlockchainMetaBase { type: TransactionType.TRANSFER chainId: null info: null } export interface SolanaBlockchainMeta extends BlockchainMetaBase { type: TransactionType.SOLANA chainId: string info: null } export interface StarkNetBlockchainMeta extends BlockchainMetaBase { type: TransactionType.STARKNET chainId: string info: StarkNetChainInfo } export interface TronBlockchainMeta extends BlockchainMetaBase { type: TransactionType.TRON chainId: string info: TronChainInfo } export interface TonBlockchainMeta extends BlockchainMetaBase { type: TransactionType.TON chainId: string info: null } ``` {% endtab %} {% tab title="Sample Response" %} ```typescript { "tokens": [ { "blockchain": "ETH", "symbol": "USDT", "image": "https://rango.vip/i/r3Oex6", "address": "0xdac17f958d2ee523a2206206994597c13d831ec7", "usdPrice": 0.999631, "decimals": 6, "name": "USD Tether", "isPopular": true, "isSecondaryCoin": false, "coinSource": null, "coinSourceUrl": null, "supportedSwappers": [ "ThorChain", "Arbitrum Bridge", "Hyphen" ] }, ], "popularTokens": [ { "blockchain": "BSC", "symbol": "USDT", "image": "https://rango.vip/i/6837hX", "address": "0x55d398326f99059ff775485246999027b3197955", "usdPrice": 0.999554, "decimals": 18, "name": "Tether USD", "isPopular": true, "isSecondaryCoin": false, "coinSource": null, "coinSourceUrl": null, "supportedSwappers": [ "ThorChain" ] } ], "blockchains": [ { "name": "OPTIMISM", "defaultDecimals": 18, "addressPatterns": [ "^(0x)[0-9A-Fa-f]{40}$" ], "feeAssets": [ { "blockchain": "OPTIMISM", "symbol": "ETH", "address": null } ], "logo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/OPTIMISM/icon.svg", "displayName": "Optimism", "shortName": "Optimism", "sort": 6, "color": "#FF0420", "enabled": true, "type": "EVM", "chainId": "0xa", "info": { "infoType": "EvmMetaInfo", "chainName": "Optimism", "nativeCurrency": { "name": "ETH", "symbol": "ETH", "decimals": 18 }, "rpcUrls": [ "https://mainnet.optimism.io" ], "blockExplorerUrls": [ "https://optimistic.etherscan.io" ], "addressUrl": "https://optimistic.etherscan.io/address/{wallet}", "transactionUrl": "https://optimistic.etherscan.io/tx/{txHash}", "enableGasV2": false } }, ], "swappers": [ { "id": "Diffusion", "title": "Diffusion", "logo": "https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/Diffusion/icon.svg", "swapperGroup": "Diffusion", "types": [ "DEX" ], "enabled": false } ] } ``` {% endtab %} {% endtabs %} ## Get Specific Part of Metadata If you only want to load a specific part of metadata rather than full metadata, i.e. only blockchains data, tokens list or supported protocols, you can use the following methods/endpoints: ### Get List of Blockchains API {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const meta = await rango.getBlockchains() ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.get('https://api.rango.exchange/meta/blockchains', { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/meta/blockchains?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} GET Blockchains Swagger {% endembed %} ### Get List of Swappers API {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const meta = await rango.getSwappers() ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.get('https://api.rango.exchange/meta/swappers', { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/meta/swappers?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} GET Swappers Swagger {% endembed %} # Get Best Route Get the best route for swapping X to Y ## Get Best Route API It goes through all the possible [swappers](/api-integration/terminology#swapper) to find the best possible route based on user experience, fee amount, and output of the swap. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript 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", }, }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript 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' } } ); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash 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" } ' ``` {% endtab %} {% endtabs %} {% embed url="" %} Get The Best Route Swagger {% endembed %} {% hint style="warning" %} **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. {% endhint %} {% hint style="info" %} **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']`. {% endhint %} ### Best Route Request {% tabs %} {% tab title="API Definition" %} * **`from`** \* Asset * Description: The source [asset](/api-integration/terminology#asset-token) * Example: `{"blockchain": "BSC", "symbol": "BNB", "address": null}` * **`to`** \* Asset * Description: The destination [asset](/api-integration/terminology#asset-token) * 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](/api-integration/terminology#affiliate-ref-referrer-code). 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` * **`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.\ 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. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript 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 } ``` {% endtab %} {% endtabs %} ### Best Route Response {% tabs %} {% tab title="API Definition" %} * **`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. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript 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 } ``` {% endtab %} {% tab title="Sample Response" %} ```typescript { "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 } ``` {% endtab %} {% endtabs %} # Get All Possible Routes Get all possible routes for swapping X to Y ## Get Best Routes API It goes through all the possible [swappers](/api-integration/terminology#swapper) to find a list of best possible routes for swapping X to Y. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const bestRoutes = await rango.getAllRoutes({ from: {"blockchain": "BSC", "symbol": "BNB", "address": null}, to: {"blockchain": "AVAX_CCHAIN", "symbol": "USDT.E", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118"}, amount: "1", slippage: "1.0" }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.post( 'https://api.rango.exchange/routing/bests', { 'from': { 'blockchain': 'BSC', 'symbol': 'BNB' }, 'to': { 'blockchain': 'AVAX_CCHAIN', 'symbol': 'USDT.E', 'address': '0xc7198437980c041c805a1edcba50c1ce5db95118' }, 'amount': '1', 'slippage': '1.0' }, { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' }, headers: { 'content-type': 'application/json' } } ); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request POST \ --url 'https://api.rango.exchange/routing/bests?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" }, "amount": "1", "slippage": "1.0" } ' ``` {% endtab %} {% endtabs %} {% embed url="" %} Get All Routes Swagger {% endembed %} {% hint style="info" %} **Confirm User Selected Route** When user confirms one of the routes and you want to go to the next step (creating transaction), it's required to call the [confirm route](/api-integration/main-api-multi-step/api-reference/confirm-route) with the relevant route request Id. Otherwise, Rango won't create the transaction for you. {% endhint %} {% hint style="info" %} **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']`. {% endhint %} ### Best Routes Request {% tabs %} {% tab title="API Definition" %} * **`from`** \* Asset * Description: The source [asset](/api-integration/terminology#asset-token) * Example: `{"blockchain": "BSC", "symbol": "BNB", "address": null}` * **`to`** \* Asset * Description: The destination [asset](/api-integration/terminology#asset-token) * 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` * **`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](/api-integration/terminology#affiliate-ref-referrer-code). 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. * **`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` * **`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.\ 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. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type MultiRouteRequest = Omit< BestRouteRequest, 'selectedWallets' | 'destination' | 'checkPrerequisites' | 'forceExecution' | 'maxLength' > 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 } ``` {% endtab %} {% endtabs %} ### Best Routes Response {% tabs %} {% tab title="API Definition" %} * **`routeId`** * The unique request Id which is generated for this request by the server. * Example: `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. * **`results`** * Description: list of of all possible routes. * **`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. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type MultiRouteResponse = { from: Asset to: Asset requestAmount: string routeId: string results: MultiRouteSimulationResult[] diagnosisMessages: string[] error: string | null errorCode: number | null traceId: number | null } export type Asset = { blockchain: string address: string | null symbol: string } export type MultiRouteSimulationResult = { requestId: string outputAmount: string resultType: RoutingResultType swaps: SwapResult[] scores: { preferenceType: PreferenceType; score: number }[] tags: RouteTag[] missingBlockchains: string[] walletNotSupportingFromBlockchain: boolean } 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 PreferenceType = 'FEE' | 'SPEED' | 'PRICE' | 'NET_OUTPUT' | 'SMART' export type RouteTag = { label: string; value: TagValue } export type Tag = | 'RECOMMENDED' | 'FASTEST' | 'LOWEST_FEE' | 'HIGH_IMPACT' | 'CENTRALIZED' export type TagValue = Tag | Omit 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 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 TimeStat = { min: number avg: number max: number } export type RecommendedSlippage = { error: boolean slippage: string } ``` {% endtab %} {% tab title="Sample Response" %} ```typescript { "from": { "blockchain": "BSC", "symbol": "BNB", "address": null }, "to": { "blockchain": "AVAX_CCHAIN", "symbol": "USDT.E", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118" }, "requestAmount": "1", "routeId": "9fd9efeb-fca2-41b2-87d0-43647345c311", "results": [ { "requestId": "486c26c0-fd2f-448d-b096-a58354ed9649", "outputAmount": "492.147292", "swaps": [ { "swapperId": "BSCPancakeV3", "swapperLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/Pancake/icon.svg", "swapperType": "DEX", "from": { "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.27 }, "to": { "symbol": "USDC", "logo": "https://rango.vip/i/e4x0s8", "blockchainLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg", "address": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d", "blockchain": "BSC", "decimals": 18, "usdPrice": 0.999239 }, "fromAmount": "1.000000000000000000", "fromAmountPrecision": null, "fromAmountMinValue": null, "fromAmountMaxValue": null, "fromAmountRestrictionType": null, "toAmount": "492.760964860255103480", "fee": [ { "asset": { "blockchain": "BSC", "symbol": "BNB", "address": null }, "expenseType": "DECREASE_FROM_OUTPUT", "amount": "0.0015000000000000000000", "name": "Rango Fee", "price": 493.27 }, { "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.27 } ], "estimatedTimeInSeconds": 45, "swapChainType": "INTER_CHAIN", "routes": [ { "nodes": [ { "nodes": [ { "marketName": "BSCPancakeV3", "marketId": "BSCPancakeV3", "percent": 1.0, "pools": [ "0xf2688fb5b81049dfb7703ada5e770543770612c4" ], "inputAmount": "998500000000000000", "outputAmount": "492760964860255103480" } ], "from": "BNB", "fromLogo": "", "fromAddress": null, "fromBlockchain": "BSC", "to": "USDC", "toLogo": "", "toAddress": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d", "toBlockchain": "BSC" } ] } ], "recommendedSlippage": null, "warnings": [], "timeStat": { "min": 1, "avg": 45, "max": 203 }, "includesDestinationTx": false, "internalSwaps": null, "maxRequiredSign": 1 }, { "swapperId": "XY Finance", "swapperLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/XY Finance/icon.svg", "swapperType": "BRIDGE", "from": { "symbol": "USDC", "logo": "https://rango.vip/i/e4x0s8", "blockchainLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg", "address": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d", "blockchain": "BSC", "decimals": 18, "usdPrice": 0.999239 }, "to": { "symbol": "USDC", "logo": "https://rango.vip/i/j9eYAa", "blockchainLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/AVAX_CCHAIN/icon.svg", "address": "0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e", "blockchain": "AVAX_CCHAIN", "decimals": 6, "usdPrice": 1.0 }, "fromAmount": "492.760964860255103480", "fromAmountPrecision": null, "fromAmountMinValue": "0.215999999999999992006394222698872908949851989746093750", "fromAmountMaxValue": "4245.273839", "fromAmountRestrictionType": "EXCLUSIVE", "toAmount": "492.539528", "fee": [ { "asset": { "blockchain": "BSC", "symbol": "USDC", "address": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d" }, "expenseType": "DECREASE_FROM_OUTPUT", "amount": "0.2214360964860255103480", "name": "Swapper Fee", "price": 0.999239 }, { "asset": { "blockchain": "BSC", "symbol": "BNB", "address": null }, "expenseType": "FROM_SOURCE_WALLET", "amount": "0.000205356800000000", "name": "Network Fee", "meta": { "type": "EvmNetworkFeeMeta", "gasLimit": "186688", "gasPrice": "1100000000" }, "price": 493.27 } ], "estimatedTimeInSeconds": 180, "swapChainType": "INTRA_CHAIN", "routes": null, "recommendedSlippage": null, "warnings": [], "timeStat": { "min": 59, "avg": 177, "max": 543 }, "includesDestinationTx": false, "internalSwaps": null, "maxRequiredSign": 1 }, { "swapperId": "AvaxChainV3", "swapperLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/UniSwapV2/icon.svg", "swapperType": "DEX", "from": { "symbol": "USDC", "logo": "https://rango.vip/i/j9eYAa", "blockchainLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/AVAX_CCHAIN/icon.svg", "address": "0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e", "blockchain": "AVAX_CCHAIN", "decimals": 6, "usdPrice": 1.0 }, "to": { "symbol": "USDT.E", "logo": "https://rango.vip/i/GJxbOP", "blockchainLogo": "https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/AVAX_CCHAIN/icon.svg", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118", "blockchain": "AVAX_CCHAIN", "decimals": 6, "usdPrice": 1.0 }, "fromAmount": "492.539528", "fromAmountPrecision": null, "fromAmountMinValue": null, "fromAmountMaxValue": null, "fromAmountRestrictionType": null, "toAmount": "492.147292", "fee": [ { "asset": { "blockchain": "AVAX_CCHAIN", "symbol": "AVAX", "address": null }, "expenseType": "FROM_SOURCE_WALLET", "amount": "0.010380480000000000", "name": "Network Fee", "meta": { "type": "EvmNetworkFeeMeta", "gasLimit": "377472", "gasPrice": "27500000000" }, "price": 21.53 } ], "estimatedTimeInSeconds": 60, "swapChainType": "INTER_CHAIN", "routes": [ { "nodes": [ { "nodes": [ { "marketName": "AvaxChainV3", "marketId": "AvaxChainV3", "percent": 1.0, "pools": [ "0xb2dc1235bf4b36628a8665aeb668bf202759528a" ], "inputAmount": "492539528", "outputAmount": "492147292" } ], "from": "USDC", "fromLogo": "", "fromAddress": "0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e", "fromBlockchain": "AVAX_CCHAIN", "to": "USDT.E", "toLogo": "", "toAddress": "0xc7198437980c041c805a1edcba50c1ce5db95118", "toBlockchain": "AVAX_CCHAIN" } ] } ], "recommendedSlippage": null, "warnings": [], "timeStat": { "min": 2, "avg": 47, "max": 360 }, "includesDestinationTx": false, "internalSwaps": null, "maxRequiredSign": 1 } ], "resultType": "OK", "scores": [ { "preferenceType": "NET_OUTPUT", "score": 100 }, { "preferenceType": "FEE", "score": 72 }, { "preferenceType": "SPEED", "score": 48 }, { "preferenceType": "PRICE", "score": 100 }, { "preferenceType": "SMART", "score": 100 } ], "tags": [ { "label": "Recommended", "value": "RECOMMENDED" } ], "walletNotSupportingFromBlockchain": false, "missingBlockchains": [] }, ], "diagnosisMessages": [], "error": null, "errorCode": null, "traceId": null } ``` {% endtab %} {% endtabs %} # Confirm Route Confirm the desired route by the user and pass user's wallets for executing the route ## Confirm Route API After presenting the best route or all possible routes to the user, and once the user confirms the swap via one of the routes, you need to call this method using the user's selected wallets and the request ID of the chosen route. This will inform Rango that the user has confirmed this route and initiate the swap execution. You can also pass the destination field to set a custom destination for the final output, which can be different from the selected wallets. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const confimedRoute = await rango.confirmRoute({ requestId: "33e0b996-da5e-4922-9fdc-f7206247fc34", selectedWallets: { "BSC": "0xeae6d42093eae057e770010ffd6f4445f7956613", "AVAX_CCHAIN": "0xeae6d42093eae057e770010ffd6f4445f7956613", }, destination: "0x6f33bb1763eebead07cf8815a62fcd7b30311fa3", }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.post( 'https://api.rango.exchange/routing/confirm', { 'requestId': '33e0b996-da5e-4922-9fdc-f7206247fc34', 'selectedWallets': { 'BSC': '0xeae6d42093eae057e770010ffd6f4445f7956613', 'AVAX_CCHAIN': '0xeae6d42093eae057e770010ffd6f4445f7956613' }, 'destination': '0x6f33bb1763eebead07cf8815a62fcd7b30311fa3', }, { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' }, headers: { 'content-type': 'application/json' } } ); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request POST \ --url 'https://api.rango.exchange/routing/confirm?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' \ --header 'content-type: application/json' \ --data ' { "selectedWallets": { "BSC": "0xeae6d42093eae057e770010ffd6f4445f7956613", "AVAX_CCHAIN": "0xeae6d42093eae057e770010ffd6f4445f7956613" }, "destination": "0x6f33bb1763eebead07cf8815a62fcd7b30311fa3", "requestId": "33e0b996-da5e-4922-9fdc-f7206247fc34" } ' ``` {% endtab %} {% endtabs %} {% embed url="" %} Route Confirmation Swagger {% endembed %} ### Confirm Route Request {% tabs %} {% tab title="API Definition" %} * **`requestId`** \* String * Description: The unique ID for the selected route. (In the response of best route or best routes endpoints.) * **`selectedWallets`** \* Object * Description: The list of user's selected wallets for this swap. For a multi-step swap, we need to have wallet address of every blockchain in the route. (Blockchain to wallet address map) * **`destination`** String * Description: Custom wallet address destination for the final output of the route. (If you want to set a wallet address different than selected wallet addresses) {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type ConfirmRouteRequest = { requestId: string selectedWallets: { [key: string]: string } destination?: string } ``` {% endtab %} {% endtabs %} ### Confirm Route Response {% tabs %} {% tab title="API Definition" %} * **`ok`** * Description: If true, route confirmation was successful and error message is null. * **`result`** * Description: The updated route. * **`error`** * Description: Error occurred during confirming the route. * **`errorCode`** * Description: Error code shows the type of error. * **`traceId`** * Description: Trace Id helps Rango support team to trace the issue. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type ConfirmRouteResponse = { ok: boolean result: Omit | null error: string | null errorCode: string | null traceId: number | null } 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 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 SwapFee = { name: string expenseType: ExpenseType asset: Asset amount: string price: number | null meta: EVMFeeMeta | null } export type ExpenseType = | 'FROM_SOURCE_WALLET' | 'DECREASE_FROM_OUTPUT' | 'FROM_DESTINATION_WALLET' export type EVMFeeMeta = { type: "EvmNetworkFeeMeta", gasLimit: string, gasPrice: string } export type TimeStat = { min: number avg: number max: number } 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 } ``` {% endtab %} {% tab title="Sample Response" %} ```json { "ok":true, "error":null, "errorCode":null, "traceId":null, "result":{ "from":{ "blockchain":"BSC", "symbol":"BNB", "address":null }, "to":{ "blockchain":"AVAX_CCHAIN", "symbol":"AVAX", "address":null }, "requestAmount":"1", "requestId":"a4abd8bc-e743-4fca-ae0e-5f781d9cdd0a", "result":{ "outputAmount":"22.750365244468519211", "swaps":[ { "swapperId":"BSCPancakeV3", "swapperLogo":"https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/Pancake/icon.svg", "swapperType":"DEX", "from":{ "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.75 }, "to":{ "symbol":"USDC", "logo":"https://rango.vip/i/e4x0s8", "blockchainLogo":"https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg", "address":"0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d", "blockchain":"BSC", "decimals":18, "usdPrice":1.002 }, "fromAmount":"1", "fromAmountPrecision":null, "fromAmountMinValue":null, "fromAmountMaxValue":null, "fromAmountRestrictionType":null, "toAmount":"492.564957917070936228", "fee":[ { "asset":{ "blockchain":"BSC", "symbol":"BNB", "address":null }, "expenseType":"DECREASE_FROM_OUTPUT", "amount":"0.0015", "name":"Rango Fee", "price":493.75 }, { "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.75 } ], "estimatedTimeInSeconds":30, "swapChainType":"INTER_CHAIN", "routes":[ { "nodes":[ { "nodes":[ { "marketName":"BSCPancakeV3", "marketId":"BSCPancakeV3", "percent":1.0, "pools":[ "0xf2688fb5b81049dfb7703ada5e770543770612c4" ], "inputAmount":"998500000000000000", "outputAmount":"492564957917070936228" } ], "from":"BNB", "fromLogo":"", "fromAddress":null, "fromBlockchain":"BSC", "to":"USDC", "toLogo":"", "toAddress":"0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d", "toBlockchain":"BSC" } ] } ], "recommendedSlippage":null, "warnings":[ ], "timeStat":null, "includesDestinationTx":false, "internalSwaps":null, "maxRequiredSign":1 }, { "swapperId":"XY Finance", "swapperLogo":"https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/XY Finance/icon.svg", "swapperType":"BRIDGE", "from":{ "symbol":"USDC", "logo":"https://rango.vip/i/e4x0s8", "blockchainLogo":"https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/BSC/icon.svg", "address":"0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d", "blockchain":"BSC", "decimals":18, "usdPrice":1.002 }, "to":{ "symbol":"USDC", "logo":"https://rango.vip/i/j9eYAa", "blockchainLogo":"https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/AVAX_CCHAIN/icon.svg", "address":"0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e", "blockchain":"AVAX_CCHAIN", "decimals":6, "usdPrice":1.0 }, "fromAmount":"492.564957917070936228", "fromAmountPrecision":null, "fromAmountMinValue":"0.215999999999999992006394222698872908949851989746093750", "fromAmountMaxValue":"4245.273839", "fromAmountRestrictionType":"EXCLUSIVE", "toAmount":"492.343221", "fee":[ { "asset":{ "blockchain":"BSC", "symbol":"USDC", "address":"0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d" }, "expenseType":"DECREASE_FROM_OUTPUT", "amount":"0.2217364957917070936228", "name":"Swapper Fee", "price":1.002 }, { "asset":{ "blockchain":"BSC", "symbol":"BNB", "address":null }, "expenseType":"FROM_SOURCE_WALLET", "amount":"0.000205356800000000", "name":"Network Fee", "meta":{ "type":"EvmNetworkFeeMeta", "gasLimit":"186688", "gasPrice":"1100000000" }, "price":493.75 } ], "estimatedTimeInSeconds":600, "swapChainType":"INTRA_CHAIN", "routes":null, "recommendedSlippage":null, "warnings":[ ], "timeStat":null, "includesDestinationTx":false, "internalSwaps":null, "maxRequiredSign":1 }, { "swapperId":"AvaxChainV3", "swapperLogo":"https://raw.githubusercontent.com/rango-exchange/assets/main/swappers/UniSwapV2/icon.svg", "swapperType":"DEX", "from":{ "symbol":"USDC", "logo":"https://rango.vip/i/j9eYAa", "blockchainLogo":"https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/AVAX_CCHAIN/icon.svg", "address":"0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e", "blockchain":"AVAX_CCHAIN", "decimals":6, "usdPrice":1.0 }, "to":{ "symbol":"AVAX", "logo":"https://api.rango.exchange/tokens/AVAX/AVAX.png", "blockchainLogo":"https://raw.githubusercontent.com/rango-exchange/assets/main/blockchains/AVAX_CCHAIN/icon.svg", "address":null, "blockchain":"AVAX_CCHAIN", "decimals":18, "usdPrice":21.56 }, "fromAmount":"492.343221", "fromAmountPrecision":null, "fromAmountMinValue":null, "fromAmountMaxValue":null, "fromAmountRestrictionType":null, "toAmount":"22.750365244468519211", "fee":[ { "asset":{ "blockchain":"AVAX_CCHAIN", "symbol":"AVAX", "address":null }, "expenseType":"FROM_SOURCE_WALLET", "amount":"0.010380480000000000", "name":"Network Fee", "meta":{ "type":"EvmNetworkFeeMeta", "gasLimit":"377472", "gasPrice":"27500000000" }, "price":21.56 } ], "estimatedTimeInSeconds":30, "swapChainType":"INTER_CHAIN", "routes":[ { "nodes":[ { "nodes":[ { "marketName":"AvaxChainV3", "marketId":"AvaxChainV3", "percent":1.0, "pools":[ "0xfae3f424a0a47706811521e3ee268f00cfb5c45e" ], "inputAmount":"492343221", "outputAmount":"22750365244468519211" } ], "from":"USDC", "fromLogo":"", "fromAddress":"0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e", "fromBlockchain":"AVAX_CCHAIN", "to":"AVAX", "toLogo":"", "toAddress":null, "toBlockchain":"AVAX_CCHAIN" } ] } ], "recommendedSlippage":null, "warnings":[ ], "timeStat":null, "includesDestinationTx":false, "internalSwaps":null, "maxRequiredSign":1 } ], "resultType":"OK" }, "validationStatus":[ { "blockchain":"BSC", "wallets":[ { "address":"0xccf3d872b01762aba74b41b1958a9a86ee8f34a3", "requiredAssets":[ { "asset":{ "blockchain":"BSC", "symbol":"BNB", "address":null }, "requiredAmount":{ "amount":"1000611952000000000", "decimals":18 }, "currentAmount":{ "amount":"54842791773041088", "decimals":18 }, "reason":"FEE_AND_INPUT_ASSET", "ok":false } ], "addressIsValid":true, "validResult":true } ] }, { "blockchain":"AVAX_CCHAIN", "wallets":[ { "address":"0xccf3d872b01762aba74b41b1958a9a86ee8f34a3", "requiredAssets":[ { "asset":{ "blockchain":"AVAX_CCHAIN", "symbol":"AVAX", "address":null }, "requiredAmount":{ "amount":"10380480000000000", "decimals":18 }, "currentAmount":{ "amount":"1101940113660760969", "decimals":18 }, "reason":"FEE", "ok":true } ], "addressIsValid":true, "validResult":true } ] } ], "walletNotSupportingFromBlockchain":false, "missingBlockchains":[ ], "diagnosisMessages":[ ] } } ``` {% endtab %} {% endtabs %} # Create Transaction Create the transaction for current step ## Create Transaction API When a user starts swapping or when a step of swap succeeds, to get the transaction for the next step, this method should be called. In multi-step routes, you should loop over the `routeResponse.route` array and call this method (`createTransaction`) per each step. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const transaction = await rango.createTransaction({ requestId: "1978d8fa-335d-4915-a039-77f1a17315f5", // bestRoute.requestId step: 1, userSettings: { slippage: 3, infiniteApprove: false }, validations: { balance: true, fee: true, approve: true }, }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.post( 'https://api.rango.exchange/tx/create', { 'requestId': '1978d8fa-335d-4915-a039-77f1a17315f5', 'step': 1, 'userSettings': { 'slippage': 3, 'infiniteApprove': false }, 'validations': { 'balance': true, 'fee': true, 'approve': true } }, { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' }, headers: { 'content-type': 'application/json' } } ); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request POST \ --url 'https://api.rango.exchange/tx/create?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' \ --header 'content-type: application/json' \ --data ' { "requestId": "1978d8fa-335d-4915-a039-77f1a17315f5", "userSettings": { "slippage": 3, "infiniteApprove": false }, "validations": { "balance": true, "fee": true, "approve": true }, "step": 1 } ' ``` {% endtab %} {% endtabs %} {% embed url="" %} Create Transaction Swagger {% endembed %} ### Create Transaction Request {% tabs %} {% tab title="API Definition" %} * **`requestId`** \* String * Description: The unique ID which is generated in the best route endpoint. * **`step`** \* Number * Description: The current step number in a multi-step route, starting from 1. * Example: `1` * **`userSettings`** \* * Description: User settings for the swap, including slippage and infinite approval. * **`validations`** \* * Description: The validation checks we are interested to check by Rango before starting the swap. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type CreateTransactionRequest = { requestId: string step: number userSettings: UserSettings validations: CreateTransactionValidation } export type UserSettings = { slippage: string infiniteApprove?: boolean } export type CreateTransactionValidation = { balance: boolean fee: boolean approve: boolean } ``` {% endtab %} {% endtabs %} ### Create Transaction Response {% tabs %} {% tab title="API Definition" %} * **`ok`** * Description: If true, Rango has created a non-null transaction, and the error message is null. * **`transaction`** * Description: Transaction's raw data. It is one of the transaction possible interfaces: `EvmTransaction`, `CosmosTransaction,` `TransferTransaction` (for UTXO), `SolanaTransaction`, `StarknetTransaction`, `TronTransaction` or `null`. * **`error`** * Description: Error message about the incident if ok == false. * **`errorCode`** * Description: Error code shows the type of error. * **`traceId`** * Description: Trace Id helps Rango support team to trace an issue. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type CreateTransactionResponse = { error: string | null ok: boolean transaction: Transaction | null } export type Transaction = | EvmTransaction | CosmosTransaction | SolanaTransaction | TronTransaction | StarknetTransaction | TonTransaction | Transfer export interface BaseTransaction { type: TransactionType blockChain: string } export interface EvmTransaction extends BaseTransaction { type: TransactionType.EVM isApprovalTx: boolean from: string | null to: string data: string | null value: string | null nonce: string | null gasLimit: string | null gasPrice: string | null maxPriorityFeePerGas: string | null maxFeePerGas: string | null } export interface SolanaTransaction extends BaseTransaction { type: TransactionType.SOLANA txType: 'LEGACY' | 'VERSIONED' from: string identifier: string recentBlockhash: string | null signatures: SolanaSignature[] serializedMessage: number[] | null instructions: SolanaInstruction[] } export interface CosmosTransaction extends BaseTransaction { type: TransactionType.COSMOS fromWalletAddress: string data: CosmosMessage rawTransfer: CosmosRawTransferData | null } export interface TronTransaction extends BaseTransaction { type: TransactionType.TRON isApprovalTx: boolean raw_data: TrxRawData | null raw_data_hex: string | null txID: string visible: boolean __payload__: object } export interface StarknetTransaction extends BaseTransaction { type: TransactionType.STARKNET isApprovalTx: boolean calls: StarknetCallData[] } export interface TonTransaction extends BaseTransaction { type: TransactionType.TON validUntil: number network?: TonChainID from?: string messages: TonMessage[] } export interface Transfer extends BaseTransaction { type: TransactionType.TRANSFER method: string asset: AssetWithTicker amount: string decimals: number fromWalletAddress: string recipientAddress: string memo: string | null } ``` {% endtab %} {% tab title="Sample Response" %} {% content-ref url="/pages/aUairuEGG5JTWVqIVUZE" %} [Sample Transactions](/api-integration/main-api-multi-step/sample-transactions) {% endcontent-ref %} {% endtab %} {% endtabs %} # Check Transaction Status Track the status of the transaction for the current step ## Check Status API After the user signs a transaction in his wallet, you should periodically call this endpoint to check the status of the transaction. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const transaction = await rango.checkStatus({ requestId: "b3a12c6d-86b8-4c21-97e4-809151dd4036", // bestRoute.requestId step: 1, txId: "0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5" }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.post( 'https://api.rango.exchange/tx/check-status', { 'requestId': 'b3a12c6d-86b8-4c21-97e4-809151dd4036', 'txId': '0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5', 'step': 1 }, { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' }, headers: { 'content-type': 'application/json' } } ); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request POST \ --url 'https://api.rango.exchange/tx/check-status?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' \ --header 'content-type: application/json' \ --data ' { "requestId": "b3a12c6d-86b8-4c21-97e4-809151dd4036", "txId": "0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5", "step": 1 } ' ``` {% endtab %} {% endtabs %} {% embed url="" %} Check Transaction Status Swagger {% endembed %} {% hint style="info" %} * This endpoint is not suitable for checking approve transaction and it is only for the main transaction. For checking approval transaction status, please [check this section](/api-integration/main-api-multi-step/api-reference/create-transaction#check-approval-status). * In on-chain transactions, you could also check transaction status by checking transaction receipt (via RPC) if you prefer. But in cross-chain swaps (e.g. bridges), you could use this method to make sure outbound transaction (transaction on destination chain) succeeds without any problem. {% endhint %} ### Check Transaction Status Request {% tabs %} {% tab title="API Definition" %} * **`requestId`** \* String * Description: The unique ID which is generated in the best route endpoint. * Example: `b3a12c6d-86b8-4c21-97e4-809151dd4036` * **`step`** \* Number * Description: The current step number in a multi-step route, starting from 1. * Example: `1` * **`txId`** \* String * Description: Transaction hash returned by wallet * Example: `0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5` {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type CheckTxStatusRequest = { requestId: string step: number txId: string } ``` {% endtab %} {% endtabs %} ### Check Transaction Status Response {% tabs %} {% tab title="API Definition" %} * **`status`** * Description: Status of the transaction, while the status is `running` or `null`, the client should retry until it turns into `success` or `failed`. * **`timestamp`** * Description: The timestamp of the executed transaction. Beware that timestamp can be null even if the status is successful or failed, e.g. `1690190660000` * **`extraMessage`** * Description: A message in case of failure, that could be shown to the user. * **`outputAmount`** * Description: The human readable output amount for the transaction, e.g. 0.28. * **`outputToken`** * Description: The output token for this step. * **`newTx`** * Description: if a transaction needs more than one-step transaction to be signed by the user, the next step transaction will be returned in this field. \ It's only used for the Voyager bridge at the moment, and you could simply avoid swappers with this requirement by passing `disableMultiStepTx` equals to `true` in get best route method * **`diagnosisUrl`** * Description: In some special cases (e.g. Wormhole), the user should follow some steps outside Rango to get its assets back (to refund). You could show this link to the user to help him.\ Sample value: * **`explorerUrl`** * Description: List of explorer URLs for the transactions that happened in this step. * **`referrals`** * Description: List of referral reward for the dApp and Rango. * **`steps`** * Description: In certain special cases (specifically for the Wormhole Bridge), the user must sign multiple transactions for a step to be successful. In these instances, you can use the steps data to display the internal steps of a single swap to the user for informational purposes. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type TransactionStatusResponse = { status: TransactionStatus | null timestamp: number | null extraMessage: string | null outputAmount: string | null outputToken: Token | null outputType: null | 'REVERTED_TO_INPUT' | 'MIDDLE_ASSET_IN_SRC' | 'MIDDLE_ASSET_IN_DEST' | 'DESIRED_OUTPUT' newTx: Transaction | null diagnosisUrl: string | null explorerUrl: SwapExplorerUrl[] | null referrals: TransactionStatusReferral[] | null steps: SwapperStatusStep[] | null } export enum TransactionStatus { FAILED = 'failed', RUNNING = 'running', SUCCESS = 'success', } export type SwapExplorerUrl = { description: string | null url: string } export type TransactionStatusReferral = { blockChain: string address: string | null symbol: string decimals: number amount: string } export type SwapperStatusStep = { name: string state: 'PENDING' | 'CREATED' | 'WAITING' | 'SIGNED' | 'SUCCESSED' | 'FAILED' current: boolean } ``` {% endtab %} {% tab title="Sample Response" %} ```json { "status": "success", "extraMessage": null, "failedType": null, "timestamp": 1725780628000, "outputAmount": "0.001961697012221780", "explorerUrl": [ { "url": "https://lineascan.build/tx/0xac125a7cc5fa1b99888b406bad06f5e5db29eb0aa24bcce7004a4108ac68dd0f", "description": "Swap" } ], "referrals": [ { "amount": "3000000000000", "blockChain": "LINEA", "symbol": "ETH", "address": null, "decimals": 18, "type": "RANGO" }, { "amount": "2000000000000", "blockChain": "LINEA", "symbol": "ETH", "address": null, "decimals": 18, "type": "AFFILIATE" } ], "newTx": null, "diagnosisUrl": null, "steps": null, "outputToken": { "blockchain": "LINEA", "symbol": "EZETH", "image": "https://tokens.pancakeswap.finance/images/linea/0x2416092f143378750bb29b79eD961ab195CcEea5.png", "address": "0x2416092f143378750bb29b79ed961ab195cceea5", "usdPrice": 2328.63, "decimals": 18, "name": null, "isPopular": false, "isSecondaryCoin": false, "coinSource": null, "coinSourceUrl": null, "supportedSwappers": [] }, "outputType": "DESIRED_OUTPUT", "bridgeExtra": { "requireRefundAction": false, "srcTx": "0xac125a7cc5fa1b99888b406bad06f5e5db29eb0aa24bcce7004a4108ac68dd0f", "destTx": null }, "error": null, "errorCode": null, "traceId": null } ``` {% endtab %} {% endtabs %} # Check Approve Transaction Status Check status of approve transaction ## Check Approval Status API When `createTransaction` returns an `approval` transaction (i.e. `isApproval`field is `true` in transaction), and the user signs that transaction, you could periodically call check-approval to see if the approval transaction is completed. After a successful check, you should call `createTransaction` again to receive the main transaction. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const transaction = await rango.checkApproval({ requestId: "b3a12c6d-86b8-4c21-97e4-809151dd4036", // bestRoute.requestId txId: "0x7f17aaba51d1f24204cd8b02251001d3704add46d84840a5826b95ef49b8b74f" // optional }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.get('https://api.rango.exchange/tx/b3a12c6d-86b8-4c21-97e4-809151dd4036/check-approval', { params: { 'txId': '0x7f17aaba51d1f24204cd8b02251001d3704add46d84840a5826b95ef49b8b74f', 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/tx/b3a12c6d-86b8-4c21-97e4-809151dd4036/check-approval?txId=0x7f17aaba51d1f24204cd8b02251001d3704add46d84840a5826b95ef49b8b74f&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} Check Approve Transaction Status {% endembed %} {% hint style="info" %} For checking approval transaction status, you could check it directly from the RPC endpoint if you prefer and skip calling Rango API for this purpose. {% endhint %} {% hint style="warning" %} **Caution** 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 route. {% endhint %} You could stop checking approval method if: * Approval transaction succeeded. => `isApproved === true` * Approval transaction failed. => `!isApproved && txStatus === 'failed'` * Approval transaction succeeded but `currentApprovedAmount` is still less than `requiredApprovedAmount` (e.g. user changed transaction data in wallet and enter another approve amount in MetaMask instead of default approve amount proposed by Rango API) => `!isApproved && txStatus === 'success'` ### Check Approval Request {% tabs %} {% tab title="API Definition" %} * **`requestId`** \* * Description: The unique ID which is generated in the best route endpoint. * Example: `b3a12c6d-86b8-4c21-97e4-809151dd4036` * **`txId`** * Description: Transaction hash returned by wallet * Example: `0x7f17aaba51d1f24204cd8b02251001d3704add46d84840a5826b95ef49b8b74f` {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript public async checkApproval( requestId: string, txId?: string ): Promise; ``` {% endtab %} {% endtabs %} ### Check Approval Response {% tabs %} {% tab title="API Definition" %} * **`isApproved`** * Description: A flag which indicates that the approve tx is done or not. * **`txStatus`** * Description: Status of approve transaction in blockchain (possible values are `success`, `running` and `failed`) if `isArppoved` is false and `txStatus` is `failed`, it means that approve transaction is failed in the blockchain. * **`currentApprovedAmount`** * Description: Required amount to be approved by the user. * **`requiredApprovedAmount`** * Description: Current approved amount by the user. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type CheckApprovalResponse = { isApproved: boolean txStatus: TransactionStatus | null requiredApprovedAmount: string | null currentApprovedAmount: string | null } export enum TransactionStatus { FAILED = 'failed', RUNNING = 'running', SUCCESS = 'success', } ``` {% endtab %} {% tab title="Sample Response" %} ```json { "isApproved": true, "txStatus": "suuccess", "currentApprovedAmount": 100020003000, "requiredApprovedAmount": 100020003000 } ``` {% endtab %} {% endtabs %} # Report Transaction Failure Report failures on signing or sending the transaction ## Report Failure API Use it when the user rejects the transaction in the wallet or the wallet fails to handle the transaction. Calling this endpoint is not required, but is useful for reporting and we recommend calling it. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const transaction = await rango.reportFailure({ requestId: "688b308e-a06b-4a4e-a837-220d458b8642", // bestRoute.requestId eventType: 'SEND_TX_FAILED', reason: "RPC Error" }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.post( 'https://api.rango.exchange/tx/report-tx', { 'requestId': '688b308e-a06b-4a4e-a837-220d458b8642', 'step': 1, 'eventType': 'SEND_TX_FAILED', 'reason': 'RPC Error' }, { params: { 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' }, headers: { 'content-type': 'application/json' } } ); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request POST \ --url 'https://api.rango.exchange/tx/report-tx?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' \ --header 'content-type: application/json' \ --data ' { "requestId": "688b308e-a06b-4a4e-a837-220d458b8642", "step": 1, "eventType": "SEND_TX_FAILED", "reason": "RPC Error" } ' ``` {% endtab %} {% endtabs %} {% embed url="" %} Report Failure Swagger {% endembed %} {% hint style="info" %} It's an optional action and does not affect the flow of swap, but it can help us improve our API if the data is informative enough {% endhint %} ### Report Failure Request {% tabs %} {% tab title="API Definition" %} * **`requestId`** \* * Description: The unique ID which is generated in the best route endpoint. * **`eventType`** \* * Description: Type of failure. possible values are: `FETCH_TX_FAILED, USER_REJECT, USER_CANCEL, CALL_WALLET_FAILED, SEND_TX_FAILED, CLIENT_UNEXPECTED_BEHAVIOUR, TX_EXPIRED, INSUFFICIENT_APPROVE` * **`reason`** * Description: Failure reason * **`tags`** * Description: An optional dictionary of pre-defined tags. Current allowed tags are `wallet` and `errorCode`. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type ReportTransactionRequest = { requestId: string eventType: APIErrorCode step?: number reason?: string tags?: { wallet?: string; errorCode?: string } } ``` {% endtab %} {% endtabs %} # Get Custom Token Get metadata of a custom token ## Custom Token API Provides token details for a user-specified token that is not included in Rango's official list. Currently supports blockchains based on Solana and EVM. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const tokenResponse = await rango.getCustomToken({ "blockchain": "SOLANA", "address": "3yoMkf3X6bDxjks6YaWwNk4SAbuaysLg1a4BjQKToQAA" }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.get('https://api.rango.exchange/meta/custom-token', { params: { 'blockchain': 'SOLANA', 'address': '3yoMkf3X6bDxjks6YaWwNk4SAbuaysLg1a4BjQKToQAA', 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/meta/custom-token?blockchain=SOLANA&address=3yoMkf3X6bDxjks6YaWwNk4SAbuaysLg1a4BjQKToQAA&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} Custom Token Swagger {% endembed %} ### Custom Token Request {% tabs %} {% tab title="API Definition" %} * **`blockchain`**\* String * Description: The blockchain which the token belongs to. * Example: `SOLANA` * **`address`**\* String * Description: Smart contract address of the token. * Example: `3yoMkf3X6bDxjks6YaWwNk4SAbuaysLg1a4BjQKToQAA` {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type CustomTokenRequest = { blockchain: string address: string } ``` {% endtab %} {% endtabs %} ### Custom Token Response {% tabs %} {% tab title="API Definition" %} * **`token`** * Description: The token's metadata * **`error`** * Description: Error message if there was any problem * **`errorCode`** * Description: Error code if there was any problem * **`traceId`** * Description: Trace id help Rango support to resolve the issue {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type CustomTokenResponse = { token: Token error: string | null errorCode: number | null traceId: number | null } export type Token = { blockchain: string address: string | null symbol: string name: string | null decimals: number image: string usdPrice: number | null isSecondaryCoin: boolean coinSource: string | null coinSourceUrl: string | null isPopular: boolean supportedSwappers?: string[] } ``` {% endtab %} {% tab title="Sample Response" %} ```json { "token": { "blockchain": "SOLANA", "symbol": "Brett", "image": "https://bafkreifi5rkzrqyze3cqoqt5xm6ullqpyh5g52ut46pmwva6cju2yyy3ay.ipfs.nftstorage.link", "address": "3yoMkf3X6bDxjks6YaWwNk4SAbuaysLg1a4BjQKToQAA", "usdPrice": null, "decimals": 9, "name": "Brett", "isPopular": false, "isSecondaryCoin": true, "coinSource": null, "coinSourceUrl": null, "supportedSwappers": [] }, "error": null, "errorCode": null, "traceId": null } ``` {% endtab %} {% endtabs %} # Get Address Token Balance Get details of a list of wallets, including their explorer Url & balance ## Get Wallets Details API Use this method if you want to get all tokens of a list of wallet addresses for some desired blockchains. Note that this endpoint is slow since it queries for all tokens an address is holding and balance of each one. We recommend to call the RPC directly or use single token balance method whenever possible. {% tabs %} {% tab title="Typescript (SDK)" %} ```typescript const walletDetails = await rangoClient.getWalletsDetails({ walletAddresses: [{ blockchain: "BSC", address: "0xeb2629a2734e272bcc07bda959863f316f4bd4cf" }] }) ``` {% endtab %} {% tab title="Node.js (Axios)" %} ```typescript const response = await axios.get('https://api.rango.exchange/wallets/details', { params: { 'address': 'BSC.0xeb2629a2734e272bcc07bda959863f316f4bd4cf', 'apiKey': 'c6381a79-2817-4602-83bf-6a641a409e32' } }); ``` {% endtab %} {% tab title="Bash (cURL)" %} ```bash curl --request GET \ --url 'https://api.rango.exchange/wallets/details?address=BSC.0xeb2629a2734e272bcc07bda959863f316f4bd4cf&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' ``` {% endtab %} {% endtabs %} {% embed url="" %} ### Wallets Details Request {% tabs %} {% tab title="API Definition" %} * **`walletAddresses`** \* * Description: List of user wallet addresses for desired blockchains. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript public async getWalletsDetails( walletAddresses: WalletAddresses ): Promise; type WalletAddresses = { blockchain: string; address: string }[] ``` {% endtab %} {% endtabs %} ### Wallets Details Response {% tabs %} {% tab title="API Definition" %} * **`wallets`** * Description: List of wallets and their assets. {% endtab %} {% tab title="SDK Models (Typescript)" %} ```typescript export type WalletDetailsResponse = { wallets: WalletDetail[] } export type WalletDetail = { failed: boolean blockChain: string address: string balances: AssetAndAmount[] | null explorerUrl: string } export type AssetAndAmount = { amount: Amount asset: Asset } export type Amount = { amount: string decimals: number } export type Asset = { blockchain: string address: string | null symbol: string } ``` {% endtab %} {% tab title="Sample Response" %} ```json { "wallets": [ { "blockChain": "BSC", "address": "0xeb2629a2734e272bcc07bda959863f316f4bd4cf", "failed": false, "explorerUrl": "https://bscscan.com/address/0xeb2629a2734e272bcc07bda959863f316f4bd4cf", "balances": [ { "asset": { "blockchain": "BSC", "symbol": "BNB", "address": null }, "amount": { "amount": "7127850000000000", "decimals": 9 } }, { "asset": { "blockchain": "BSC", "symbol": "XYZ", "address": "0x43fdec959a53092722d79ebd2bc0521719adc681" }, "amount": { "amount": "21000000000", "decimals": 6 } } ] } ] } ``` {% endtab %} {% endtabs %} # Tutorial Main API Tutorial # SDK Example SDK Example for Integrating Rango Exchange ## Overview You could read this guide to understand the flow of integrating Rango-SDK. If you prefer to dive directly into the code and explore it there, you can use the links below. {% embed url="" %} EVM Example {% endembed %} ## Install TS SDK If you decide not to use our TypeScript SDK and prefer integration in other programming languages, feel free to skip this step. To integrate Rango SDK inside your dApp or wallet, you need to install `rango-sdk` using npm or yarn. ```bash npm install --save rango-sdk # or yarn add rango-sdk ``` Then you need to instantiate `RangoClient` and use it in the next steps. ```typescript import { RangoClient } from "rango-sdk" const rango = new RangoClient(RANGO_API_KEY) ``` ## Get Tokens & Blockchains Data To get the list of available blockchains, tokens, and protocols (dex or bridge) supported by Rango, you could use the [getAllMetadata](/api-integration/main-api-multi-step/api-reference/get-blockchains-and-tokens) method like this: ```typescript const meta = await rango.getAllMetadata() ``` ## Routing ### Get All Routes Using information retrieved from the meta, you could implement your own SwapBox including your blockchain and token selector. The next step is to show the preview of the best route possible when the user selects the source and the destination tokens. The *blockchain* and *symbol* names must be exactly what is fetched from Rango's Meta API. ```typescript // Converting 0.1 BSC BNB to AVAX_CCHAIN USDT.E const routingResponse = await rango.getAllRoutes({ from: { "blockchain": "BSC", "symbol": "BNB", "address": null }, to: { "blockchain": "AVAX_CCHAIN", "symbol": "USDT.E", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118" }, amount: "0.1", slippage: "1.0", }) ``` You could call this method periodically to get the updated route before the user confirms the route. ### Confirm Route Using the `getAllRoutes` method, you obtain a list of available routes. Once the user selects and confirms a route, you need to call the [confirm](/api-integration/main-api-multi-step/api-reference/confirm-route) method to notify Rango that the user has chosen this route for the next step and retrieve the final, updated route to display to the user. To confirm the route, you must provide the selected route's request ID, the wallet addresses for all blockchains in the route, and optionally, a custom destination if the user wishes to send funds to a different wallet than the one specified for the related blockchain (in `selectedWallets`). ```typescript // user selects one of the routes const selectedRoute = routingResponse.results[0] const confirmResponse = await rango.confirmRoute({ requestId: selectedRoute.requestId, selectedWallets: { 'BSC': '0xeae6d42093eae057e770010ffd6f4445f7956613', 'AVAX_CCHAIN': '0xeae6d42093eae057e770010ffd6f4445f7956613' }, destination: '0x6f33bb1763eebead07cf8815a62fcd7b30311fa3' }) ``` At this stage, it is also possible to verify if the user has sufficient balance and fees for each step of the route in advance based on confirm response validation field. Also, you can compare the confirmed route with the route's output amount and alert the user if there is a significant difference. ```typescript // check if the route was okay if (!confirmResponse.result || confirmResponse.error) { // there was a problem in confirming the route } else { // everything was okay // you could compare confirmed route with the route output amount // and warn the user if there is noticable difference // e.g. check if confirmed route output is 2% less than previous one const confirmedOutput = new BigNumber(routingResponse.results[selected]?.outputAmount) const finalOutput = new BigNumber(confirmResponse.result?.outputAmount) if (finalOutput.lt(confirmedOutput.multipliedBy(new BigNumber(0.98))) { // get double confirmation from the user } else { // proceed to executing the route } } ``` ## Route Execution For every steps of the selected route, we need to repeat the next steps: ### Creating Transaction If the source blockchain for this step requires approval, such as EVM-based blockchains, Starknet, or Tron, and the user lacks sufficient approval, the Rango API will return an approval transaction in the response. The user must sign this transaction, and in the next [createTransaction](/api-integration/main-api-multi-step/api-reference/create-transaction) call for this step, the Rango API will provide the main transaction. Therefore, the createTransaction API response could either be an approval transaction (`isApproval=true`) or the main transaction (`isApproval=false`). ```typescript const request: CreateTransactionRequest = { requestId: confirmedRoute.requestId, step: 1, // 1, 2, 3, ... userSettings: { slippage: '1.0', infiniteApprove: false }, validations: { approve: true, balance: false, fee: false, } } let createTransactionResponse = await rango.createTransaction(request) let tx = createTransactionResponse.transaction if (!tx) { throw new Error(`Error creating the transaction ${createTransactionResponse.error}`) } ``` If you are verifying the balance and fee amount on your client side or you've already checked them in route confirmation step, it is advisable to set the balance and fee parameters to false to prevent duplicate checks or potential errors during validation. ### Tracking Swap Status After signing the transaction by the user and receiving transaction hash, you could periodically call Rango check-status API to track the transaction status. In Rango, each swap step could have 3 different states: `running`, `failed` and `success`. You only need to keep checking the status until you find out whether the transaction failed or succeeded. ```typescript const state = await rango.checkStatus({ requestId: confirmedRoute.requestId, step: 1, // related step txId: '0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5' }) 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 check-status method again after a timeout (10s) } } ``` ## Complete Code Flow {% embed url="" %} {% code title="Node.JS Example" %} ```typescript // run `node --import=tsx index.ts` in the terminal import { CreateTransactionRequest, RangoClient, TransactionStatus, TransactionType } from "rango-sdk"; import { findToken } from '../shared/utils/meta.js' import { TransactionRequest, ethers } from "ethers"; import { setTimeout } from 'timers/promises' // setup wallet & RPC provider // please change rpc provider url if you want to test another chain rather than BSC const privateKey = 'YOUR_PRIVATE_KEY'; const wallet = new ethers.Wallet(privateKey); const rpcProvider = new ethers.JsonRpcProvider('https://bsc-dataseed1.defibit.io'); const walletWithProvider = wallet.connect(rpcProvider); const waleltAddress = walletWithProvider.address // initiate sdk using your api key const API_KEY = "c6381a79-2817-4602-83bf-6a641a409e32" const rango = new RangoClient(API_KEY) // get blockchains and tokens meta data const meta = await rango.getAllMetadata() // some example tokens for test purpose const sourceBlockchain = "BSC" const sourceTokenAddress = "0x55d398326f99059ff775485246999027b3197955" const targetBlockchain = "BSC" const targetTokenAddress = null const amount = "0.001" // find selected tokens in meta.tokens const sourceToken = findToken(meta.tokens, sourceBlockchain, sourceTokenAddress) const targetToken = findToken(meta.tokens, targetBlockchain, targetTokenAddress) // get route const routingRequest = { from: sourceToken, to: targetToken, amount, slippage: '1.0', } const routingResponse = await rango.getAllRoutes(routingRequest) if (routingResponse.results.length === 0) { throw new Error(`There was no route! ${routingResponse.error}`) } // confirm one of the routes const selectedRoute = routingResponse.results[0] const selectedWallets = selectedRoute.swaps .flatMap(swap => [swap.from.blockchain, swap.to.blockchain]) .filter((blockchain, index, self) => self.indexOf(blockchain) === index) .map(blockchain => ({ [blockchain]: waleltAddress })) .reduce((acc, obj) => { return { ...acc, ...obj }; }, {}); const confirmResponse = await rango.confirmRoute({ requestId: selectedRoute.requestId, selectedWallets, }) const confirmedRoute = confirmResponse.result if (!confirmedRoute) { throw new Error(`Error in confirming route, ${confirmResponse.error}`) } let step = 1 const swapSteps = confirmedRoute.result?.swaps || [] for (const swap of swapSteps) { const request: CreateTransactionRequest = { requestId: confirmedRoute.requestId, step: step, userSettings: { slippage: '1.0', infiniteApprove: false }, validations: { approve: true, balance: false, fee: false, } } let createTransactionResponse = await rango.createTransaction(request) let tx = createTransactionResponse.transaction if (!tx) { throw new Error(`Error creating the transaction ${createTransactionResponse.error}`) } if (tx.type === TransactionType.EVM) { if (tx.isApprovalTx) { // sign the approve transaction const approveTransaction: TransactionRequest = { from: tx.from, to: tx.to, data: tx.data, value: tx.value, maxFeePerGas: tx.maxFeePerGas, maxPriorityFeePerGas: tx.maxPriorityFeePerGas, gasPrice: tx.gasPrice, gasLimit: tx.gasLimit, } const { hash } = await walletWithProvider.sendTransaction(approveTransaction); // wait for approval while (true) { await setTimeout(5_000) const { isApproved, currentApprovedAmount, requiredApprovedAmount, txStatus } = await rango.checkApproval(confirmedRoute.requestId, hash) if (isApproved) break else if (txStatus === TransactionStatus.FAILED) throw new Error('Approve transaction failed in blockchain') else if (txStatus === TransactionStatus.SUCCESS) throw new Error(`Insufficient approve, current amount: ${currentApprovedAmount}, required amount: ${requiredApprovedAmount}`) } // create the main transaction if previous one was approval transaction createTransactionResponse = await rango.createTransaction(request) tx = createTransactionResponse.transaction if (!tx || tx.type !== TransactionType.EVM) { throw new Error(`Error creating the transaction ${createTransactionResponse.error}`) } } // sign the main transaction const mainTransaction: TransactionRequest = { from: tx.from, to: tx.to, data: tx.data, value: tx.value, maxFeePerGas: tx.maxFeePerGas, maxPriorityFeePerGas: tx.maxPriorityFeePerGas, gasPrice: tx.gasPrice, gasLimit: tx.gasLimit, } const { hash } = await walletWithProvider.sendTransaction(mainTransaction); // track swap status while (true) { await setTimeout(10_000) const state = await rango.checkStatus({ requestId: confirmedRoute.requestId, step, txId: hash }) const status = state.status if (status === TransactionStatus.SUCCESS) { // we could proceed with the next step of the route step += 1; break } else if (status === TransactionStatus.FAILED) { throw new Error(`Swap failed on step ${step}`) } } } } ``` {% endcode %} # Monetization How to take fees from the users using Rango Main API? ## How Rango affiliate system works? {% content-ref url="/pages/XLBy76udAgbv1sqg98A8" %} [Monetization](/technical/monetization) {% endcontent-ref %} ## How to set affiliate parameters? In main api, it's enough to pass affiliate parameters only in routing methods e.g. in [getBestRoute](/api-integration/main-api-multi-step/api-reference/get-best-route) or `getAllRoutes` methods. In these methods, several fields could be used for participating in the affiliate program: `affiliateRef`, `affiliateWallets`, `affiliatePercent`. You could use combination of`affiliateRef` and `affiliatePercent`, or `affiliateWallets` and `affiliatePercent`: * `affiliateRef`: The referral code you could generate on our Affiliate Program Page. If you use this, we will send the affiliate fees to the wallet that created this link. * `affiliatePercent`: The fee percentage you want to charge the users (1.5 means 1.5 percent). The maximum fee you could charge users is 3 percent. The default value is 0.1 percent or 10 bps. * `affiliateWallets`: A map of blockchains to wallet addresses, allowing you to specify which wallet you want to receive the fee. Sample code for fetching the route preview: {% tabs %} {% tab title="Typescript" %} 
const bestRoute = await rango.getBestRoute({
    from: {"blockchain": "BSC", "symbol": "BNB", "address": null},
    to: {"blockchain": "AVAX_CCHAIN", "symbol": "USDT.E", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118"},    
    amount: "1",
    slippage: 1,
    checkPrerequisites: false,
    affiliatePercent: 0.3,
    affiliateWallets: {
        "BSC": "0x6f33bb1763eebead07cf8815a62fcd7b30311fa3"
    },
})
{% endtab %} {% tab title="cURL" %} ```bash 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" }, "checkPrerequisites": false, "affiliateWallets": { "BSC": "0x6f33bb1763eebead07cf8815a62fcd7b30311fa3" }, "amount": "1", "affiliatePercent": 0.3, "slippage": 1 } ' ``` {% endtab %} {% endtabs %} Example code for the moment the user confirms the route: {% tabs %} {% tab title="Typescript" %} 
const bestRoute = await rango.getBestRoute({
    from: {"blockchain": "BSC", "symbol": "BNB", "address": null},
    to: {"blockchain": "AVAX_CCHAIN", "symbol": "USDT.E", "address": "0xc7198437980c041c805a1edcba50c1ce5db95118"},    
    amount: "1",
    slippage: 1,
    checkPrerequisites: true,
    selectedWallets: {
        "BSC": "0xeae6d42093eae057e770010ffd6f4445f7956613",
        "AVAX_CCHAIN": "0xeae6d42093eae057e770010ffd6f4445f7956613",
    },
    affiliatePercent: 0.3,
    affiliateWallets: {
        "BSC": "0x6f33bb1763eebead07cf8815a62fcd7b30311fa3"
    },
})
{% endtab %} {% tab title="cURL" %} ```bash 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" }, "selectedWallets": { "BSC": "0xeae6d42093eae057e770010ffd6f4445f7956613", "AVAX_CCHAIN": "0xeae6d42093eae057e770010ffd6f4445f7956613" }, "checkPrerequisites": true, "affiliateWallets": { "BSC": "0x6f33bb1763eebead07cf8815a62fcd7b30311fa3" }, "amount": "1", "affiliatePercent": 0.3, "slippage": 1 } ' ``` {% endtab %} {% endtabs %} # Sample Transactions Sample transactions for all types of transactions in main API ## Overview Here are some samples of the transaction object that is created in [create transaction](/api-integration/main-api-multi-step/api-reference/create-transaction) method. Rango currently returns 6 different types of transactions based on the blockchain that the transaction is happening on. This includes: * **EVM**: For all EVM-based blockchains, including Ethereum, Polygon, Avalanche, etc. * **COSMOS**: For all the cosmos-based networks, including the Cosmos itself, Osmosis, Akash, Thorchain, Maya and etc. * **TRANSFER**: For UTXO blockchains, including Bitcoin, Litecoin, Doge, etc. * **SOLANA:** For Solana transactions. * **TRON:** For Tron Transactions. * **STARKNET:** For Starknet transactions. * **SUI:** For SUI transactions. * **XRPL:** For XRPL transactions. * **STELLAR**: For Stellar transactions. Let's see some examples here. ## EVM Sample Transaction: [(Test)](https://app.rango.exchange/bridge?fromBlockchain=BSC\&fromToken=BUSD--0xe9e7cea3dedca5984780bafc599bd69add087d56\&toBlockchain=AVAX_CCHAIN\&toToken=AVAX) Here is the structure of an EVM transaction in the code below. If the user lacks sufficient approval for the transaction, the create transaction method will respond with an approval transaction. (`isApproval` field is `true` in this case.) The user must first sign this approval transaction to ensure they have the necessary approval. Then, they should call the create transaction method again to obtain and sign the main transaction. The fields and schema for the approval and main transactions are identical. {% hint style="info" %} For the gas price of the transaction, if the blockchain supports the new versions of gas price, such as `maxPriorityFeePerGas` and `maxFeePerGas`, these fields will be populated. However, for blockchains that have not yet updated their gas model, the gas price will be set in the `gasPrice` field as before. You can check the list of all chains that support the new gas price versions in the `meta` or `blockchains` methods. (There is an `enableGasV2` field in the response body, included for each blockchain.) {% endhint %} 
"transaction": {
    "type": "EVM",
    "blockChain": "BSC",
    "isApprovalTx": true,
    "from": "0x7abac41d46857b0b6c4d67eb966b4a29ba69b4f3",
    "to": "0xe9e7cea3dedca5984780bafc599bd69add087d56",
    "data": "0x095ea7b300000000000000000000000069460570c93f9de5e2edbc3052bf10125f0ca22d000000000000000000000000000000000000000000000000000775f05a074000",
    "value": null,
    "gasLimit": "0x12284",
    "gasPrice": "1100000000",
    "maxPriorityFeePerGas": null,
    "maxFeePerGas": null,
    "nonce": null
}
Sample for non-approval: 
"transaction": {
  "type": "EVM",
  "blockChain": "BSC",
  "isApprovalTx": false,
  "from": "0xccf3d872b01762aba74b41b1958a9a86ee8f34a2",
  "to": "0x69460570c93f9DE5E2edbC3052bf10125f0Ca22d",
  "data": "0xb17d0e6e000000000000000000000000000000002358d41a5a8f4afa87403e161e2955e900000000000000000000000055d398326f99059ff775485246999027b3197955000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000081fe9fae05d8094c0000000000000000000000000000000000000000000000000031fe30556285140000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000037f73c93f73fac000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000001000000000000000000000000ccf3d872b01762aba74b41b1958a9a86ee8f34a3000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000001b81d678ffb9c0263b24a97847620c99d213eb140000000000000000000000001b81d678ffb9c0263b24a97847620c99d213eb1400000000000000000000000055d398326f99059ff775485246999027b31979550000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000081fe9fae05d8094c00000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000264ac9650d800000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000124c04b8d59000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000190ff9d543500000000000000000000000000000000000000000000000081fe9fae05d8094c0000000000000000000000000000000000000000000000000037f4872b410e24000000000000000000000000000000000000000000000000000000000000002b55d398326f99059ff775485246999027b31979550001f4bb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004449404b7c0000000000000000000000000000000000000000000000000037f73c93f73fac00000000000000000000000069460570c93f9de5e2edbc3052bf10125f0ca22d0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "value": null,
  "gasLimit": "0x91bc6",
  "gasPrice": "1100000000",
  "maxPriorityFeePerGas": null,
  "maxFeePerGas": null,
  "nonce": null
}
## COSMOS Sample Transaction: For Cosmos based blockchains, we have two type of transactions based on `signType` field: `AMINO` and `DIRECT`. ### Cosmos Amino Sample Transaction: [(Test)](https://app.rango.exchange/bridge/?fromBlockchain=OSMOSIS\&fromToken=OSMO\&toBlockchain=OSMOSIS\&toToken=ATOM--ibc%2F27394fb092d2eccd56123c74f36e4c1f926001ceada9ca97ea622b25f41e5eb2) 
{
  "type": "COSMOS",
  "fromWalletAddress": "osmo1unf2rcytjxfpz8x8ar63h4qeftadptg5t0nqcl",
  "blockChain": "OSMOSIS",
  "data": {
    "chainId": "osmosis-1",
    "account_number": 102721,
    "sequence": "892",
    "msgs": [
      {
        "type": "wasm/MsgExecuteContract",
        "value": {
          "sender": "osmo1unf2rcytjxfpz8x8ar63h4qeftadptg5t0nqcl",
          "contract": "osmo1clp46dz247hck0ns5jkv49hqzg8x0vh5hsx8yfvk6w87hnvc6hgs563ew3",
          "msg": {
            "swap_and_action": {
              "user_swap": {
                "swap_exact_asset_in": {
                  "swap_venue_name": "osmosis-poolmanager",
                  "operations": [
                    {
                      "pool": "1464",
                      "denom_in": "uosmo",
                      "denom_out": "ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4"
                    },
                    {
                      "pool": "1838",
                      "denom_in": "ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4",
                      "denom_out": "ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2"
                    }
                  ]
                }
              },
              "min_asset": {
                "native": {
                  "denom": "ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2",
                  "amount": "74944"
                }
              },
              "timeout_timestamp": 1722276105002000000,
              "post_swap_action": {
                "transfer": {
                  "to_address": "osmo1unf2rcytjxfpz8x8ar63h4qeftadptg5t0nqcl"
                }
              },
              "affiliates": []
            }
          },
          "funds": [
            {
              "denom": "uosmo",
              "amount": "1000000"
            }
          ]
        }
      }
    ],
    "protoMsgs": [
      {
        "type_url": "/cosmwasm.wasm.v1.MsgExecuteContract",
        "value": [
          10,
          43,
          111,
          // ...
        ]
      }
    ],
    "memo": "",
    "source": null,
    "fee": {
      "gas": "2000000",
      "amount": [
        {
          "denom": "uosmo",
          "amount": "50000"
        }
      ]
    },
    // Sign type, could be AMINO or DIRECT
    "signType": "AMINO",
    "rpcUrl": "https://osmosis-rpc.polkachu.com"
  },
  // @deprecated An alternative to CosmosMessage object for the cosmos wallets 
  "rawTransfer": null
}
### Cosmos Direct Sample Transaction: [(Test)](https://app.rango.exchange/bridge/?fromBlockchain=JUNO\&fromToken=JUNO\&toBlockchain=JUNO\&toToken=USDC--ibc%2Feac38d55372f38f1afd68df7fe9ef762dcf69f26520643cf3f9d292a738d8034\&fromAmount=1) This type is only used in limited swappers like WYNDDex (and Juno Blockchain) and we are going to deprecate support for Cosmos Direct transaction types whenever possible. You could sign this type of transactions using Stargate Client library. 
"transaction": {
  "type": "COSMOS",
  "fromWalletAddress": "juno1unf2rcytjxfpz8x8ar63h4qeftadptg54xrtf3",
  "blockChain": "JUNO",
  "data": {
    "chainId": "juno-1",
    "account_number": 125507,
    "sequence": "309",
    "msgs": [
      {
        "typeUrl": "/cosmwasm.wasm.v1.MsgExecuteContract",
        "value": {
          "sender": "juno1unf2rcytjxfpz8x8ar63h4qeftadptg54xrtf3",
          "contract": "juno1pctfpv9k03v0ff538pz8kkw5ujlptntzkwjg6c0lrtqv87s9k28qdtl50w",
          "msg": "eyJleGVjdXRlX3N3YXBfb3BlcmF0aW9ucyI6eyJvcGVyYXRpb25zIjpbeyJ3eW5kZXhfc3dhcCI6eyJhc2tfYXNzZXRfaW5mbyI6eyJuYXRpdmUiOiJpYmMvQzRDRkY0NkZENkRFMzVDQTRDRjRDRTAzMUU2NDNDOEZEQzlCQTRCOTlBRTU5OEU5QjBFRDk4RkUzQTIzMTlGOSJ9LCJvZmZlcl9hc3NldF9pbmZvIjp7Im5hdGl2ZSI6InVqdW5vIn19fV0sIm1heF9zcHJlYWQiOiIwLjAxIn19",
          "funds": [
            {
              "denom": "ujuno",
              "amount": "1000000"
            }
          ]
        }
      }
    ],
    "protoMsgs": [],
    "memo": "",
    "source": null,
    "fee": {
      "gas": "1000000",
      "amount": [
        {
          "denom": "ujuno",
          "amount": "2500"
        }
      ]
    },
    // Sign type, could be AMINO or DIRECT
    "signType": "DIRECT",
    "rpcUrl": "https://rpc-juno.itastakers.com:443/"
  },

  // @deprecated An alternative to CosmosMessage object for the cosmos wallets 
  "rawTransfer": null
}
## Transfer Sample Transaction: [(Test)](https://app.rango.exchange/bridge/?fromBlockchain=BTC\&fromToken=BTC\&toBlockchain=LTC\&toToken=LTC\&fromAmount=1) Here is the structure of an UTXO (Transfer) transaction: ```json "transaction": { // This field equals to TRANSFER for all UTXO Transactions "type": "TRANSFER", // The method that should be passed to wallet including deposit, transfer "method": "transfer", // Source wallet address that can sign this transaction "fromWalletAddress": "bc1qagtumlttplyp93fnxndkkcf80ladl4gpnmv25u", // Destination wallet address that the fund should be sent to "recipientAddress": "bc1qeqc7py84yjrtc3cnfnjx9p9xyvjm8887kexdfu", // The memo of transaction, can be null "memo": "=:ETH.ETH:0x6f33bb1763eebead07cf8815a62fcd7b30311fa3:1080176077:rg:0", // The machine-readable amount of transaction "amount": "1000000000", // The decimals of the asset "decimals": 8, // An asset with its ticker "asset": { "blockchain": "BTC", "symbol": "BTC", "address": null, "ticker": "BTC" }, // Partially signed bitcoin transaction "psbt": { "unsignedPsbtBase64": "cHNidP8BAH0CAAAAAdeeknt27QIuENUtqyEuDWKi0HjMR6J8OyFIH0AeCowYAAAAAAD/////AoCWmAAAAAAAIlEgD5gCxhBANQBrbG92Di7Y0wPGEgBXxa9K7mVT0IIvONIM+SMCAAAAABYAFOoXzf1rD8gSxTM022thJ3/639UBAAAAAAABAR9QkbwCAAAAABYAFOoXzf1rD8gSxTM022thJ3/639UBAAAA", "inputsToSign": [ { "address": "bc1qagtumlttplyp93fnxndkkcf80ladl4gpnmv25u", "signingIndexes": [ 0 ] } ] } } ``` ## Tron Sample Transaction: [(Test)](https://app.rango.exchange/bridge/?fromBlockchain=TRON\&fromToken=TRX\&toBlockchain=TRON\&toToken=USDT--TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t) Here is the structure of a Tron transaction. Similar to EVM transactions, it can be either an approval transaction or a main transaction, depending on the `isApproval` field ```json { "type": "TRON", "blockChain": "TRON", "isApprovalTx": false, "raw_data": { "contract": [ { "parameter": { "value": { "data": "b24ebddb000000000000000000000000000000000000000000000000000000000002091100000000000000000000000000000000000000000000000000000190ffaa951100000000000000000000000000000000000000000000000000000000000f4240", "owner_address": "413a51fc0bc19accbea62fac65bad2660bbcffd08a", "contract_address": "41a2726afbecbd8e936000ed684cef5e2f5cf43008", "call_value": 1000000 }, "type_url": "type.googleapis.com/protocol.TriggerSmartContract" }, "type": "TriggerSmartContract" } ], "ref_block_bytes": "af01", "ref_block_hash": "e4752a1cdaf3e944", "expiration": 1722276345000, "fee_limit": 1500000000, "timestamp": 1722276287817 }, "raw_data_hex": "0a02af012208e4752a1cdaf3e94440a8e9adfd8f325ad301081f12ce010a31747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e54726967676572536d617274436f6e74726163741298010a15413a51fc0bc19accbea62fac65bad2660bbcffd08a121541a2726afbecbd8e936000ed684cef5e2f5cf4300818c0843d2264b24ebddb000000000000000000000000000000000000000000000000000000000002091100000000000000000000000000000000000000000000000000000190ffaa951100000000000000000000000000000000000000000000000000000000000f424070c9aaaafd8f32900180dea0cb05", "externalTxId": null, "__payload__": { "owner_address": "413a51fc0bc19accbea62fac65bad2660bbcffd08a", "call_value": 1000000, "contract_address": "41a2726afbecbd8e936000ed684cef5e2f5cf43008", "fee_limit": 1500000000, "function_selector": "trxToTokenSwapInput(uint256,uint256,uint256)", "parameter": "000000000000000000000000000000000000000000000000000000000002091100000000000000000000000000000000000000000000000000000190ffaa951100000000000000000000000000000000000000000000000000000000000f4240", "chainType": 0 }, "txID": "10d1428e0ccc8870b9334d73da2313cfaff29ec27930e68a6947ea8bb1d6b181", "visible": false } ``` ## Starknet Sample Transaction: [(Test)](https://app.rango.exchange/bridge/?fromBlockchain=STARKNET\&fromToken=ETH--0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7\&toBlockchain=STARKNET\&toToken=USDT--0x68f5c6a61780768455de69077e07e89787839bf8166decfbf92b645209c0fb8\&fromAmount=1) Here is the structure of a Starknet transaction. Like EVM transactions, it can be either an approval transaction or a main transaction, depending on the `isApproval` field. Whenever possible, in Starknet, we batch the approval and main transactions into a single transaction using the `calls` array, as shown in the example below. ```json "transaction": { "type": "STARKNET", "blockChain": "STARKNET", "calls": [ { "contractAddress": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", "entrypoint": "approve", "calldata": [ "0x4270219d365d6b017231b52e92b3fb5d7c8378b05e9abc97724537a80e93b0f", "0x00000000000000000ddb6275b03a4000", "0x00000000000000000000000000000000" ] }, { "contractAddress": "0x4270219d365d6b017231b52e92b3fb5d7c8378b05e9abc97724537a80e93b0f", "entrypoint": "multi_route_swap", "calldata": [ "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", "0xddb6275b03a4000", "0x0", // ... ] }, { "contractAddress": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", "entrypoint": "transfer", "calldata": [ "0x01d8b73b49d8cb653570929260e8e01033278d6840f706faa421f08b992f8083", "0x00000000000000000005543df729c000", "0x00000000000000000000000000000000" ] } ], "maxFee": null, "isApprovalTx": false, "spender": null } ``` ## Solana Sample Transaction: [(Test)](https://app.rango.exchange/bridge/?fromBlockchain=SOLANA\&fromToken=USDT--Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB\&toBlockchain=SOLANA\&toToken=SOL\&fromAmount=1) {% hint style="warning" %} **Base64 Encoding** Remember to broadcast the signed transaction to Solana RPCs with **base64** encoding. The **base58 encoding is deprecated**, but it is still the default method in Solana [docs](https://solana.com/docs/rpc/http/sendtransaction). {% endhint %} {% hint style="info" %} **Versioned vs Legacy** All supported routes for Solana are `VERSIONED` transactions except a special case of converting `SOL` to `WSOL` or vice versa via Solana Wrapper. (which you can ignore it.) * [Sample for versioned transaction](https://app.rango.exchange/bridge/?fromBlockchain=SOLANA\&fromToken=USDT--Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB\&toBlockchain=SOLANA\&toToken=SOL\&fromAmount=1) * [Sample for legacy transaction](https://app.rango.exchange/bridge/?fromBlockchain=SOLANA\&fromToken=SOL\&toBlockchain=SOLANA\&toToken=WSOL--So11111111111111111111111111111111111111112\&fromAmount=1) {% endhint %} 
"transaction": {
     // This field equals to SOLANA for all SOLANA Transactions
    "type": "SOLANA",
    
    // Transaction blockchain
    "blockChain": "SOLANA",
    
    // Wallet address of transaction initiator
    "from": "3HsNMDtxPRUzwLpDJemmNVbasm11Ei5CGGCjktgHh27F",
    
    // Transaction identifier in case of retry
    "identifier": "Swap",
    
    // List of instructions
    "instructions": [ ],

    // Recent blockHash. Nullable. Filled only if message is already partially signed
    "recentBlockhash": null,
    
    // List of signatures. Filled only if message is already partially signed
    "signatures": [ ],
    
    // When serialized message appears, there is no need for other fields and you just sign and send it
    "serializedMessage": [1, 0, 95, 96, ..., 1, 253], 
    
    // Could be LEGACY or VERSIONED
    "txType": "VERSIONED"
  }
## SUI Sample Transaction:[(Test)](https://app.rango.exchange/bridge/?fromBlockchain=SUI\&fromToken=SUI--0x2%3A%3Asui%3A%3ASUI\&toBlockchain=BSC\&toToken=BNB\&fromAmount=15) {% hint style="info" %} **Key Notes:** * The **unsignedPtbBase64** field is a base64-encoded string that contains the transaction's raw data. This is typically used to create the signed transaction, which would then be broadcasted to the blockchain. {% endhint %} ```json "transaction": { "type": "SUI", "blockChain": "SUI", // Base64-encoded unsigned transaction data "unsignedPtbBase64": "AAAA......" } ``` ## XRPL Sample Transaction:[(Test)](https://api.rango.exchange/basic/swap?from=XRPL.XRP\&to=BASE.ETH\&amount=50000000) {% hint style="info" %} **Key Notes:** * **Trust lines (IOUs):** When the destination token is not the native XRP, you need to set up a trust line to the issuer account before the swap (wallets can sign this as a pre-tx) {% endhint %} ```json "transaction": { "type": "XRPL", "blockChain": "XRPL", "data": { "TransactionType": "Payment", "Destination": "rM27yzkCw6WA3T4g1sPaeC1kpxHUhuxRWn", "Amount": "10231000", "Memos": [ { "Memo": { "MemoData": "7B2266726F6D546F6B656E223A22307865656565656565656565656565656565656565656565656565656565656565656565656565656565222C22746F546F6B656E223A2258525041594E45547C72616E676F4465787C302E3031222C2273656E646572223A22724769537053387177614B4E62386E6D6A3234616831794767724434346B36543663222C2264657374696E6174696F6E223A22724769537053387177614B4E62386E6D6A3234616831794767724434346B36543663222C226D696E52657475726E416D6F756E74223A22393136393338353234373034303030303030303030303030222C2266726F6D416D6F756E74223A223130323331303030227D" } } ] }, "type": "XRPL""prerequisites": [ { "type": "XRPL_CHANGE_TRUSTLINE", "currency": "The Xrpl output asset currency, such as USDC", "issuer": "The Xrpl output asset issuer", "value": "Minimum expected value of trust for the Xrpl asset", "wallet": "User's wallet address which must have this trustline allowed for the Xrpl asset" } ], } ``` ```json "transaction": { "type": "XRPL", "blockChain": "XRPL", "data": { "TransactionType": "Payment", "Destination": "rM27yzkCw6WA3T4g1sPaeC1kpxHUhuxRWn", "Amount": { "currency": "CSC", "value": "256461.000000000000000000", "issuer": "rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr" }, "Memos": [ { "Memo": { "MemoData": "7B2266726F6D546F6B656E223A22724353434D616E545A384D4539456F4C72534848594B5738505077574D676B7772222C22746F546F6B656E223A22307865656565656565656565656565656565656565656565656565656565656565656565656565656565222C2273656E646572223A22724769537053387177614B4E62386E6D6A3234616831794767724434346B36543663222C2264657374696E6174696F6E223A22724769537053387177614B4E62386E6D6A3234616831794767724434346B36543663222C226D696E52657475726E416D6F756E74223A2237303230333339222C2266726F6D416D6F756E74223A22323536343631303030303030303030303030303030303030227D" } } ] }, "prerequisites": [ { "type": "XRPL_CHANGE_TRUSTLINE", "currency": "The Xrpl output asset currency, such as USDC", "issuer": "The Xrpl output asset issuer", "value": "Minimum expected value of trust for the Xrpl asset", "wallet": "User's wallet address which must have this trustline allowed for the Xrpl asset" } ], } ``` ## Stellar Sample Transaction: [(Test)](https://api.rango.exchange/basic/swap?from=STELLAR.XLM\&to=STELLAR.USDC--USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN\&amount=50000000) In order to execute a transaction on stellar network, Rango provides you a base64 encoded External Data Representation or XDR for operations and memo of the transaction, and preconditions of a PreconditionsV2. You can check the [official Stellar docs regarding XDRs](https://developers.stellar.org/docs/learn/fundamentals/data-format/xdr) in Stellar Network. This value must be signed by user's wallet. {% hint style="info" %} **Key Notes:** * **Trust lines:** When the destination token is not the native XLM, the API returns a trust-line precondition which must be signed and broadcasted before signing and broadcasting the swap transaction. In some of the swaps, Rango would be able to include the `ChangeTrustOperation` in the transaction itself, and so no trust-line precondition would be returned by the API. {% endhint %} Note that for non-native Stellar assets, user's wallet must allow a trustline for the asset in order to receive it. 
 "transaction": {
        "type": "STELLAR",
        "blockChain": "STELLAR",
        "data": {
                "baseFee": null, // Optional BigInt value, Recommended base fee (in stroops) for building the stellar transaction
                "preconditions": {        // CAP-21 PreconditionsV2 of transaction transaction
                        "timeBounds": { // Optional, time bounds of stellar transaction data
                                "minTime": 1778506995, // BigInt value, Unix timestamped constraint for minimum time of transaction validity
                                "maxTime": 1779506995 // Unix timestamped constraint for maximum time of transaction validity
                        },
                        "ledgerBounds": { // Optional, ledger bounds of stellar transaction data, Transaction only valid for ledger numbers n such that minLedger <= n < maxLedger
                                "minLedger": 1000, // BigInt value, Minimum ledger for transaction validity
                                "maxLedger": 0 // BigInt value, Maximum ledger for transaction validity, 0 here means NO maxLedger
                        },
                        "minSeqNumber": null, // BigInt value, If NULL, only valid when sourceAccount's sequence number is seqNum - 1.  Otherwise, valid when sourceAccount's sequence number n satisfies minSeqNum <= n < tx.seqNum
                        "minSeqAge": null, // BigInt value, For the transaction to be valid, the current ledger time must be at least minSeqAge greater than sourceAccount's seqTime
                        "minSeqLedgerGap": null, // BigInt value, For the transaction to be valid, the current ledger number must be at least minSeqLedgerGap greater than sourceAccount's seqLedger
                        "extraSigners": null // Optional, list of strings, For the transaction to be valid, there must be a signature corresponding to every Signer in this array
                },
                "operationsXdrBase64": [ // list of operations as base 64 encoded strings
                        "AAA...",
                        "AAA..."
                ],
                "memoXdrBase64": null // base 64 encoded memo of transaction
        },
        "prerequisites": [
                {
                        "type": "STELLAR_CHANGE_TRUSTLINE",
                        "code": "The stellar output asset code, such as USDC",
                        "issuer": "The stellar asset issuer, e.g.: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
                        "value": "The minimum amount of required trustline for this stellar asset, such as 11.50",
                        "wallet": "User's wallet address which must have this trustline allowed for the stellar asset" 
                }
        ]
    }
# API Troubleshooting Rango Exchange API Troubleshooting ## Error Codes ### Overview This sections outlines the structure of Rango error responses and error codes, and describes the possible errors integrators may encounter when using our APIs. Rango error responses contain three fields: **error**, **errorCode**, and **traceId**. * **Error:** Describes what happened in Rango. * **Error Code:** Indicates the general type of error as defined in this documentation. * **Trace ID:** A number that the integrator can provide to Rango to trace the error and locate the corresponding request in our logs. Rango error codes follow a four-digit format. The first two digits indicate the error category, and the last two specify the error type. ### Error Code Categories #### **Server Errors (11)** * **1101:** In some cases, the integrator might encounter an internal server error. When this occurs, the Rango team will automatically be notified and will address the issue immediately. If the error persists, please [contact us](https://discord.gg/q3EngGyTrZ) by opening a ticket in **users-support channel** of Rango's official Discord server. * **1102:** An exception occurred in one of the underlying protocols. **Validation Errors (12)** * **1201:** This error occurs when a bad request is sent through the Rango API. Please review the API response for details on how to resolve the issue. * **1202:** The provided input exceeds the permitted limits of the swapper (either above the maximum or below the minimum). The API response returns the quoted swapper’s minimum and maximum thresholds. It varies for each swapper and token. * **1203:** Rango was unable to retrieve your wallet balance for the input or fee token. * **1204:** The transaction hash provided by the integrator is invalid, possibly due to an incorrect approval transaction or an incorrect format. * **1205:** Rango was unable to locate the token for the provided token contract address. * **1206:** The requested blockchain is not supported by Rango or the type is wrong. You can find Rango supported blockchain in the [Meta API](/api-integration/basic-api-single-step/api-reference/get-blockchains-and-tokens). **Routing Errors (13)** * **1301:** This swap would result in a loss of more than 18% of the user's input USD value. * **1302:** This error occurs when there is a significant discrepancy between the quoted amount and the transaction’s creation amount. * **1303:** The route has expired, and a transaction can no longer be created using this route. This error occurs if the integrator attempts to create the transaction more than 5 minutes after the quote response. Although integrators have a 5-minute window to create the transaction, we recommend doing so within 1 minute due to high rate fluctuations on the blockchain. * **1304:** No valid route was found for this swap. **Authentication Errors (14)** * **1401:** This error occurs during authentication (e.g., when an affiliate attempts to log in) if the provided credentials are invalid. **KYC Errors (15)** * **1501:** Swapper’s KYC verification is required when a transaction involves a large amount or when a suspicious wallet is detected. (Currently only SWFT has such a mechanism on Rango) # Swap Aggregation How Rango batch multiple transactions into a single transaction? ## Introduction In Rango, we batch multiple transactions in a single transaction whenever possible. For example, imagine the user wants to swap its MATIC on Polygon to USDC on Osmosis. The usual route would be to first swap MATIC to AXLUSDC and then bridge it using Satellite (Axelar) to Osmosis. But Rango can aggregate these two steps in a single step, enabling to swap and bridge in the same transaction as it can be seen in image below:

Using an aggregator in Rango, swapping MATIC on polygon to USDC on osmosis in a single transaction.

To enable this feature, Rango uses smart contracts. Also message passing protocols are used to batch three step transactions into a single transaction. For example, in the case below, IBC+Osmosis+IBC steps are batched into a single transaction. IBC protocol is used for both bridging and message passing. As a result, the user can convert its native ATOM to native JUNO in a single transaction using trust-less protocols.

Using an aggregator in Rango, swapping ATOM on cosmos to JUNO on juno in a single transaction, using IBC and osmosis swaps.

## Slippage Handling Since aggregations batch multiple transactions into a single transaction, the slippage could be applied at each step. There is a trade-off between slippage and transaction failure rate in the case of on-chain swaps. To reduce failure rate without exposing the user to higher slippage, in case of three-step aggregations, we try to use half the slippage for the initial step to leave enough room for the third step transaction. For example if the user sets max slippage tolerance of 3% for a batch of swap+bridge+swap aggregation, on the first swap we only use 1.5% slippage tolerance. This both helps prevent MEV in the first step and also reduce error rates in the third step. ## **Edge Cases** In Solana aggregation, two cases occur: 1\. When an on-chain swap is executed in Solana, and one side is SOL, all WSOL balance in wallet will be converted to SOL. This behavior is inherent to the Jupiter aggregator, and we don't have any control over it. 2\. When a token is swapped and then bridged from Solana to other blockchains, there might be a residual amount of tokens left in the user's wallet because the aggregation in AllBridge and DeBridge performs the swap but the bridge transaction is executed with minimum expected output. # Monetization How can individuals or dApps & wallets collect fees from Rango Exchange? ## Introduction Rango Affiliate Program presents an opportunity for both individual users and decentralized applications. By participating in the program, affiliates can refer new users to our platform and receive an affiliate fee for swap transactions that their referrals initiate. ## Affiliate Types Our affiliate program offers two distinct payment methods. The payment method is determined based on specific circumstances and the blockchain networks where transactions occur. ### Instant Settlement (Direct Fee) The Instant Settlement program enables you to earn affiliate fees instantly when a user executes a transaction using Rango and includes your referral information for the swap. This program provides a seamless and real-time way to earn affiliate rewards for each swap transaction initiated by your referred users. #### ✔ Supported Chains: * EVM Chains * Osmosis * Starknet #### ✔ Supported Protocols * All EVM On-Chain Swappers (DEXs and DEX Aggregators) * Almost all EVM Bridges * EVM Bridges which don’t support direct fee yet: XYFinance, Synapase and DeBridge (They will be supported in next contract audit.) * Starknet On-Chain Swappers (DEXs and DEX Aggregators) * Osmosis IBC or On-Chain Swap {% hint style="info" %} **Notices:** * You will receive this fee, on the source chain of the user’s transaction. * If the source chain of transaction is in the supported chains, the direct fee will be charged from user and instantly settled on the source chain. Whenever the source chain is not in the list above, direct fees are not supported. For example, when user swaps from Solana to Ethereum, affiliate fee cannot be settled instantly. {% endhint %} ### Monthly Settlement (Manual Fee) {% hint style="warning" %} **Deprecated** Since Rango now broadly supports direct fee transactions, this program is almost deprecated. We only offer it in special circumstances for some enterprise customers with specific requirements. {% endhint %} In this program, we collect the affiliate fees from all transactions made by users that you referred to. At the end of each month, we consolidate your earnings and pay you the accumulated amount whenever it exceeds $10. The Monthly Settlement program is implemented in cases where we don't have Rango contracts deployed on certain blockchains, and specific swappers or bridges have their affiliate programs with limitations, usually supporting only one wallet. To accommodate these scenarios, Rango collects the protocol fees and affiliate fees from such swappers or bridges in the Rango protocol wallet. By default, the procotol will charge 10 bps as affiliate fees. API/SDK and Widget users can customize the charged amount. View [widget monetization](/widget-integration/monetization), [Basic API monetization](/api-integration/basic-api-single-step/monetization) or [Main API monetization](/api-integration/main-api-multi-step/monetization) for more details. #### ✔ Supported Chains and Protocols * Solana * Thorchain (When the source chain isn’t EVM-based) * MayaProtocol (When the source chain isn’t EVM-based) * Centralized Protocols (e.g. XO Swap, SWFT Allchain Bridge, etc.) {% hint style="info" %} **Notices** * All payments will be on the BSC blockchain at the end of the month, unless another chain is agreed. {% endhint %} ## Rango's Share In both Instant Settlement (Direct Fees) and Monthly Settlement (Manual Fees), Rango charges 15 bps alongside the amount set by the API/SDK or Widget configuration. This fee remains consistent across all supported chains for now and may vary based on different situations in the future. {% hint style="success" %} Our team is open to negotiating the fee sharing with dApps and wallets, and we are pleased to offer exceptional discounts for the first 6 months on both instant and monthly settlement programs. {% endhint %} ## How To Participate ### B2C: Individual Users Individual users who wish to participate in our Affiliate Program and earn affiliate fees can easily do so by following these steps: 1. Generate Referral Code: Visit our Affiliate Program page at to create your unique link. 2. Share Link Code: Once you have generated your referral link, share it with friends, family, or anyone interested in swapping digital assets. 3. Earn Affiliate Fees * Whenever someone signs a transaction on supported chains and swappers using your referral link, you will earn affiliate fees. The way you receive these fees depends on the chains and swappers involved. * For transactions on chains and swappers with Instant Settlement support, you will receive the affiliate fees instantly. * For transactions on chains and swappers with Monthly Settlement support, your earnings will be accumulated throughout the month and paid out monthly when the accumulated amount exceeds $10. * Note that you will earn 10bps from the user input amount for the swap. (Customisable percentage options will be available in the upcoming version.) ### B2B: DApps & Wallets Other services, including dApps, can integrate our API to participate in our affiliate program. The process of generating referral codes and earning affiliate fees is the same as for individual users. Services can access the affiliate program features by integrating either the Multi-step API or Basic API or by using our widget. * [How to enable affiliate in Basic API (Single-Step API)](/api-integration/basic-api-single-step/monetization) * [How to enable affiliate in Main API (Multi-Step API)?](/api-integration/main-api-multi-step/monetization) * [How to enable affiliate in Widget?](/widget-integration/monetization) ## Tracking Affiliate Revenue Affiliates can monitor their activities and earnings through the Rango Affiliate Program page. Detailed views of referred users' actions and earnings help affiliates optimize their strategies. For DApps, Rango offers detailed APIs for more granular tracking and integration. ## Upcoming Features * In the next version of our affiliate system, you will also be able to manage your affiliate settings via a dedicated dashboard. # Fee Structure Rango Fee Structure ## **Introduction** Rango is a versatile platform that facilitates swaps, asset bridging, and aggregation across multiple blockchains. Understanding Rango's fee structures and affiliate program is essential for users and affiliates to make informed decisions. This guide outlines the different types of fees, how to participate in the affiliate program, and key considerations for using the platform. ## Types of Fees in Rango ### Network Fee Network fees, or gas fees, are necessary for processing blockchain transactions. Rango estimates these fees during the quote / routing step, often using higher gas limits and with safety factor multipliers. This approach is taken to: * Account for Inaccurate Gas Estimates: EVM-based blockchains can sometimes provide inaccurate gas estimates for complex transactions. If the gas limit is set too low, the transaction might fail if it requires more gas than initially estimated. * Ensure Transaction Success: By applying safety factors, Rango sets the gas limit higher than the estimated requirement. This buffer helps ensure that transactions are completed successfully, even if gas usage temporarily spikes beyond the initial estimate. Additionally, EIP-3529 introduced changes to Ethereum's gas refund mechanism, reducing the maximum gas refund available but still allowing refunds for unused gas. This means that if Rango overestimates the gas required for a transaction, any unused gas is refunded to the user, ensuring cost efficiency. Read this [article](https://docs.rango.exchange/api-integration/network-fees-and-gas-estimates) for detailed discussion on network fees ### Rango Fee Rango generally charges a fee as a fixed percentage of the transaction amount, which is usually deducted from the user's origin wallet. However, this fee structure can vary depending on the specific swap and the blockchain involved. For instance, in BTC to ATOM swaps via Thorchain, the fee is charged in RUNE, Thorchain's native token, rather than in the original or destination asset. In other cases, such as swaps facilitated by the Jupiter Protocol on the Solana blockchain, the Rango fee is deducted from the output asset. For example, if you're swapping SOL to USDC on Solana, the fee will be taken from the USDC you receive, reducing the amount of USDC delivered to your wallet. The percentage of the fee varies based on the type of transaction and the specific assets being swapped. This structure allows Rango to cover operational costs while providing flexibility to accommodate different blockchain protocols and assets. ### Swapper Fee Swapper fees are charges applied by the protocols that facilitate swaps, bridging, or asset aggregation. These fees are typically a percentage of the transaction amount and are collected by the respective protocols, not Rango. They cover the costs and operational expenses associated with executing these transactions. ### Affiliate Fee [Rango's Affiliate Program](/technical/monetization) allows users to earn fees by referring others. There are two settlement methods: 1. Instant Settlement (Direct Fee): Affiliates earn fees immediately when their referrals complete transactions on supported EVM chains and protocols, such as Polygon, Ethereum, and OneInch. The fee is credited right away to the affiliate's account on the origin chain. Instant settlement is available exclusively for transactions where the origin chain is EVM-based. 2. Periodic Settlement (Manual Fee): For certain transactions, particularly on non-EVM chains or specific swappers and bridges where instant settlements aren't available, affiliate fees are accumulated and paid out periodically, typically at the end of each month. Rango shares 50% of these collected fees with the affiliates. {% hint style="warning" %} **Note** * The periodic settlement method will soon be deprecated, with all settlements transitioning to the instant model for enhanced efficiency and quicker payouts. * Rango currently does not support the affiliate program on Solana, Cosmos, and Tron chains. {% endhint %} {% hint style="info" %} **Rango's Share** * Rango typically adds a 0.15% fee on top of the affiliate fee. However, decentralized applications (dApps) participating in the affiliate program have the flexibility to add their own fees on top of Rango's share. This allows dApps to set a total fee structure that suits their business model and user base. * Additionally, Rango is open to negotiating special deals and offers tailored to the needs of individual dApps. This flexibility can help dApps optimize their revenue while providing users with competitive fee structures. * For more detailed information or to discuss potential deals, please contact us through our official channel at [Telegram](https://t.me/Rango_Marketing). {% endhint %} ## How fees are deducted from users? Rango uses three methods to deduct fees: 1. `FROM_SOURCE_WALLET`: Fees are taken from the user's source wallet. 2. `DECREASE_FROM_OUTPUT`: Fees are deducted from the estimated output, handled by Rango, so dApps do not need to adjust the output manually. 3. `FROM_DESTINATION_WALLET`: Fees are taken from the destination wallet, typically for bridges requiring a claim transaction. ## **Impact of `avoidNativeFee` parameter** The `avoidNativeFee` option excludes swappers that require native tokens for bridging, benefiting users without these tokens, such as those using Account Abstraction (AA) accounts and Gasless Wallets. However, it may limit available swappers and routes, potentially increasing costs due to less competitive rates. {% hint style="info" %} **Note:** `avoidNativeFee` simplifies fee payments but does not exempt users from paying blockchain (network) fees with native assets. This setting only affects swappers' service fees. {% endhint %}
# Network Fees and Gas Estimates When Rango API provides a quote response, we try to provide an accurate estimation of fees. For the actual transaction creation however, especially EVM transactions, we suggest higher gaslimits and bridge fees in order to make sure the transaction is not processed by the network (or bridge). To achieve this goal, we apply safety factor multipliers to network fees and some bridge fees to reduce transaction failure rate. **Does this mean the user pays higher fees? No.** There are multiple reasons for using higher gaslimits and fees. EVM RPCs are not very good at estimating gas for complex transactions. The problem becomes even more complex if we consider gas refunds and net gas estimates. For example imagine a transaction consumes 800k gas, but during the execution, the gas consumption up goes to 900k and at the end of the transaction 100k gas is refunded, netting the predicted 800k gas consumption. However, if the user sets 800k gas on transaction, the tx will fail because it cannot consume more than 800k to reach the 900k gas consumption, even if the user will be refunded 100k. **Therefore, for this example, when we estimate the fees, we use 800k gas, but when we create the transaction, we use 900k gas.** As an example, you can take a look at this tx that has ran out of gas with a gaslimit of 695,624. ([Link](https://bscscan.com/tx/0xd368e3f13714587861e5e3367d9bbd32f1528d093988305b74794e87f505f88a)) But if we simulate the same transaction with a higher gasLimit, in this example, 795,624, we see that the transaction is successful and the gas used is 641,006 which is even lower than the original tx that failed. ([Simulation Link](https://dashboard.tenderly.co/shared/simulation/90cd13cb-ac06-4eb3-a971-784d28c186b3)) Some bridges have a similar model and we apply a safety factor for the bridge fee. In such cases, the user is refunded if the it has paid more fees than neccessary. Note: In the future we will provide the safety factors that we use in the APIs. This way, third parties can have a better estimate of the actual costs and what is safe to use for transaction execution. Some useful links: * [StackExchange Discussion](https://ethereum.stackexchange.com/questions/150102/evm-gas-refund-and-total-gas-calculation) * [Storage Gas Refunds](https://www.evm.codes/#55?fork=shanghai) and [EIP-3529](https://eips.ethereum.org/EIPS/eip-3529) # Stuck Transactions Our aggregation processes and contracts are designed such that in case of a failure, the tokens are refunded to the user automatically in almost all cases. In some edge cases such as invalid opcodes, token transfer taxes and rebasing tokens, the transaction might get stuck. In this guide we provide info to how to unstuck transactions for different bridges. ### Wormhole: Use the official guide of wormhole for redeeming tokens: \[[Link](https://docs.wormhole.com/wormhole/archive/tutorial-recovery-workflow)] ### CBridge: Go to Celer cBridge [website](https://cbridge.celer.network/) and connect your wallet, then check your transfer history. Find your transfer and click *'Request Refund'.* {% hint style="info" %} In case you couldn't solve your issue by this manual, feel free to create a ticket on discord or contact our mods and admins in telegram. {% endhint %} # Overview Rango Widget Playground ## Introduction The Rango Widget presents a user-friendly and effective solution for facilitating cross-chain swaps within your dApp. The widget's versatility allows you to customize it according to your precise needs and preferences. We encourage you to explore the full potential of the Rango Widget and leverage its capabilities to enhance your dApp's functionality using [widget playground](https://playground.rango.exchange/\\).
## Playground The Widget Playground offers a user-friendly environment for you to explore different features of the Rango widget and customizing it based on your requirements. Once you've personalized the widget to your satisfaction, you can easily generate the code using "export button" for your preferred framework or the IFrame version. {% embed url="" %} ## Changelog You could check latest development on Rango Widget here: {% embed url="" %} {% hint style="info" %} We would greatly appreciate any feedback you may have in terms of specific requirements for functionality and customization. Your input is crucial to our development process, and we will prioritize your needs in our upcoming iterations. Thank you for your continued support. {% endhint %} ## Demo {% embed url="" %} # Quick Start Getting Start with Rango Widget ## Examples Here you could explore different examples of using widget for different frameworks: * [Parcel](https://github.com/rango-exchange/widget-examples/tree/main/parcel) * [Vite](https://github.com/rango-exchange/widget-examples/tree/main/vite) * [Next.JS](https://github.com/rango-exchange/widget-examples/tree/main/next) * [React App Rewired (JS)](https://github.com/rango-exchange/widget-examples/tree/main/react-app-rewired-js) * [React App Rewired (TS)](https://github.com/rango-exchange/widget-examples/tree/main/react-app-rewired-ts) * [Vue.js](https://github.com/rango-exchange/widget-examples/tree/main/vue) * [IFrame](https://github.com/rango-exchange/widget-examples/tree/main/iframe) ## Installation First you need to add `@rango-dev/widget-embedded` dependency. ```bash # using yarn yarn add @rango-dev/widget-embedded # or using npm npm install --save @rango-dev/widget-embedded ``` Then you could use this code snippet to easily add widget to your project. ```typescript import { Widget, WidgetConfig } from "@rango-dev/widget-embedded"; export default function App() { const config = { // This API key is only for test purpose. Don't use it in production. apiKey: 'c6381a79-2817-4602-83bf-6a641a409e32', // This project id is only for test purpose. Don't use it in production. // Get your Wallet Connect project id from https://cloud.walletconnect.com/ walletConnectProjectId: 'e24844c5deb5193c1c14840a7af6a40b', } return (
); } ``` {% hint style="info" %} **Get Your API KEY** Our service is currently free. But to use our API, SDK or Widget, you need to open a ticket in **users-support** channel of [Rango official Discord server](https://discord.gg/q3EngGyTrZ). Describe what your project does, what is the website and what are the social media handles in the ticket, the blockchains you like to connect to, and your dApp domain if it's a website to enable CORS headers for your API key. {% endhint %} ## IFrame Version If you want to use Rango widget directly in your html codes using IFrame, you code use code snippet below. ```html
``` ### IFrame Limitations Although using the iframe version is quite straightforward, we recommend utilizing the JavaScript package directly instead. This is because certain wallets, such as [Phantom](https://docs.phantom.app/resources/faq#why-cant-i-access-phantom-on-my-website) and MetaMask Mobile on iOS, have limitations when working with iframes due to security concerns, which may cause issues for users. # Customization Rango Widget Config ## Overview The `WidgetConfig` object allows you to customize your widget to fit your application's needs. The following sections provide a detailed breakdown of all available properties, organized by category. {% hint style="success" %} You can customize your widget in the [Playground](https://playground.rango.exchange/) and use the "Export Code" button at the top to obtain the final configuration. {% endhint %} *** ## 1. **Core Configuration** * **`apiKey`** (`string`) - **Required** * Your API key for accessing the Rango API. This key is required to make widget requests. * **`apiUrl`** (`string`) - Optional * The base API URL for custom API endpoints. * **`walletConnectProjectId`** (`string`) - Optional * The Wallet Connect Project ID used for integrating WalletConnect. Obtain it from [WalletConnect Cloud](https://cloud.walletconnect.com/). * **`title`** (`string`) - Optional * The title that appears on top of the widget. * **`variant`** (`WidgetVariant`) - Optional * The layout variant of the widget. * `'default'`: Standard view. * `'expanded'`: Expanded view showing multiple routes. * `'full-expanded'`: Full route information visible on the homepage. * **`amount`** (`number`) - Optional * The default value to be displayed in the swap input field. *** ## 2. **Blockchain & Token Configuration** * **`from`** (`BlockchainAndTokenConfig`) - Optional * Configuration for the source blockchain and token. * **blockchains** (`string[]`): A list of allowed source blockchains. * **blockchain** (`string`): The default blockchain. * **token** (`Asset`): The default token configuration. * **`to`** (`BlockchainAndTokenConfig`) - Optional * Configuration for the destination blockchain and token. * **blockchains** (`string[]`): A list of allowed destination blockchains. * **blockchain** (`string`): The default blockchain. * **token** (`Asset`): The default token configuration. * **`liquiditySources`** (`string[]`) - Optional * A list of allowed DEXes and bridges used for routing liquidity. * **`excludeLiquiditySources`** (`boolean`) - Optional * If set to `true`, the liquidity sources defined in `liquiditySources` will be excluded instead of included. * **`customDestination`** (`boolean`) - Optional * Enables the user to enter a custom blockchain address as the destination. *** ## 3. **Theme Configuration** * **`theme`** (`WidgetTheme`) - Optional * Customize the visual appearance of the widget. * **mode** (`'auto' | 'light' | 'dark'`): Defines the theme mode. * **fontFamily** (`string`): Sets the font for the widget. To do this, please also include your preferred font in your HTML file. * **colors** (`object`): Customize colors for both light and dark modes. (Please check playground to play with different colors and presets.) * **dark**: Color configuration for dark mode. * **light**: Color configuration for light mode. * **borderRadius** (`number`): The border radius for the widget container. * **secondaryBorderRadius** (`number`): The border radius for buttons within the widget. * **singleTheme** (`boolean`): If set to `true`, limits the widget to one theme (dark or light) based on the `mode` value. *** ## 4. Routing **Configuration** * **`routing`** (`Routing`) - Optional * **maxLength** (`number`): limit the maximum acceptable length of a route * **avoidNativeFee** (`'enabled' | 'disabled'`): Enable/disable avoid native fee. * **experimental** (`'enabled' | 'disabled'`): Enable/disable experimental routing. * **enableCentralizedSwappers** (`'enabled' | 'disabled'`): Enable/disable centralized swappers. *** ## 5. **Wallet & Signers Configuration** * **`wallets`** (string\[]) - Optional * A list of supported wallet types for connecting to the widget. Example: `['metamask', 'phantom']`. * **`multiWallets`** (`boolean`) - Optional * If set to `true`, the user can connect multiple wallets. Otherwise, he could only connect one wallet at the same time. (Not recommended) * **`externalWallets`** (`boolean`) - Optional * Allows external wallet integration. * **`signers`** (`SignersConfig`) - Optional * Custom RPC configuration for specific blockchains. * **customSolanaRPC** (`string`): Custom Solana RPC endpoint URL. * **`trezorManifest`** (`TrezorManifest`) - Optional * Required for integrating Trezor wallets. Provide your app's URL and a contact email. * **email** (`string`): your email address * **appUrl** (`string`): your application URL * **tonConnect** (`TonConnectConfig`) - Optional * Required for integrating Ton wallets. * **manifestUrl** (`string`): The link to your app URL containing your app URL, name and iconUrl. Sample: *** ## 6. **Affiliate Configuration** * **`affiliate`** (`WidgetAffiliate`) - Optional * Configuration for charging affiliate fees. Please check widget [monetization guide](/widget-integration/monetization). * **ref** (`string`): Your affiliate referral code. * **percent** (`number`): The percentage of fees charged per transaction. * **wallets** (`object`): A map of blockchain names to affiliate wallet addresses. *** ## 7. **Feature Toggles** * **`features`** (Features) - Optional * Controls the visibility of various features. For example, you could hide the theme or language settings in widget if you want to control it from your dApp. * **theme** (`'visible' | 'hidden'`): Show/hide the theme feature. * **language** (`'visible' | 'hidden'`): Show/hide the language selector. * **connectWalletButton** (`'visible' | 'hidden'`): Show/hide the connect wallet button. * **notification** (`'visible' | 'hidden'`): Show/hide the notification icon. * **liquiditySource** (`'visible' | 'hidden'`): Show/hide liquidity source information. * **customTokens** (`'visible' | 'hidden'`): Show/hide the custom token feature.
*** ## Sample Configuration Code ```javascript javascriptCopy codeconst config = { apiKey: 'c6381a79-2817-4602-83bf-6a641a409e32', walletConnectProjectId: 'e24844c5deb5193c1c14840a7af6a40b', title: 'My Custom Widget', amount: 1, from: { blockchains: ['BTC', 'LTC', 'BCH'], blockchain: 'BTC', token: { blockchain: 'BTC', symbol: 'BTC' } }, to: { blockchains: ['ETH'], blockchain: 'ETH', token: { blockchain: 'ETH', symbol: 'ETH' } }, theme: { mode: 'dark', colors: { dark: { background: '#000', primary: '#1C3CF1' }, light: { background: '#FFF', primary: '#1C3CF1' } }, borderRadius: 10 }, wallets: ['metamask', 'wallet-connect-2'], affiliate: { ref: 'your-affiliate-code', percent: 1, wallets: { 'ETH': '0x123...', 'BSC': '0xabc...' } }, liquiditySources: ['Uniswap', 'SushiSwap'], excludeLiquiditySources: false, language: 'en', multiWallets: true, customDestination: true }; ``` # Monetization How to enable affiliate in Rango Widget? You can charge widget users a fee for any of their successful transactions performed through the widget. Below, we present a detailed tutorial on activating affiliate functionality for your decentralized application (dApp) using the Rango Widget Config. ## 1. Create Affiliate Ref Code To begin, you should navigate to the [Rango dApp affiliate section](https://app.rango.exchange/affiliate) and establish a connection with your EVM-compatible wallet. From there, you can generate a referral link by clicking on the "Invite Friends" button.
After creating the link, you will notice that your `affiliateRef` code is located at the end of the link, similar to the illustration provided. By default, Rango will utilize the wallet address you used during the link creation process to deliver your affiliate reward. ## 2. Update Widget Affiliate Config By utilizing the `affiliateRef` that you generated in step 1, you can enable the fee collection feature within the widget by passing this parameter to the widget configuration as shown below: 
import { Widget, WidgetConfig } from "@rango-dev/widget-embedded";

export default function App() {

  const config = {
    // This API key is only for test purpose. Don't use it in production.
    apiKey: 'c6381a79-2817-4602-83bf-6a641a409e32',
    affiliate: {
      // The affilaite ref code you've created on step above
      ref: 'YOUR_AFFILIATE_REF_CODE',
      // The affiliate percent you want to charge users based on input amount
      // Setting 0.1 means 0.1% of input amount
      percent: 0.1,
      // If you want to change the default wallet that you want to earn reward,  
      // you could pass your desired wallets in this property 
      wallets: {
        'ETH': 'your wallet',
        'BSC': 'your wallet',
        'POLYGON': 'your wallet',
        // ...
      }
    }
  }
              
  return (
    <div className="App">
      <Widget config={config} />
    </div>
  );
}
Whenever a user initiates a swap using the Rango Widget, you will receive a referral percent of 0.1% from the input amount. If desired, you can customize the affiliate percent by including the parameter "affiliate.percent" in the configuration. Please note that the maximum allowed value for the affiliate percent is 3 percent. # React Router How to use Rango Widget with React Router? In case React Router is being used in your project, the following code snippet can be used to integrate Rango Widget. ```typescript import React from 'react'; import { Route, Routes } from 'react-router-dom'; import { Widget } from '@rango-dev/widget-embedded'; export function App() { return ( } /> ); } ``` Alternatively, if React Router is not being utilized, Rango Widget functions seamlessly with its integrated memory router. # Events Subscribe to Rango Widget Events Various types of events are triggered as a result of different scenarios and states. You can subscribe to these events to implement your custom logic in your dApp. The events emitted from the widget can be categorized into four distinct groups, each of which is explained below. There are different events that will be triggered: ```typescript export type Events = { [WidgetEvents.RouteEvent]: RouteEventData; [WidgetEvents.StepEvent]: StepEventData; [WidgetEvents.QuoteEvent]: QuoteEventData; [WidgetEvents.WalletEvent]: WalletEventData; [WidgetEvents.UiEvent]: UiEventData; }; ``` ## Route Events Once a user executes a route within Rango Widget, various events will be triggered depending on the different states of the route. You can subscribe to these events to implement your custom logic related to executing routes. For instance, you can display a personalized notification whenever a route succeeds or fails. Here is a sample code: ```typescript import { useEffect } from "react"; import { Widget, widgetEventEmitter, WidgetEvents, } from "@rango-dev/widget-embedded"; export function Component() { useEffect(() => { widgetEventEmitter.on(WidgetEvents.RouteEvent, (routeEvent) => { const { event, route } = routeEvent; // your custom logic goes here }); return () => widgetEventEmitter.off(WidgetEvents.RouteEvent); }, [widgetEventEmitter]); } ``` Here is a sample usage: ```typescript widgetEvents.on(WidgetEvents.RouteEvent, ({ route: Route; event: RouteEvent }) => {}) ``` And these are related types declarations for route events: ```typescript type RouteEvent = | Event | Event | Event; type RouteEventData = { route: Route; event: RouteEvent }; ``` ## Step Events Once a user executes a swap within Rango Widget, various events will be triggered depending on the different states of each step transactions. You can subscribe to these events to implement your custom logic related to executing steps of each transaction. For instance, you can display a personalized notification whenever a step of a transaction succeeds or fails. Here is a sample code: ```typescript import { useEffect } from "react"; import { Widget, widgetEventEmitter, WidgetEvents, } from "@rango-dev/widget-embedded"; export function Component() { useEffect(() => { widgetEventEmitter.on(WidgetEvents.StepEvent, (stepEvent) => { const { event, route, step } = stepEvent; // your custom logic goes here }); return () => widgetEventEmitter.off(WidgetEvents.StepEvent); }, [widgetEventEmitter]); } ``` Here is a sample usage: ```typescript widgetEvents.on(WidgetEvents.StepEvent, ({ route: Route; step: Step; event: StepEvent }) => {}) ``` And these are related types declarations for step events: ```typescript type StepStartedEvent = Event; type StepSucceededEvent = Event< StepEventType.SUCCEEDED, SucceededStepEventPayload >; type StepFailedEvent = Event; type StepTxExecutionUpdatedEvent = Event< StepEventType.TX_EXECUTION, StepExecutionEventPayload >; type StepTxExecutionBlockedEvent = Event< StepEventType.TX_EXECUTION_BLOCKED, StepBlockedEventPayload >; type StepCheckStatusEvent = Event; type StepApprovalTxSucceededEvent = Event; type StepOutputRevealedEvent = Event< StepEventType.OUTPUT_REVEALED, OutputRevealedEventPayload >; type StepEvent = | StepStartedEvent | StepSucceededEvent | StepFailedEvent | StepTxExecutionUpdatedEvent | StepTxExecutionBlockedEvent | StepCheckStatusEvent | StepApprovalTxSucceededEvent | StepOutputRevealedEvent; type StepEventData = { route: Route; step: Step; event: StepEvent }; ``` ## Wallet Events Once a user connects or disconnects a wallet within Rango Widget, various events will be triggered depending on the different states of the wallet. You can subscribe to these events to implement your custom logic related connecting or disconnecting wallets. For instance, you can display a personalized notification whenever a wallet connects or disconnects. Here is a sample code: ```typescript import { useEffect } from "react"; import { Widget, widgetEventEmitter, WidgetEvents, } from "@rango-dev/widget-embedded"; export function Component() { useEffect(() => { widgetEventEmitter.on(WidgetEvents.WalletEvent, (walletEvent) => { const { type, payload } = walletEvent; // your custom logic goes here }); return () => widgetEventEmitter.off(WidgetEvents.WalletEvent); }, [widgetEventEmitter]); } ``` Here is a sample usage: ```typescript widgetEvents.on(WidgetEvents.WalletEvent, (walletEvent: WalletEventData) => {}); ``` And these are related types declarations for wallet events: ```typescript enum WalletEventTypes { CONNECT = "connect", DISCONNECT = "disconnect", } type WalletEventData = | EventData | EventData; type ConnectWalletEventPayload = { walletType: string; accounts: Account[]; }; type DisconnectWalletEventPayload = { walletType: string; }; ``` ## Quote Events Once inputs or outputs for a quote gets updated within Rango Widget, various events will be triggered to demonstrate the changes in inputs and output. You can subscribe to these events to implement your custom logic related to updating inputs and outputs. For instance, you can update the ui of your website if a certain blockchain or token is selected in inputs. Here is a sample code: ```typescript import { useEffect } from "react"; import { Widget, widgetEventEmitter, WidgetEvents, } from "@rango-dev/widget-embedded"; export function Component() { useEffect(() => { widgetEventEmitter.on(WidgetEvents.QuoteEvent, (quoteEvent) => { const { type, payload } = quoteEvent; // your custom logic goes here }); return () => widgetEventEmitter.off(WidgetEvents.QuoteEvent); }, [widgetEventEmitter]); } ``` Here is a sample usage: ```typescript widgetEvents.on(WidgetEvents.QuoteEvent, (quoteEvent: QuoteEventData) => {}); ``` And these are related types declarations for route events: ```typescript enum QuoteEventTypes { QUOTE_INPUT_UPDATE = "quoteInputUpdate", QUOTE_OUTPUT_UPDATE = "quoteOutputUpdate", } type QuoteEventData = | EventData | EventData; type QuoteInputUpdateEventPayload = { fromBlockchain?: string; toBlockchain?: string; fromToken?: { symbol: string; name: string | null; address: string | null }; toToken?: { symbol: string; name: string | null; address: string | null }; requestAmount?: string; }; type QuoteUpdateEventPayload = Pick< SelectedQuote, "requestAmount" | "swaps" | "outputAmount" | "resultType" | "tags" > | null; ``` ## UI Events Once a user does some certain actions on the widget UI, various events will be triggered depending on the action of user. You can subscribe to these events to implement your custom logic related to actions of users. For instance, you can display a personalized wallet connect modal when user clicks on "Connect Wallet" button in the widget. Note: Currently, the only event triggered from UI is click on "Connect Wallet" button. Here is a sample code: ```typescript import { useEffect } from "react"; import { Widget, widgetEventEmitter, WidgetEvents, } from "@rango-dev/widget-embedded"; export function Component() { useEffect(() => { widgetEventEmitter.on(WidgetEvents.UiEvent, (uiEvent) => { const { type, payload } = uiEvent; // your custom logic goes here }); return () => widgetEventEmitter.off(WidgetEvents.UiEvent); }, [widgetEventEmitter]); } ``` Here is a sample usage: ```typescript widgetEvents.on(WidgetEvents.UiEvent, (uiEvent: UiEventData) => {}); ``` And these are related types declarations for route events: ```typescript type PreventableEventPayload< T extends Record = Record > = { preventDefault: () => void; } & T; type ClickConnectWalletPayload = PreventableEventPayload; enum UiEventTypes { CLICK_CONNECT_WALLET = "clickConnectWallet", } type UiEventData = EventData; type ClickConnectWalletPayload = PreventableEventPayload; type PreventableEventPayload< T extends Record = Record > = { preventDefault: () => void; } & T; ``` # External Wallets Connecting to External Wallets Rango Widget comes with built-in integration for multiple wallet providers, and you can find a list of the latest supported wallets at this link: . Furthermore, it is also possible to connect Rango Widget to the wallets used in your dApp, enhancing the user experience. With this feature, when a user connects their wallet, such as Metamask, in your dApp, the corresponding wallet in the Rango Widget will be automatically connected as well, ensuring a seamless experience for the user. There is a field named `wallets` in widget config that you could pass if you want to enable external wallets. ```typescript type WidgetConfig = { // ... other props wallets?: (WalletType | ProviderInterface)[] } ``` If the wallets supported by your dApp are a subset of the wallets supported by Rango Widget, you can provide a list of wallet names as strings that specifically denote the wallets supported by your dApp. This enables Rango Widget to present only the relevant wallets to your users, ensuring a focused selection. Additionally, this allows for seamless connectivity between the widget wallets and the wallets used in your dApp, eliminating the need for any additional configuration or setup. ```typescript export enum WalletTypes { META_MASK = 'metamask', WALLET_CONNECT = 'wallet-connect', TRUST_WALLET = 'trust-wallet', KEPLR = 'keplr', PHANTOM = 'phantom', BINANCE_CHAIN = 'binance-chain', TRON_LINK = 'tron-link', COINBASE = 'coinbase', XDEFI = 'xdefi', CLOVER = 'clover', ARGENTX = 'argentx', FRONTIER = 'frontier', COSMOSTATION = 'cosmostation', COIN98 = 'coin98', SAFEPAL = 'safepal', TOKEN_POCKET = 'token-pocket', BRAVE = 'brave', MATH = 'math', EXODUS = 'exodus', OKX = 'okx', KUCOIN = 'kucoin', LEAP = 'leap', LEAP_COSMOS = 'leap-cosmos', STATION = 'station', ENKRYPT = 'enkrypt', TAHO = 'taho', } ``` On the other hand, you have the option to implement the `ProviderInterface` and pass it to the `wallets` array. This interface allows you to customize and integrate additional wallet providers into Rango Widget. We will soon provide a sample implementation of the ProviderInterface to assist you in this process. Stay tuned for further updates and information on how to utilize this feature effectively. ```typescript export type ProviderInterface { type: WalletType; defaultNetwork?: Network; checkInstallation?: boolean; isAsyncInstance?: boolean; connect: Connect; getInstance: any; disconnect?: Disconnect; subscribe?: Subscribe; switchNetwork?: SwitchNetwork; getSigners: (provider: any) => SignerFactory; canSwitchNetworkTo?: CanSwitchNetwork; getWalletInfo(allBlockChains: BlockchainMeta[]): WalletInfo; } ``` # Architecture Rango Smart Contracts Architecture {% hint style="info" %} The contract code and architecture is discussed briefly to give an overview of the smart contracts. However, the contracts should only be used through Rango's API and contract details that are not discussed here. {% endhint %} {% hint style="info" %} Rango Smart Contracts Code is open source and available at this Github repository: {% endhint %} ## Overview Rango v2 contracts are designed to handle swaps and bridge transactions and also message passing transactions. There are two main type of contracts: * `Diamond` : Handles swap and bridge transactions (RangoDiamond.sol) * `Middlewares` : Receives token and message on destination chain and handles the transaction RangoDiamond is based on [EIP-2535](https://eips.ethereum.org/EIPS/eip-2535) and [v3 implementation](https://github.com/mudgen/diamond-3). The functionality and support for each bridge is handled by a separate facet. All swapping protocols are handled by a single facet. For example: * Axelar (Satellite): [RangoSatelliteFacet.sol](https://github.com/rango-exchange/rango-contracts-v2/tree/main/contracts%2Ffacets%2Fbridges%2FRangoSatelliteFacet.sol) * THORChain: [RangoThorchainFacet.sol](https://github.com/rango-exchange/rango-contracts-v2/tree/main/contracts%2Ffacets%2Fbridges%2Fthorchain%2FRangoThorchainFacet.sol) * Stargate: [RangoStargateFacet.sol](https://github.com/rango-exchange/rango-contracts-v2/tree/main/contracts%2Ffacets%2Fbridges%2FRangoStargateFacet.sol) * Stargate Middleware: [RangoStargateMiddleware.sol](https://github.com/rango-exchange/rango-contracts-v2/tree/main/contracts%2Ffacets%2Fbridges%2FRangoStargateMiddleware.sol) * 1inch, Paraswap, uniswap v2, v3 & forks etc: [RangoSwapperFacet.sol](https://github.com/rango-exchange/rango-contracts-v2/tree/main/contracts%2Ffacets%2Fbase%2FRangoSwapperFacet.sol) Example scenario: Swap 100 USDT on chain A to DAI on chain B

Swap + Bridge, in one transaction

Example scenario: Swap 100 USDT on chain A to BUSD on chain B through a `Middleware` contract

Swap + Bridge + Swap, in one transaction

Example scenario: Swap 100 USDT on chain A to BUSD on chain B through a `Middleware` contract and call a third-party dApp contract.

Swap + Bridge + Third-party Contract Call, in one transaction

## Bridges Facet Code Structure Bridge Facets follow a pattern of having two `external` functions which are the main entry points: * One function for direct bridging: * Stargate: `function StargateBridge(...) external` * Wormhole: `function wormholeBridge(...) external` * Another function for swap and bridge: * Stargate: `function StargateSwapAndBridge(...) external` * Wormhole: `function wormholeSwapAndBridge(...) external` To handle the interaction with the bridge, each bridge has one or more `internal` functions where the name is like `doBridge`: * Stargate: `function doStargateSwap(...) internal` * Symbiosis: `function doSymbiosisBridge(...) internal` In summary, the contract code architecture looks like this: ```solidity contract RangoSatelliteFacet { // entrypoint external function to swap and then bridge function satelliteSwapAndBridge( LibSwapper.SwapRequest memory request, LibSwapper.Call[] calldata calls, IRangoSatellite.SatelliteBridgeRequest memory bridgeRequest ) external { ... LibSwapper.onChainSwapsPreBridge(...) // swapping ... doSatelliteBridge(...); // interact with the bridge } // entrypoint external function to bridge function satelliteBridge( SatelliteBridgeRequest memory request, RangoBridgeRequest memory bridgeRequest ) external { ... doSatelliteBridge(request, token, amount);// interact with the bridge } // internal function where interaction logic with the bridge happens function doSatelliteBridge( SatelliteBridgeRequest memory request, address token, uint256 amount ) internal { ... // interact with bridge IAxelarGateway(s.gatewayAddress).callContractWithToken( request.toChain, request.receiver, payload, request.symbol, amount); } } ``` ## Swap Code Structure The swap functionality for each bridge is very similar and the core implementation is handled by LibSwapper.sol and RangoSwapperFacet.sol To handle swap logic, we use two structs `SwapRequest` and `Call`. A swap transaction has one `SwapRequest` and one or more swap `Call`: The `SwapRequest` defines which tokens is to be swapped and which token should be received and some helper data: ```solidity struct SwapRequest { address requestId; address fromToken; address toToken; uint amountIn; uint platformFee; uint destinationExecutorFee; uint affiliateFee; address payable affiliatorAddress; uint minimumAmountExpected; bool feeFromInputToken; uint16 dAppTag; string dAppName; } ``` The `Call` defines the contract that should be given approval (`spender`) and the contract to be called (`target`) and the calldata to be sent to target contract (`callData`). Note that `Call` also defines swapFromToken and swapToToken which might be different from `SwapRequest`. This is because a swap can have multiple `Call`s and the `SwapRequest` needs to know initial and final token, but each `Call` might have its own tokens. ```solidity struct Call { address spender; address payable target; address swapFromToken; address swapToToken; bool needsTransferFromUser; uint amount; bytes callData; } ``` An example of helper function that uses `SwapRequest` and `Call`s in bridges is provided here: ```solidity function onChainSwapsPreBridge( SwapRequest memory request, Call[] calldata calls, uint extraFee ) internal; ``` ## Interchain Messages Code Structure In the case of sending a message across chains, we use a standard struct called `RangoInterChainMessage`. This object is used when a swap or contract call is needed on the destination chain. The message is received in the destination chain and is handled by the `Middleware` Contract specific to that bridge. ```solidity struct RangoInterChainMessage { address requestId; uint64 dstChainId; address bridgeRealOutput; address toToken; address originalSender; address recipient; ActionType actionType; bytes action; CallSubActionType postAction; uint16 dAppTag; // Extra message bytes dAppMessage; address dAppSourceContract; address dAppDestContract; } ``` ## Middleware Contracts Code Structure Each bridge has its own messaging model if it supports message passing. Therefore, there is no standard or pattern for interchain message calls for different bridges. But to keep the code clean, we have defined a parent contract([`RangoBaseInterchainMiddleware.sol`](https://github.com/rango-exchange/rango-contracts-v2/blob/main/contracts/facets/base/RangoBaseInterchainMiddleware.sol)) which all middlewares can inherit from in order to have functionalities such as whitelists and refunding. # Audit Reports Rango Smart Contracts Audit Reports Audits can be found in link below: ### PeckShield (2023/06/26): ### AstraSec (2024/09/25): ### AstraSec (2025/10/15): # Deployment Addresses ## Diamond
BlockchainAddress Louper Explorer
Ethereum0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Polygon0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Optimism0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Arbitrum0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Fantom0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
BNB0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Avalanche0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Cronos0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Moonbeam0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Moonriver0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Heco0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dExplorer
Polygon zkEVM0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Aurora0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Gnosis0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Boba Eth0xd9BdD77E9017C4727D3CdB87D91b7a0Fc7d63da4LouperExplorer
Boba BNB0xd9BdD77E9017C4727D3CdB87D91b7a0Fc7d63da4Explorer
Linea0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Base0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
ZkSync Era0x13598FD0986D0E33c402f6907F05Acf720224527LouperExplorer
Scroll0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Celo0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Blast0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Metis0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Mode0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
XLayer0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Taiko0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
Zora0x69460570c93f9DE5E2edbC3052bf10125f0Ca22dLouperExplorer
## Middlewares
NameAddress on EVMsAddress on Ethereum and Optimism (Cancun)Blockchains
MiddlewareStorage0x0484962f4Ff892Ee5608BE5eC80e2f461624a87C0x89fE77AF04DB303d612D7e7F4C1c5E8664EDbEf6
CBridgeMiddleware0xC1e311c06230C2fAe6425C07bB0a7C5fFCE9C7850x89fE77AF04DB303d612D7e7F4C1c5E8664EDbEf6Eth,Polygon,Optimism,Arbitrum,BNB,Fantom,Avalanche,Moonriver,Aurora
AcrossMiddleware0xB852e653f8FBC099F06DC9D61E269517a4990B730xd5C7176Ec638eF466c2Fee761762d9EAb673997dEth,Polygon,Optimism,Arbitrum,BNB,Fantom,Avalanche
StargateMiddleware0x7045F971e312f7F1e211b3085ACE9155DeB0a9760x5434eD2d9F5737986858de127545e8a2Fb6EB6aEEth,Polygon,Optimism,Arbitrum,BNB,Fantom,Avalanche
SymbiosisMiddleware0x3Caed470a3215a4D6648D5c684c429B7A371C2690x0b7728E6c51511E30788a3a393A3362d59Ca67AfPolygon,Optimism,Arbitrum,BNB,Avalanche
SatelliteMiddleware0x0ADFb7975aa7c3aD90c57AEa8FDe5E31a721E9bb0x901D602dCADE00e2d7384e3940a70Ef772A355c3Eth,Polygon,Optimism,Arbitrum,BNB,Fantom,Avalanche,Moonbeam
WormholeMiddleware0x87f9bE4D0478dF182C95CBBd761381699B3343420x93310c2A44C0Ea5B5381606d020980CC9B62f547Eth,Polygon,Optimism,Arbitrum,BNB,Fantom,Avalanche,Moonbeam
NitroMiddleware0xb05233e0779cA7952a27CBFF7c3820CFce9526b30x557BaBBa31BE0ca0571CF5dAf44fb8c42Ba10351
ConnextMiddleware0x4a91efC961913fC24bFAE6BC3Eb5457e34e8F7640x0F415542e35A05A2655e2b1a0a95FE1cc74e84A3
ChainFlip Middleware0x74C670A0BB4668F146FB5b97d0B4EA8eF60986dA0xB4231156BBF6025745046d9DE642A4eb242cD9ef
DeBridgeMiddleware0x3Abaeb6399D3fc44838D75b88e642182e4b826fE0xD9Dc714D617608c273DA943840A17e4F1092D766
# Message Passing The requirements and interface for your contract to receive messages along with tokens when bridging. You can pass a custom message of your choice along with the tokens that will be bridged. Your receiving contract must implement a custom interface that can be found in the docs. Your receiving contract address must be whitelisted on our system, after security checks and confirmation by our technical team. It is not possible to pass messages without tokens. {% hint style="info" %} To use message passing, your receiving contract address must be whitelisted on our smart contracts, after security checks and confirmation by our technical team. {% endhint %} You can see a sample smart contract that in this [link](https://github.com/rango-exchange/rango-contracts-v2/blob/main/contracts/utils/SampleDApp.sol), which can act as sender as well as a receiver contract. **Note: This sample contract is just for demonstration purposes and should not be used in production. Do not rely on this sample for security, functionality or logic.** Your receiver contract should implement \`IRangoMessageReceiver\` interface ([Link](https://github.com/rango-exchange/rango-contracts-v2/blob/main/contracts/interfaces/IRangoMessageReceiver.sol)). ```solidity interface IRangoMessageReceiver { enum ProcessStatus { SUCCESS, REFUND_IN_SOURCE, REFUND_IN_DESTINATION } function handleRangoMessage( address token, uint amount, ProcessStatus status, bytes memory message ) external; } ``` ### How Rango contracts interact with your contract: To understand how the contract is called, check below code ([Source](https://github.com/rango-exchange/rango-contracts-v2/blob/065111c6da323c3bd202399fbab114a48462ea55/contracts/libraries/LibInterchain.sol#L383-L404)). First the token is sent to your contract, then your contract is checked for being whitelisted by us for message passing. Then, your contract is called through `handleRangoMessage` function wrapped in a try/catch block. Therefore, when `handleRangoMessage` function is called on your contract, the bridged tokens are in your control as they are already sent to your contract. {% hint style="info" %} Important Note: The call to your contract is wrapped in try/catch block. Therefore, if any exceptions or failures happen in your contract, the transaction does not revert and the tokens that previously sent to your contract, will stay in your contract. Make sure to consider this in your security considerations. {% endhint %} ```solidity ... if (_token == LibSwapper.ETH) { LibSwapper._sendNative(immediateReceiver, _amount); } else { SafeERC20.safeTransfer(IERC20(_token), immediateReceiver, _amount); } if (thereIsAMessage) { require( messagingStorage.whitelistMessagingContracts[_dAppReceiverContract], "3rd-party contract not whitelisted" ); try IRangoMessageReceiver(_dAppReceiverContract) .handleRangoMessage(_token, _amount, processStatus, _dAppMessage) { emit CrossChainMessageCalled(_dAppReceiverContract, _token, _amount, processStatus, _dAppMessage, true, ""); } catch Error(string memory reason) { emit CrossChainMessageCalled(_dAppReceiverContract, _token, _amount, processStatus, _dAppMessage, false, reason); } catch (bytes memory lowLevelData) { emit CrossChainMessageCalled(_dAppReceiverContract, _token, _amount, processStatus, _dAppMessage, false, LibSwapper._getRevertMsg(lowLevelData)); } } ``` # DEXs & DEX Aggregators If you are a specific DEX or DEX aggregator and want to be integrated in Rango, you can contact us in Twitter, Telegram or Discord. # Rango Mobile SDK Android & iOS SDK of Cross-chain swap Currently Rango offers JavaScript SDK and API Endpoints. If you want to use Rango in Mobile Apps you can contact: * Create a ticket in users-support channel of [Rango's official Discord server](https://discord.gg/q3EngGyTrZ) * Send an email to [marketing@rango.exchange](mailto:Marketing@rango.exchange) SDKs for following languages/frameworks could be developed by Rango team: * Native Android (Java/Kotlin) * Native iOS (Objective C/Swift) * React Native * Flutter * Unity Game Engine (C#) * Other Programming Languages & Frameworks # Terms of Use Rango Exchange Terms of Service **Last Modified: May 7th, 2025** **Foreword** Thanks for considering Rango Exchange. Please review the following terms and conditions carefully before using our services. These Terms of Use (referred to herein as “Terms” or “these Terms”) explain the terms and conditions by which you can use and access services and products (collectively, “The Services”, “Rango Services” or “Our Services”) offered by Rango Exchange (“Rango Exchange”, “Rango”, “we”, “us”, “our”). Rango Services include but are not limited to: 1\. Rango Website, hosted on[ https://rango.exchange](https://rango.exchange/) (“the Website”) 2\. Rango interface or dApp, hosted on[ https://app.rango.exchange](https://app.rango.exchange/) 3\. All APIs provided by Rango Exchange, details on[ https://docs.rango.exchange](https://docs.rango.exchange/) 4\. Rango’s Smart Contracts, details on[ ](https://docs.rango.exchange/) 5\. Rango’s SDK, Widget & Playground, details on These Terms are consistently accessible on the Website, prevailing over any alternative versions or conflicting documents. You acknowledge that you have read, understood, accepted and agreed to comply unconditionally with all of the Terms, including our Privacy Policy, by accessing, browsing or using the Services in any capacity or submitting your acceptance through the option that is offered. The Privacy Policy is incorporated herein by reference, and it's subject to periodic updates. Please stop using the Services if you don't agree with these Terms and/or the Privacy Policy. **IMPORTANT NOTICE ABOUT ARBITRATION: BY USING OR ACCESSING OUR SERVICES, YOU AGREE TO SETTLE ANY DISPUTE WITH RANGO EXCHANGE THROUGH BINDING, INDIVIDUAL ARBITRATION INSTEAD OF GOING TO COURT. YOU ALSO AGREE TO A CLASS ACTION WAIVER, WHICH AFFECTS YOUR RIGHTS REGARDING DISPUTE RESOLUTION.** ### 1. Eligibility This Agreement applies from the first time you access the Services. You'll have to abide by them as long as you keep using the Services in any capacity. Our Services are **NOT available** to individuals or entities located in, citizens of, incorporated in, or with a registered office in the **United States of America** or any Prohibited Territories, referred to as Restricted Persons, as defined below. We do not grant exceptions. If you are a Restricted Person, do not attempt to access or use our services. The use of a virtual private network (VPN) or any other method by Restricted Persons to access or use of services is prohibited. By using our services, you confirm that you (a) are at least 18 years old; (b) comply with the laws of your jurisdiction; (c) are not located, established, or registered in any of the "Prohibited Territories" listed below; and (d) are not a "Restricted Person" as defined below. You may not use Rango Services if applicable law prohibits your usage. You also cannot use Rango Services if you reside in a jurisdiction where digital token transactions are prohibited or restricted by law. You are solely responsible for complying with all relevant laws and regulations concerning your use or access to Rango Services. Your usage of Rango Services is prohibited if it violates any applicable laws or regulations or aids in illegal activities. By utilizing the Services, you confirm that you have the legal capacity within your country to enter into contracts and subscribe to our Services. Your complete acceptance of these Terms is inferred. If you are unable to accept these Terms, either in full or in part, you must immediately cease using our Services. By using or accessing Rango Services, you confirm to us that you are not listed on any Sanction Lists and that you are not a Restricted Person, as defined below. "Sanction Lists" refer to any sanctions designations listed on economic/trade embargo lists and/or specially designated persons/blocked persons lists published by international organizations, as well as any state and governmental authorities of any jurisdiction, including, but not limited to, the lists of the United Nations, the European Union and its Member States, and the United States and United Kingdom sanctions lists. We make no representations or warranties that the information, products, or services provided through our services are suitable for access or use in jurisdictions outside our own. You are prohibited from accessing or using our services in any jurisdiction or country if it violates the laws or regulations of that jurisdiction or if it would require us to comply with the laws of, or any registration requirements of, such jurisdiction. We reserve the right to restrict the availability of our services to any individual, geographic area, or jurisdiction, at any time and at our sole discretion. Prohibited Territories. Rango does not interact with digital wallets located in, established in, or a resident of Myanmar (Burma), Côte D'Ivoire (Ivory Coast), Cuba, Crimea and Sevastopol, the so-called Donetsk People’s Republic, Democratic Republic of Congo, Iran, Iraq, Libya, the so-called Luhansk People’s Republic, Mali, Nicaragua, Democratic People’s Republic of Korea (North Korea), Somalia, Sudan, Syria, Yemen, Zimbabwe or any other state, country or region that is included in the Sanction Lists. You are prohibited from using any software or networking methods, including Virtual Private Networks (VPNs), to alter your internet protocol address or bypass, or attempt to bypass, this restriction. Restricted Individuals: Rango does not engage with digital wallets that have been previously categorized or identified by international organizations or any state and governmental authorities of any jurisdiction as belonging or being associated with individuals specially designated or included in the Sanction Lists ("Restricted Persons"). For the purposes of these Terms, Restricted Persons also encompass all individuals or entities residing in, citizens of, incorporated in, or having a registered office in the Prohibited Territories. Third-Party Limitations: Our Services may incorporate Third-Party Services. Your usage and interaction with these Third-Party Services are subject to the terms and conditions set by the respective third-party providers. This includes but is not limited to their eligibility criteria, restrictions on specific territories, restricted persons, or any other eligibility-related terms. Consequently, your access to certain products and/or features of our services may be restricted based on these third-party providers' terms. Please be aware that we solely facilitate your engagement with these Third-Party Services and assume no responsibility for any restrictions imposed by them. It is your responsibility to review and ensure compliance with the terms and conditions of these third-party providers. You are not subject to economic or trade sanctions administered or enforced by any governmental authority, including but not limited to the Office of Foreign Assets Control of the U.S. Department of the Treasury. You are not on any Sanctions List, including, but not limited to the United Nations Security Council Sanctions List or the Specially Designated Nationals and Blocked Persons List maintained by OFAC. You are not recognized as individuals who owned, controlled, or acted on behalf of persons listed on a Sanctions List, nor as individuals targeted by any sanctions laws, regulations, or embargoes imposed by the United Nations, United States, European Union, or similar governmental institutions. Additionally, your involvement must not breach any legal requirements, including anti-money laundering regulations. You will not access or use any of The Services to conduct, promote, or facilitate any illegal activities. You agree not to access Rango Services using any technology for the purposes of circumventing these Terms. The utilization of our Services must strictly adhere to legal guidelines as delineated in these Terms of Use. It is explicitly forbidden to employ the Services for: 1\. Violating any national or international laws or regulations, including those pertaining to anti-money laundering (AML), anti-terrorism, and anti-corruption. 2\. Exploiting or endangering minors through inappropriate content or actions. 3\. Transferring or using digital assets without rightful ownership or authorization. 4\. Engaging in illicit or abusive trading practices. 5\. Infringing upon the rights of others or participating in illegal, threatening, fraudulent, or harmful activities. 6\. Disabling, damaging, degrading, or obstructing the functionality of the Services or impeding others from utilizing the Services. 7\. Attempting to access the source code of the Services, reverse engineering, decompiling, or creating derivative works. 8\. Implementing disruptive elements like viruses or malware. 9\. Unauthorized attempts to access, disrupt, or damage the Services or associated infrastructure. 10\. Disrupting, degrading or negatively affecting the Services in any capacity through any act such as denial-of-service attacks. ### 2. Risk Assessment & Compliance By utilizing our Services, you accept the economic and technical risks associated with blockchain technology and cryptocurrencies, understanding that: \- Cryptocurrencies are built on an evolving blockchain technology that may experience failures, bugs, disruptions, or changes. \- The Services, blockchains, underlying technologies or third-parties may be exposed to cyber threats and attacks. \- Cryptocurrencies lack central bank backing and legal tender status, subject to varying legal frameworks. \- The accuracy, full or correct functioning, or timeliness of our Services or the underlying technologies or third-parties is not guaranteed. \- Cryptocurrencies may encounter regulatory restrictions, affecting their value. \- Cryptocurrencies' value is vulnerable to market fluctuations and risks of fraudulent activities. If you are in disagreement with these Terms, we regretfully advise refraining from using Our Services. By using Rango Services, you acknowledge and accept all associated risks. You also explicitly waive and discharge us from any liability, claims, actions, or damages arising from or connected to your use of Rango Services. Your Responsibility for Compliance: Rango Services may not be accessible or suitable for use in every jurisdiction. By accessing or using Rango Services, you acknowledge that you are solely responsible for complying with all relevant laws and regulations applicable to you. You also agree that we are not obligated to notify you of any potential legal liabilities or violations that may arise from your use of the Rango Services, and we are not liable for any failure on your part to comply with applicable laws or regulations. You acknowledge that you might need to undergo Know Your Client (KYC) and Know Your Business (KYB) checks via a third-party provider to access specific products or features. Declining to provide requested information could lead to access limitations. Compliance Verification: To maintain a secure and compliant environment within the Rango Network, certain products or features accessible through the Rango Services may require you to undergo a verification process. This process entails completing a Know Your Client (KYC) / Know Your Business (KYB) questionnaire ("KYC/KYB Checks") in accordance with applicable anti-money laundering, anti-terrorist financing, fraud prevention, and sanctions laws and regulations. The KYC/KYB Checks may be delegated to a third-party provider at the sole discretion of Rango. To complete these checks, you agree to promptly furnish all necessary information, including supporting documentation and other evidence, as reasonably requested by the third-party provider selected by Rango. You are solely accountable for the accuracy and comprehensiveness of the information provided. You recognize and comprehend that the outcome of the KYC/KYB Checks is solely determined by the third-party provider. Upon successfully passing these checks, you will gain access to the relevant products and/or features on Rango Services. However, if you decline or fail to provide the requested information as per the third-party provider's requirements, your access to the corresponding products and/or features of the Rango Services may be limited. You acknowledge that the extent of information requested as part of the KYC/KYB Checks may change over time. It's possible that you may be required to provide additional documents and/or information at a later stage. The data is collected to meet legal and regulatory requirements, ensuring the verification of your identity and legal eligibility. This data is securely stored and disclosed only when authorized by law. For further details on how your personal data is processed, please consult our Privacy Policy. We might utilize publicly accessible data and Third-Party Services to evaluate risks related to illicit or non-compliant activities, phishing attempts, or other potential threats. These risk assessment services could be offered by various third-party providers, including but not limited to: BlockAid, TRM Labs, Synaps, MetaMask, and MEW. You acknowledge and consent to risk assessment using Third-Party Services to monitor wallet addresses and/or other content for non-compliant behavior based on publicly available information. We retain the right to block or restrict access to wallet addresses associated with illicit activity. We bear no responsibility for such assessment, restrictions, outcomes, or the accuracy of Third-Party Services. Rango retains the right, without obligation, to utilize publicly accessible information and enlist third-party providers to monitor and evaluate your and/or other users' wallet addresses, third-party links, domain names, virtual currencies, smart contracts, and any other content accessible via the Rango Services for the risks associated with money laundering, terrorism financing, fraud, and/or any other illicit or non-compliant activities. No additional personal data is collected for such compliance assessments. You acknowledge and understand that the outcomes of compliance assessments are solely determined by third-party providers. Rango has no influence over or affiliation with these Third-Party Services, and therefore cannot be held responsible for the accuracy of the information or the services provided by such providers. These Third-Party Services are subject to their own respective terms of use, which you should carefully review. Rango retains the right, though not obligated, to issue warnings to you accordingly. You acknowledge that Rango bears no responsibility and shall not be held accountable for such assessments, restrictions, outcomes, or their accuracy. You are solely responsible for determining the applicability and suitability of such risk assessments. While we may offer phishing risk alerts via the Rango Services, we don't assure their accuracy or reliability. It's your responsibility to evaluate their relevance, and we're not liable for any claims or losses arising from these alerts. Phishing Alerts: Periodically, Rango might issue phishing and other potential risk alerts via the Rango Services. These alerts are solely for informational purposes, and we do not guarantee their accuracy, completeness, or reliability. You are solely responsible for determining the suitability and relevance of such alerts. You acknowledge and agree that risk alerts are provided "as is," without any warranties or guarantees, and that you assume all associated risks. Rango bears no responsibility and shall not be held liable for any claims, damages, or losses arising from or related to such alerts in any way. ### 3. Services **Scope** Rango Exchange has developed, operates, and offers the Services, an advanced online application designed to facilitate your utilization of a cross-chain DEX and bridge aggregator platform. This platform empowers you to seamlessly find the best routes inside and in between blockchains and execute token swaps and bridging transactions across a range of diverse blockchains. For further details, please consult our comprehensive documentation available at . **Token swaps** Within the "Swap" section, you gain the capability to initiate orders facilitated by Third-Party Services, enabling the conversion of Cryptocurrencies into other Cryptocurrencies or bridging (transferring) of Cryptocurrencies across blockchains. It's important to note that Rango Exchange does not possess or retain custody of your cryptocurrencies at any step. Instead, we function as an aggregator Service that interfaces with Third-Party Services. **Customer Support** Our dedicated customer support is readily accessible through our Discord and Telegram groups, as well as via . We have established and uphold an efficient procedure to promptly address any inquiries or concerns you may have pertaining to the Services. We commit to providing timely responses, taking into account the volume of ongoing requests. **User’s Wallet** You have the option to connect your digital wallet to the Services, facilitating the collection and display of relevant wallet information. At your discretion, you can choose to disconnect your wallet from the Services at any given time. In order to effectively engage with the Services, it might be necessary to connect a digital wallet. It is important to emphasize that the ownership and custodianship of digital assets held in your wallet consistently remain with you; this ownership does not transfer to Rango Exchange. We do not custody or own the data or digital assets in your wallet and we do not have the ability to transfer digital assets in your wallet. As the owner of your wallet and digital assets, you solely assume full responsibility for any associated risk or loss. Rango Exchange disclaims liability for fluctuations or losses in digital assets. Furthermore, you are solely accountable for safeguarding the private keys linked to your digital wallet. While Rango Exchange prioritizes the security of the platform, the additional responsibility of enhancing wallet security, such as properly securing credentials, private keys or secrets and keeping the wallet secured, remains with you. **API** Rango Exchange extends the availability of an API, accessible upon request or via the Website, providing access to the Services for Third-Party end users. Through this API, you gain the ability to establish a fee structure, mutually determined between you and the Service, as outlined in the API documentation. The utilization of the API is contingent upon the fulfillment of all provisions within these Terms to the fullest extent and without any exception. The following conditions govern the usage of the API: \- Selection of relevant configurations. \- Utilization exclusively for your purposes. \- Deployment for a fee-based purpose, necessitating the selection of the Partnership API. In the event of non-compliance with the aforementioned conditions or if based on our sole discretion believe that you might not have complied with the terms, Rango Exchange reserves the prerogative to promptly suspend your access to the Services, without prior notification. We will not be liable for any loss or lack of profit thereof as a result of decisions including but not limited to the full or partial suspension. **Pricing** We reserve the right to charge for our services and we reserve the right to provide the services without any charge based on our sole discretion. The employment of the Partnership API is subject to a fee structure, detailed conditions of which can be found at this link: ### 4. User's Responsibilities You hereby assure the Services against any breach exceeding foreseeable risks, stemming from your utilization of the Services. It is incumbent upon you to exclusively employ the Services in alignment with these stipulated Terms. Unauthorized activities, such as reconstructing the Services, decompiling, circumventing technical restrictions, and hosting Services for Third Parties, are expressly prohibited unless explicitly authorized by Rango Exchange. While using the Services, either on our website or indirectly or through APIs, you are required to abstain from actions or omissions that could potentially: \- Impede the seamless functioning of the Services. \- Compromise Rango Exchange's interests, rights, or reputation. \- Detrimentally impact Third Parties' interests, rights, or reputation. Rango Exchange reserves the right to suspend your access to the Services without prior notice or compensation, and to pursue legal remedies, including seeking damages, if your conduct contravenes these Terms, is unlawful, fraudulent, or harmful to other Users or the Services. ### 5. Disclaimers Please read the whole section carefully for specifics. It explains that we don’t make any warranties about the Services. The Services are presented "AS IS" and "AS AVAILABLE," necessitating operation under your sole responsibility. We do not make any warranty about the Services and we disclaim any representations or warranties whether explicit, implied or statutory. You acknowledge and consent that your use of the Services is at your own risk.. We make and expressly disclaim all representations and warranties, whether express, implied, or statutory, regarding the Rango Services and the proprietary or open-source code. Specifically, we do not represent or warrant, and expressly disclaim any such representation or warranty, including but not limited to, title, non-infringement, merchant-ability, usability, security, suitability, fitness for any particular purpose, workmanship, technical coding, or absence of defects, whether latent or patent. We do not assert or guarantee that the Rango Services, code, or any related information is accurate, complete, reliable, current, or error-free. The Rango Services are provided on an "as is" and "as available" basis, without any warranties of any kind, whether express or implied, including, but not limited to, implied warranties of merchant-ability, fitness for a particular purpose, or non-infringement. You acknowledge that no advice, information, or statement provided by us should be construed as creating any warranty regarding the Rango Services. We do not endorse, guarantee, or assume responsibility for any advertisements, offers, or statements made by third parties regarding the Rango Services. We are not responsible for transferring, protecting, or maintaining your private keys. You acknowledge that Rango is not responsible for transferring, safeguarding, or maintaining your private keys or any virtual currency associated with them. If you lose, mishandle, or have your associated virtual currency private keys stolen, you acknowledge that recovery of the associated virtual currency may not be possible, and Rango is not liable for such loss. Furthermore, you acknowledge that Rango is not responsible for any loss, damage, or liability resulting from your failure to adhere to the terms outlined herein. We make no representations or warranties about the functionality of our services or accuracy of data provided on our services be it live or historical data. You should verify all information before relying on it, and all decisions that you make directly or indirectly through our services are your sole responsibility and we have no liability for your decisions Except for the Terms outlined herein, please recognize that the information on the Website should not be construed as contractual information. Nothing on the Website constitutes an offer, invitation, or solicitation to buy or sell, nor an offering of cryptocurrencies. You understand and agree that the GitHub repository, decentralized and autonomous protocol and environment, and associated decentralized networks, are beyond Rango's control. Rango does not possess access to your private key and cannot initiate interactions with your virtual currency or access it in any way. Rango bears no responsibility for any activities you undertake while using your wallet or the Services. The information available on the Website serves purely informational purposes. While Rango Exchange endeavors to furnish comprehensive, accurate, reliable, and up-to-date information, it does not guarantee the ultimate completeness, accuracy, correctness, or suitability of such information for your specific situation at the time of access. Information shown on our services, including prices, liquidity, and staking details, is sourced from third parties or calculated for informational purposes only. We don't offer any warranties for such information. We provide no representations or warranty as to our services. Furthermore, we do not warrant uninterrupted, timely, or error-free access and use of the Services, nor do we guarantee protection against defects, malfunctions, viruses, malicious code, or other harmful elements. ### 6. Limitation of Liability and Indemnification IN NO EVENT AND UNDER NO CIRCUMSTANCES SHALL WE OR ANY OF OUR AFFILIATES AND SERVICE PROVIDERS, OR ANY OF THE RESPECTIVE OFFICERS, DIRECTORS, AGENTS, SUBSIDIARIES, JOINT VENTURES, EMPLOYEES OR REPRESENTATIVES, BE LIABLE FOR ANY DIRECT, INDIRECT, PUNITIVE, INCIDENTAL, INTANGIBLE, SPECIAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES OR LOSSES INCLUDING (BUT NOT LIMITED TO) LOSS OF PROFIT, COMMERCIAL DISRUPTION, LOSS OF GOODWILL OR REPUTATION, LOSS OR BREACH OF DATA OR ANY OTHER INTANGIBLE PROPERTY, ARISING OUT OF OR RELATING TO ACCESS, USAGE, INABILITY OR DELAY OF ACCESS, MAINTENANCE, PERFORMANCE OR LACK OF PERFORMANCE OF THE SERVICES EITHER DIRECTLY, THROUGH APIs OR THROUGH THIRD-PARTIES IN ANY CAPACITY, TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW. WE ASSUME NO LIABILITY OR RESPONSIBILITY FOR ANY OF: (I) ANY LOSS OR DAMAGE RESULTING FROM HACKING, BREACH, UNAUTHORIZED ACCESS OF OUR SERVICES (II) INACCURACIES, ERRORS, MISTAKES OF ANY SORT OF ANY DATA OR CONTENT OF OUR SERVICES (III) INTERRUPTION, DELAY OR NOT FUNCTIONING OF THE SERVICES OR LOSS OF ACCESS (IV) BREACH OR UNAUTHORIZED ACCESS OR USE OF ANY SERVER OR DATABASE IN OUR CONTROL, OR THE USE OR LEAK OF ANY INFORMATION OR DATA STORED THEREIN (V) PERSONAL INJURY OR PROPERTY DAMAGE IN ANY CAPACITY RESULTING FROM OF RELATED TO ACCESS OR USE OF THE SERVICES (VI) BUGS, VIRUSES OR ANY KIND OF MALICIOUS CODE OR DATA THAT CAN BE EXTERNAL AND UNRELATED TO THE SERVICES OR MIGHT BE TRANSMITTED THROUGH THE SERVICES (VII) ERRORS, OMISSIONS OR ANY MALICIOUS OR ILLEGAL CONDUCT OF ANY THIRD-PARTY. (VIII) REGULATIONS OR CHANGE OF REGULATIONS OF ANY JURISDICTION (IX) FORCE MAJEURE EVENTS. THIS LIMITATION OF LIABILITY APPLIES REGARDLESS OF WHETHER THE ALLEGED LIABILITY IS BASED ON CONTRACT, TORT, STATUTE, FRAUD, MISREPRESENTATION, NEGLIGENCE OR ANY OTHER LEGAL THEORY OR BASIS EVEN IF WE ARE EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND WHETHER THE ALLEGED LIABILITY ARISES AFTER THE TERMINATION OF THESE TERMS. IN NO EVENT AND UNDER NO CIRCUMSTANCES SHALL WE OR ANY OF OUR AFFILIATES, OFFICERS, DIRECTORS, AGENTS, SUBSIDIARIES, JOINT VENTURERS, EMPLOYEES OR REPRESENTATIVES, BE LIABLE TO YOU FOR ANY CLAIMS, PROCEEDINGS, OBLIGATIONS, DAMAGES, LOSSES OR COSTS IN AN AMOUNT EXCEEDING THAN THE AMOUNT YOU WERE CHARGED FOR ACCESS OR USAGE OF THE SERVICES OR A MAXIMUM OF $5. You agree to indemnify and hold Rango Exchange and its affiliates, subsidiaries, officers, directors, managers, employees, agents, joint ventures, subsidiaries, representatives, service providers, suppliers, and contractors harmless from any losses or damages whether actual or consequential, judgments, fines, and costs, including legal fees and expenses, arising from any claims or demands out of or related to your breach of this agreement, your usage of the services, misrepresentation or fraud by you, your violation of any law, rule, protocol or regulation or the rights of any third party. The Services give you the option to filter, include or exclude third-party services. The Service solely serves as an intermediary aggregation platform for Third Party Services, transmitting your requests to these entities. It is expressly your responsibility to evaluate and select Third Party Services for the relevant Service operation. Rango Exchange cannot be held liable for losses stemming from Third Party Service operations. ### 7. Privacy Policy You acknowledge that by using our services, we may process your personal data, including cookies, that is provided to us directly or indirectly. To acquire comprehensive insight into the processing of Personal Data by the Company, as well as its utilization of cookies, please refer to the Privacy Policy accessible on the Website. ### 8. Amendment Rango Exchange reserves the inherent right to modify or discontinue accessibility to either the entirety or a portion of the Services, the Website, and/or the applications and APIs at any given time based on our sole discretion. We retain the prerogative to amend these Terms of Use to encompass various scenarios, including but not limited to: (a) adjustments necessitated by evolving laws; (b) regulatory or security prerequisites; (c) pertinent guidance or codes of practice; (d) technical refinements to the Services; (e) enhancements to ensure clarity and uniformity; or (f) any other rationale deemed suitable at our sole discretion. Should modifications be implemented to these Terms of Use, we will duly update the "Last Modified" date indicated at the head of these Terms of Use. **Your continued utilization of the Services will signify your acceptance of any alterations incorporated into the updated version of the Terms of Use.** If you do not agree with the changes, you should stop using the Services. ### 9. Termination Under our exclusive discretion, we retain the right to promptly suspend or terminate your access to the Services, without the obligation of prior notice or incurring any liability. This termination may be executed for various reasons and without constraint, including but not limited to a violation of these prevailing Terms of Use. It's important to note that fees paid in association with the Services are non-refundable. In instances where termination is enacted due to a breach of these Terms of Use, fees will not be subject to reimbursement. In cases of termination for other reasons, it will be at our sole discretion to decide whether to return any fees, paid either by you or on your behalf, at the time of termination. This decision may be made with or without explanation or justification. All clauses within these Terms of Use that, by their nature, should extend beyond termination shall indeed remain in effect after termination. This encompasses ownership clauses, disclaimers of warranty, indemnification, and limitations of liability, among others. ### 10. Legal Inquiries For any legal questions or concerns, please contact us at `legal@rango.exchange`. Our team will respond to your inquiry as soon as possible.
# Privacy policy **August 10th, 2023** Rango Exchange (hereinafter the "Company" or “The Company”, “we”, “us”, “our”) would like to inform you of the way personal data is processed and collected when using Rango Exchange Services (DApp, API, SDK, Smart Contracts, Widget and other third-party integrations, collectively “Services”, “The Services” or “Our Services”). The same might apply if you use our Services on third-party websites or apps. We are determined to protect the privacy of our users and protection of your personal data and privacy are among our top priorities. Accessing or using our Services, either directly or through third-parties, means that you accept this privacy policy and its terms. To understand how we will treat your information, please carefully read this Privacy Policy. IF YOU ARE UNWILLING TO AGREE TO THIS PRIVACY POLICY, OR YOU DO NOT HAVE THE RIGHT, POWER AND AUTHORITY TO ACT ON BEHALF OF AND BIND THE BUSINESS, ORGANIZATION, OR OTHER ENTITY YOU REPRESENT, DO NOT ACCESS OR OTHERWISE USE THE SITE AND/OR APP. 1. **Collecting data and its purpose:** The Company collects your data for specific purposes, each of which is duly authorized by a valid legal basis. The information the Company collects: * IP address, cookie identifiers, domain server, data related to usage, performance, site security, traffic patterns, location information, browser and device information, referring/exit pages, operating system and browser language. This is only when you use our Services on our products and/or other Websites or Apps which use the Company's infrastructure. * Public data: the data that is available to the public, including but not limited to transactions on blockchains, wallet addresses and signed messages. Note that blockchain addresses and transaction info are public data that are not created by us or any other central party, and are not considered personally identifying. 2. **Here's how and why we use your Personal Information** Your Personal Information listed above may be used for the following purposes: * Providing and personalizing the Services to enhance our product user experience. * Our internal and operational purposes, when: ensuring security, identifying irregular website behavior, preventing fraudulent activity and improving security at all possible levels; * Assessing and improving the performance of the services we provide through our Site and/or infrastructure; * Analyzing the services we provide through our Site and/or App, including via Google Analytics, Hotjar and other analytics tools. 3. **Information that is not collected in any case** * We will NEVER ask you for your private keys, mnemonic phrase, wallet seed or any other personal information. Never provide your private keys or wallet seed to anyone or any website/form, and do not store it anywhere accessible by anyone other than you. * We will never contact you on any social media, messenger or other platform, asking you for personal information and/or your wallet information. You shall not send/submit these data on any website/form/email: Your wallet info, private keys, mnemonic phrase, seed phrase or any other private/personal information. 4. **Data recipients** * It may be necessary for the Company to share your Personal Data with third-party service providers that the Company uses to provide the service to you. These third-party services and providers might use your personal data with the purpose of performing their function as a service provider. The shared data with third parties will never include your personal data / sensitive information. * Furthermore, as the case may be, the Company shares your Personal Data with competent courts and any other governmental and/or public authorities requesting access to your Personal Data, to the extent legally permitted. * Furthermore, per the request of a court, legal investigation or any legal or governmental authority, the Company shares the collected data with the requesting entity on a need to know basis and in order to fulfill its duty and legal compliance. * The company may not be able to guarantee that the recipients of your Personal Information will maintain the privacy or security of such Personal Information if we are required to disclose any of your Personal Information in order to comply with official investigations or legal proceedings initiated by governmental and/or law enforcement officials. * Blockchains are transparent and decentralized and as an obvious result of using blockchains, your data such as transactions are stored on the blockchain and are public to anyone and therefore any third-party can access such data. 5. **Storage period** Based on our analysis of how long the specific data is reasonably required for legal or business purposes, we may maintain a Data Retention Policy detailing the retention period for Personal Information. Personal Information is securely destroyed or deleted when it is no longer required. Aggregated data, which cannot identify a device/browser (or individual) and is used for purposes of reporting and analysis, is maintained for as long as is commercially necessary. Business and legal requirements may require us to retain certain information for an extended period of time, for specific purposes. Reasons we might retain some data for longer periods of time include: * Security, fraud & abuse prevention. * Financial record-keeping. * Complying with legal or regulatory requirements. * Ensuring the continuity of our services at our Site and/or App. 7. **Data transfer** * In some cases, personal data may be processed outside of the European Union. In that situation, the Company shall take all necessary precautions and alternatively or cumulatively ensure that an adequacy decision has been taken by the European Commission regarding the country of destination; that contractual clauses adopted by the European Commission or the supervisory authority have been signed with the recipient; and that the recipient adheres to a code of conduct or certification mechanism that has been approved by the European Commission. 8. **The rights of the user** * As a data subject, you have a variety of rights regarding your Personal Data. These are as follows:\ \- Right to request from the Company access to and rectify or erasure of your Personal Data;\ \- Right to request from Company to stop processing your data;\ \- Right to object to processing of your Personal Data;\ \- Right to portability of your Personal Data; * You may exercise your rights or ask questions regarding the protection of Personal Data by contacting us by email at with proof of your identity. * To protect your personal data as well as the personal data of other users, we might require you to verify your identity before we take action based on your request. If we are unable to verify your identity, we might decline your request. * After receiving a request, the Company will endeavor to respond to your request without undue delay, and at the latest within four weeks of receiving the request. Depending on the complexity of the request, the company may extend this period to an additional twelve weeks. * Your Personal Data will be protected by the Company and in accordance with the applicable data protection regulations. 8. **Cookies**\ A cookie is a small text file that is placed on your computer by websites that you visit. It is widely used to make websites work, or to make them function more efficiently, as well as to provide information to the site's owners. Cookies are typically stored on the hard drive of your computer. In order to evaluate the effectiveness of our Site and/or App, we collect information from cookies. As a result of the information collected from cookies, we are able to determine the most popular sections of the Site and/or App, as well as the difficulties our visitors may have accessing them. Using this information, we can enhance your experience on the Site and/or App by identifying and providing more of the most requested features and information, as well as by resolving accessibility issues. * You are informed that information may be transmitted to Your browser or Equipment by the Service (“Cookies”). When You browse the Service for the first time, you may see a Cookie banner requesting You to accept, refuse or configure Cookies. * Please find below a presentation of Cookies on these websites:\ [Cloudflare](https://developers.cloudflare.com/fundamentals/get-started/reference/cloudflare-cookies/), [Hotjar](https://help.hotjar.com/hc/en-us/articles/6952777582999-Cookies-Set-by-the-Hotjar-Tracking-Code), [Google Analytics](https://policies.google.com/technologies/cookies?hl=en-US) * You have control over your cookies to accept, reject or remove Cookies. * The refusal of certain Cookies may affect the delivery of the Service provided and navigation on the Website. It is possible for our users to set which cookies are stored and to delete cookies in most browsers. In some circumstances, restricting the storage of cookies to certain websites or disallowing third-party cookies may render our website inoperable. The following steps will guide you through customizing cookie settings in the most common browsers: [Google](https://support.google.com/chrome/answer/95647?co=GENIE.Platform%3DDesktop\&hl=en) ; [Mozilla Firefox](https://support.mozilla.org/en-US/kb/clear-cookies-and-site-data-firefox) ; [Safari](https://support.apple.com/en-gb/guide/safari/sfri11471/mac) ; [Edge](https://support.microsoft.com/en-us/help/4027947/microsoft-edge-delete-cookies) and [Opera](http://help.opera.com/Windows/10.20/fr/cookies.html).