Skip to main content
Pass these optional fields through config.initialValues to control what the form starts with and what users can change:
Hosted Page URL parameters use many of the same names, plus legacy aliases and named theme presets. Their canonical reference is Hosted Page setup.

​
Routing

​
string
Source network or exchange the user transfers from — for example, ETHEREUM_MAINNET, IMMUTABLEX_MAINNET, or an exchange identifier. Network and token names are listed on Supported networks & tokens.
​
string
Destination network or exchange the user transfers to — e.g. BASE_MAINNET.
​
string
Token preselected in the “From” field. Available tokens depend on the selected source network.
​
string
Token preselected in the “To” field. Available tokens depend on the selected destination network.
​
string
Pre-fills the amount field. The user can still change it. Skipped if no asset is selected.
​
string
The destination address the funds should reach at the end of the swap.

​
Locking fields

​
boolean
Lock the source network to the value set in from. Only takes effect when from is also set; the picker remains clickable but offers no other networks.
​
boolean
Lock the destination network to the value set in to. Only takes effect when to is also set; the picker remains clickable but offers no other networks.
​
boolean
Lock the source token to the value set in fromAsset. Requires both from and fromAsset; also enable lockFrom to restrict the token picker.
​
boolean
Lock the destination token to the value set in toAsset. Requires both to and toAsset; also enable lockTo to restrict the token picker.

​
Hiding UI elements

​
boolean
Hide the source network picker. Only takes effect when from is also set. When partner branding is configured, it also replaces the source network with your app’s name and logo in swap summaries and history.
​
boolean
Hide the destination network picker. Only takes effect when to is also set. When partner branding is configured, it also replaces the destination network with your app’s name and logo in swap summaries and history.
​
boolean
Disable the refuel feature and hide it in the UI.
Hide the Layerswap logo in the widget header. Only takes effect in the wide layout.

​
Flow selection

​
"swap" | "cex" | "deposit"
The initial flow shown by the widget:
  • swap — cross-chain swap flow (default)
  • cex — deposit from CEX flow
  • deposit — Deposit tab
​
"wallet" | "deposit_address"
Preselect wallet funding or deposit-address funding. Other values are ignored by the standard Widget.
​
string
Open the widget directly on an existing swap.

​
Attribution & display

​
string
An ID from your system identifying the user’s swap session. It is sent as the swap’s reference_id on creation and returned on swap objects as metadata.reference_id, so you can correlate swaps across API responses and webhooks. Uniqueness is your responsibility — the widget does not enforce it.
​
string
User account name or address shown as the swap’s source address. Only takes effect together with hideFrom: true. When appName resolves to a valid partner, the source network is additionally replaced by your app’s name and logo in the swap summary.
​
string
Your partner identifier from your partner setup (the client_id value). Used for address attribution: when destination_address is provided, an Autofilled by {your app name} label — and, if your partner profile is registered as a wallet, your logo — is shown next to the address. The value must exactly match your client_id; otherwise attribution is silently disabled. Also required for source branding when using account with hideFrom: true.
​
string
Set this to the name of a network that requires same-account transfers. If the specified network is selected as the source or destination, the connected source address must match the destination address; otherwise, the widget blocks the swap. The widget also disables manual transfers (deposit_address) for that route.
​
string
default:"Next"
Replaces the text of the main swap-form action button — e.g. “Deposit”, “Withdraw”, “Transfer”. Applies to the form’s submit button only; buttons on later steps (e.g. “Swap now” during withdrawal) are not affected.

​
Flow behavior

​
Swap

The default swap flow moves assets between blockchain networks. You can prefill or lock both sides and provide destination_address.

​
Deposit from CEX

The cex flow lets a user withdraw from a centralized exchange into a destination wallet. The user selects an exchange and intermediary network, follows the withdrawal instructions, and Layerswap continues after detecting the deposit. Prefill the exchange with from and the destination with to, toAsset, and destination_address.

​
Deposit tab

The deposit flow gives the user a generated address or QR code they can fund from a wallet, hardware wallet, or exchange without a source-side wallet connection. In this flow, the connected destination wallet takes precedence: its address overwrites destination_address. Use LayerswapDepositWidget when your application must lock the destination address. To keep users in one flow, combine defaultTab with config.theme.header.hideTabs: true.

​
Older aliases

Older URL and Widget parameter names are still normalized, but new integrations should use only the canonical fields above. The complete alias and precedence table lives in Hosted Page setup.