Rubicexchange swap widget embeds token exchange with configurable source and destination selections
Rubicexchange swap widget brings Rubic’s token exchange interface into a host website with configurable source and destination assets. Each selection combines a token with its blockchain, so the starting pair determines the exchange direction. Visitors can change those choices when the host enables selection. Presets define the initial form; available providers determine whether that pair produces a usable quote.
Updated onThe host also sets an initial amount, selection restrictions, and display preferences. These controls explain why embedded forms can behave differently across websites. Understanding the selected token and network comes before interpreting an output estimate or approving a wallet request.
Restore the intended pair before requesting another quote
A usable quote estimates the receiving amount for the token pair and networks currently selected. If that amount disappears or changes after a destination change, the earlier quote no longer describes the same request. Leave the source amount unchanged while checking the destination selection; this keeps the comparison tied to the changed input.
Where destination selection is enabled, restoring the preceding destination lets you request a quote without sending funds.
- If the destination changed, confirm both its token and blockchain describe the asset you intend to receive.
- If selection is locked, use the configured pair or ask the host to change its settings.
- If the source amount also changed, restore it before isolating the destination change.
- If the restored pair returns a quote, evaluate the revised destination as a separate exchange.
- If no usable quote appears, stop before approval or submission; presets don’t establish a working route.
Changing the destination can also change the available provider, even when the starting quantity stays fixed.
Choosing another receiving network can still change provider availability, expected output, and costs. Each quote prices the complete selection at the time requested, so a conclusion about the earlier pair applies only while its inputs and quoted conditions remain unchanged.
What identifies the tokens in an embedded swap?
A token selection combines a token symbol or address with its blockchain, defining the source and destination separately. The
from
and
to
settings choose tokens. The
fromChain
and
toChain
settings choose their networks. A matching symbol across networks doesn’t make those assets interchangeable.
Source token and starting amount
from
identifies the asset being exchanged, while
amount
supplies the initial trade quantity. That preset quantity helps populate the form when the widget opens. It isn’t a destination estimate.
Receiving token and blockchain
to
identifies the receiving asset, and
toChain
determines its destination network. Read them together when judging what the exchange would deliver. A token contract address identifies the asset, whereas a wallet address identifies the recipient. The
to
field selects the token; it isn’t a field for the receiving wallet.
Same-chain and cross-chain selections change the required operation
Choosing the same source and destination blockchain calls for an on-chain exchange within that network. Choosing different blockchains calls for cross-chain functionality. The widget supports both forms, so a visible token pair doesn’t by itself explain the movement involved. A decentralized exchange (DEX) handles token exchange through blockchain transactions. Cross-chain routing adds a means of moving value between networks. Those operations may fit into an aggregated route, depending on the selected assets and available providers.
Can a website restrict which tokens visitors exchange?
A host can restrict changes to the source token, destination token, or both through the widget’s configuration. The
hideSelectionFrom
and
hideSelectionTo
controls govern those restrictions.
Each enabled selection restriction limits that side of the swap to its configured token.
One side can remain editable while the other is fixed. This supports an embedded form centered on a chosen receiving token without removing the permitted source choice.
Setting a starting token supplies a default selection; restricting selection controls whether a visitor can change it. Quotes for a fixed receiving token still depend on the source amount, selected networks, and available providers. Choosing a fixed target therefore constrains what the form can receive without fixing its exchange rate.
Custom token entries need chain-specific identifiers and available liquidity
The
injectTokens
setting adds host-specified tokens to the widget’s selection list. Entries are grouped by blockchain and accept token symbols or addresses. Supplied Ethereum token addresses must use checksum format. A checksum uses capitalization to help detect address errors. Token names and symbols describe an asset; the contract address supplies its precise identity within the network. Checksum capitalization shouldn’t be changed as a cosmetic edit.
Adding a selectable token doesn’t supply liquidity; providers must still support the requested exchange.
Does the configured amount fix how many tokens arrive?
The configured amount sets the starting trade quantity; a quote estimates the receiving quantity for the selected destination token. Read the quantities with their respective token identities. The source asset and amount describe what enters the exchange, while the destination asset and network define what the provider prices for receipt.
Expected output describes the provider’s calculation at the quote stage. Where a minimum output after slippage is shown, it identifies the route’s quoted minimum receiving amount. Read each amount with its destination token and units. A dollar estimate serves a different purpose from a token quantity. Market movement, liquidity updates, and provider recalculation can change a quote before execution data is prepared. These changes affect quoted output even when the source quantity remains unchanged.
Slippage defaults follow the exchange type
The widget’s
slippagePercent
configuration has separate entries for
instantTrades
and
crossChain
. These entries let the host set different defaults for on-chain exchange and cross-chain movement. Slippage tolerance bounds accepted execution-price movement under the selected route’s rules.
The quote’s minimum receiving amount, where shown, reflects slippage in destination-token units. A slippage percentage and a displayed receiving quantity have different units.
Approval, submission, and delivery describe different states
An allowance-based token swap can require authorization before execution, while destination delivery remains a separate transaction outcome. The action being approved determines what a wallet confirmation means. Read the requested operation before approving it.
Token allowance
For ERC-20 tokens, an allowance is the amount a contract has permission to spend. An approval transaction can change that permission when the selected route requires it. Approval data identifies the spending contract being authorized. The permission applies to the selected ERC-20 token and authorized spender.
Swap submission
Submission follows the selected provider’s execution instructions, which can involve a swap transaction or a deposit transfer. Some deposit-based providers may require know your customer (KYC) identity verification when their risk systems flag a transaction. A returned trade identifier supports tracking of the exchange. An identifier can exist before funds are sent, so it doesn’t confirm submission or destination delivery.
Receiving tokens
Cross-chain completion concerns the destination side of the exchange. Rubic’s transaction status data can identify successful completion and provide a destination transaction hash. Even a confirmed source-chain transaction doesn’t establish destination delivery.
Separate host charges from network, protocol, and provider costs
The website can configure fee collection for swaps performed through its widget. Rubic’s integrator fee sharing requires the host’s designated wallet to be whitelisted. That host-side setting belongs alongside the costs of the selected exchange route. Network gas pays for blockchain execution, and a provider can add charges associated with its service. Those costs aren’t all controlled by the field specifying the host’s fee. A form with no configured host charge may still incur network, provider, or Rubic protocol fees.
The fee recipient identifies where a host charge goes. The swap recipient identifies where the exchanged assets arrive. The widget’s integrator address settings configure fee collection; they don’t select the destination token or confirm delivery.
Container width and visibility settings shape the form
The widget’s flex layout responds to the width of its containing element.
With
iframe
set to
flex
, the widget turns vertical below a container width of 1,180 pixels and horizontal at or above that width.
This measures the widget container, so a narrow column can use the vertical layout even on a wide screen. The
useLargeIframe
option selects the larger desktop size when enabled and the mobile size when disabled.
Other display settings address appearance and unused controls. A host can choose a theme, background, and language, and
hideUnusedUi
hides unused interface elements. Token selection restrictions govern available edits separately, so a visual change doesn’t establish permission to choose a different asset or blockchain.
Initialize the embedded form in the browser
The widget needs a dedicated container and initialization code running in the browser. The page supplies a loader, the
rubic-widget-root
container, and a configuration object passed to
rubicWidget.init
. Each part has a different job: the loader supplies widget functionality, the container provides its location, and initialization applies the configuration. A configuration object on its own doesn’t render an exchange interface.
Preserving the starting configuration
Keeping a base configuration separate from display updates helps preserve the intended token and network selections.
Object.freeze
prevents accidental changes to that object’s top-level properties. A revised copy can retain the pair and amount while supplying updated display settings.
hideSelectionFrom
and
hideSelectionTo
control whether visitors can change the tokens in the form.
Client-side initialization
Server-side rendering can generate the surrounding website without running the widget’s browser initialization. The initialization must execute on the client side in that setup. Successful initialization makes the configured interface available; a usable quote still requires the selected tokens, networks, and providers to support that exchange.
Frequently asked questions about Rubicexchange swap widget
-
Can the embedded widget follow a change from a light theme to a dark theme?
- The host can change the widget’s theme by calling rubicWidget.init again with an updated configuration. Reinitialization deletes the previous widget and creates a replacement.
-
Where do the loader, container, and initialization code belong in a widget integration?
- The integration places the loader in the page head, the widget container at the intended display location, and initialization code near the bottom of the body. The container uses rubic-widget-root as its identifier. Initialization supplies the configuration after the required page components are available.
-
Why doesn’t hideBranding apply when useLargeIframe is false?
- The hideBranding option works only when useLargeIframe is true. With useLargeIframe set to false, the widget uses the mobile size, so that configuration doesn’t meet the branding control’s layout condition.
-
Which interface languages does the widget support?
- The widget language options include English, Spanish, Korean, Russian, and Chinese. The corresponding language values are en, es, ko, ru, and zh. The host selects the widget’s interface language through its configuration.
-
How do provider inclusion and exclusion lists affect an embedded quote?
- Provider inclusion lists limit the selected provider set, while exclusion lists remove specified providers from consideration. The widget configuration distinguishes on-chain and cross-chain provider lists. Restricting those candidates changes what the embedded form can consider for an exchange, without guaranteeing a route for every configured token pair.
-
Must on-chain and cross-chain widget fees use the same integrator address?
- On-chain and cross-chain widget swaps can use separate whitelisted integrator addresses. The onChainIntegratorAddress and crossChainIntegratorAddress settings specify them independently. Each address belongs to fee collection for its respective exchange type. The token-selection settings define the exchanged assets separately.