> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerswap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Initial values & flows

> Prefill, lock, or hide Widget fields and select the Swap, CEX, or Deposit flow.

Pass these optional fields through [`config.initialValues`](/widget/configuration) to control what the form starts with and what users can change:

```tsx theme={null}
<LayerswapWidget
  config={{
    apiKey: 'YOUR_API_KEY',
    version: 'mainnet',
    initialValues: {
      to: 'BASE_MAINNET',
      toAsset: 'USDC',
      lockTo: true,
      destination_address: '0x1234…5678',
    },
  }}
/>
```

Hosted Page URL parameters use many of the same names, plus legacy aliases and named theme presets. Their canonical reference is [Hosted Page setup](/hosted-page/setup).

## Routing

<ResponseField name="from" type="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](/get-started/networks-and-tokens).
</ResponseField>

<ResponseField name="to" type="string">
  Destination network or exchange the user transfers to — e.g. `BASE_MAINNET`.
</ResponseField>

<ResponseField name="fromAsset" type="string">
  Token preselected in the "From" field. Available tokens depend on the selected source network.
</ResponseField>

<ResponseField name="toAsset" type="string">
  Token preselected in the "To" field. Available tokens depend on the selected destination network.
</ResponseField>

<ResponseField name="amount" type="string">
  Pre-fills the amount field. The user can still change it. Skipped if no asset is selected.
</ResponseField>

<ResponseField name="destination_address" type="string">
  The destination address the funds should reach at the end of the swap.
</ResponseField>

## Locking fields

<ResponseField name="lockFrom" type="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.
</ResponseField>

<ResponseField name="lockTo" type="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.
</ResponseField>

<ResponseField name="lockFromAsset" type="boolean">
  Lock the source token to the value set in `fromAsset`. Requires both `from` and `fromAsset`; also enable `lockFrom` to restrict the token picker.
</ResponseField>

<ResponseField name="lockToAsset" type="boolean">
  Lock the destination token to the value set in `toAsset`. Requires both `to` and `toAsset`; also enable `lockTo` to restrict the token picker.
</ResponseField>

## Hiding UI elements

<ResponseField name="hideFrom" type="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.
</ResponseField>

<ResponseField name="hideTo" type="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.
</ResponseField>

<ResponseField name="hideRefuel" type="boolean">
  Disable the refuel feature and hide it in the UI.
</ResponseField>

<ResponseField name="hideLogo" type="boolean">
  Hide the Layerswap logo in the widget header. Only takes effect in the wide layout.
</ResponseField>

## Flow selection

<ResponseField name="defaultTab" type="&#x22;swap&#x22; | &#x22;cex&#x22; | &#x22;deposit&#x22;">
  The initial flow shown by the widget:

  * `swap` — cross-chain swap flow (default)
  * `cex` — deposit from CEX flow
  * `deposit` — Deposit tab
</ResponseField>

<ResponseField name="depositMethod" type="&#x22;wallet&#x22; | &#x22;deposit_address&#x22;">
  Preselect wallet funding or deposit-address funding. Other values are ignored by the standard Widget.
</ResponseField>

<ResponseField name="swapId" type="string">
  Open the widget directly on an existing swap.
</ResponseField>

## Attribution & display

<ResponseField name="externalId" type="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.
</ResponseField>

<ResponseField name="account" type="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.
</ResponseField>

<ResponseField name="appName" type="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`.
</ResponseField>

<ResponseField name="sameAccountNetwork" type="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.
</ResponseField>

<ResponseField name="actionButtonText" type="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.
</ResponseField>

## 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`](/widget/deposit-widget) 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](/hosted-page/setup).