Rango
Rango Widget Customization for Embedded Swaps
Rango’s swap widget embeds configurable crypto trading inside an app or website with an API key. The integration combines a ready-made swap interface with theme settings, source and destination filters and wallet connections. Package and iframe formats have different integration requirements, especially around wallet access.
· updated
Bottom line: Preselected assets set the widget’s starting choices, while blockchain filters constrain which networks its users can select.
Package and Iframe Swap Interfaces
The swap widget combines asset selection, quotes and transaction execution in an interface an application can embed, reducing the swap UI its developers need to build. It supports same-chain trades and cross-chain swaps through the underlying aggregation service. The host app chooses how that interface fits its product, while available liquidity and supported connections determine which swaps it can offer. Embedding the interface doesn’t create liquidity for an otherwise unavailable pair.
The JavaScript package exposes a Widget component developers render with a configuration object. An iframe integration provides another embedding format for websites. These approaches change how the interface joins the host application; neither grants the app automatic authority to sign wallet transactions. The Playground provides a visual configuration environment with an export function for the chosen framework or iframe format. Validate the resulting embed in the browser and wallet environments the application intends to support.
API Access and Chain Filters
Widget requests require an API key and CORS access enabled for the application’s domain. A rendered swap card alone doesn’t establish a working API connection.
Production integrations need their own credentials; installation snippets contain testing credentials. Source and destination settings separate the allowed blockchain list from the initially selected blockchain and token. A preselection establishes a starting choice; an allowed list constrains available choices. Keep these settings consistent so the initial selection belongs to the intended trading scope. Narrow filters can also remove paths the broader service would otherwise offer.
Blockchain availability can change independently of an app’s configuration. The API’s blockchain metadata includes an enabled flag indicating whether a network is available through the service. Use that status alongside identifiers returned by the API when defining supported options. An old saved configuration doesn’t establish continued network availability.
Liquidity source filtering controls which exchanges and bridges routing may use. The exclusion setting reverses the supplied list’s meaning, so review it before deployment. These controls affect available routes and their costs. They don’t supply a fixed fee schedule or guarantee a quote for every allowed combination. An unavailable quote warrants examining restrictions before broadening the app’s trading options.
Themes and Route Display
Theme settings cover automatic, light and dark modes, with customizable colors and rounded corners. Layout variants range from the standard view to expanded route displays. Choose how much route information should appear up front. Keep amounts and transaction messages readable within the available space. Visual previews let developers assess those choices without authorizing a swap.
Existing Wallets and Signing Support
Wallet integration connects the embedded interface to accounts able to authorize its transactions, either through supported built-in providers or a provider supplied by the host application. An existing app connection can therefore become part of the widget integration. Compatibility requires the provider’s supported transaction capabilities, beyond displaying an account address.
The wallet configuration can restrict the presented providers to those relevant to the host app. A custom
ProviderInterface
supplies connection behavior and exposes
getSigners
for transaction signing. Network switching and account changes need consistent handling across both interfaces. Otherwise, the app’s selected account and the widget’s usable signer may disagree. Treat provider support as a dependency of the enabled swap choices.
Some wallet environments have security restrictions that can prevent a Rango iframe integration from working correctly. The package integration offers an alternative when those restrictions affect the intended environment.
Connection permissions and transaction authorization have different effects. A connected wallet may expose selected accounts; a signing request concerns the transaction or approval presented to it. Keep the wallet prompt understandable within the embedded experience, including the network and requested action, without portraying a connection as a completed swap.
A Working Quote Before Transaction Signing
In this hypothetical integration, an app uses a dark theme and an iframe, with selected network filters, supported assets, an input amount and a wallet environment. The developer requests a quote before authorizing any transfer. API access must work and selected networks must be enabled for that request to succeed. The wallet must also connect in the chosen browser. If a route is also available for the selected assets and amount, the widget displays a quote for review alongside the intended connected account. Configuration changes remain reversible at this point.
If the wallet can’t connect because the frame restricts access, replace the iframe integration with the package integration and check that wallet environment again. If API access fails instead, correct that dependency before diagnosing routing or wallet execution.
If the developer uses the package-integration fallback, the app’s handler for quote updates can receive the estimate and display it for the selected assets. The developer confirms the intended wallet account is connected in the widget. The developer can now inspect the proposal, revise the settings or proceed toward transaction authorization. The output amount shown belongs to the quote and represents an estimate.
Route Notifications in the Host App
Widget events let a host application respond to quote changes and execution progress without treating every update as a completed trade. Quote updates describe selected inputs and estimated output. Route events distinguish started, failed and succeeded states. Step events describe individual operations within a route, including approval-related events. Use these distinctions when choosing notification text, since an approval notification doesn’t establish delivery of the selected asset.
Event subscriptions also need cleanup when their owning component unmounts, so old handlers don’t persist after navigation. Decide which progress stays in the widget and which notifications the surrounding app should present.
Common questions about Rango
Does the Rango Widget Support Affiliate Fees on Embedded Swaps?
The widget supports optional affiliate fees on eligible transactions through its affiliate configuration. The configured percentage applies to the input amount, with referral and payout settings identifying the recipient. Keep that integrator fee distinct from network and underlying swap costs, and don’t assume every route supports referral rewards.
Which Details Identify a Preselected Token in the Widget?
Use the asset’s blockchain identifier, symbol and address in the token configuration. Native assets use a null address. A symbol alone doesn’t distinguish tokens across networks, and a display name isn’t interchangeable with the blockchain identifier the API expects. Select the token identity alongside the intended source or destination network.
Why doesn’t Setting fontFamily Load the widget’s Chosen Font?
The fontFamily setting selects a font but doesn’t supply the font file. For the package integration, the host page must load the chosen font separately. An iframe uses its own document and doesn’t inherit the host page’s font declarations. A fallback font can alter line wrapping and control widths, so inspect the embedded layout with the intended font available.
Will Hiding Liquidity Source Information Exclude That Provider From Swaps?
Hiding liquidity source information changes its visibility in the interface. Routing inclusion and exclusion use separate liquidity source settings. Keep those controls distinct when configuring the embed, since hiding a provider’s label doesn’t establish a restriction on which providers the service may use.
Is React Router Required to Embed the Swap Widget?
React Router isn’t required because the widget has an integrated memory router. An app already using React Router can host the widget under a route permitting its nested paths. Choose the arrangement that fits the application’s navigation without adding a router solely to display the swap interface.
What Wallet Information Can an App Receive Through Widget Events?
Wallet connection events expose the wallet type and connected accounts, while disconnection events identify the wallet type. Those payloads help the host app reflect connection state. Treat account details as user data when deciding what to retain in logs; a connection event doesn’t prove a swap was authorized or completed.