Rubicexchange

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 on

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

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.

Separate host charges from network, protocol, and provider costs (Rubicexchange swap widget) - illustration

View image file


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.

Visual outline: Client-side initialization (Rubicexchange swap widget)

View image file

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.