> For the complete documentation index, see [llms.txt](https://docs.swapper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapper.finance/widget-integration/configuration.md).

# Configuration Reference

Every option the widget accepts through the [iframe SDK](/widget-integration/iframe-sdk.md) (`SwapperConfig`). The four required fields are always needed; everything else is optional and noted per field.

## Required

| Field                  | Type     | Description                                                                                                 |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `integratorId`         | `string` | Your registered integrator id. Scopes the session and links your [webhook](/tracking-deposits/webhooks.md). |
| `dstChainId`           | `string` | Destination chain id (e.g. `"8453"`).                                                                       |
| `dstTokenAddr`         | `string` | Destination token address. Use `0x0000000000000000000000000000000000000000` for native.                     |
| `depositWalletAddress` | `string` | Wallet that receives the destination token.                                                                 |

```typescript
const config = {
  integratorId: "your-integrator-id",
  dstChainId: "8453",
  dstTokenAddr: "0x833…913",
  depositWalletAddress: "0x2A0…28A",
};
```

## Optional

### `styles`

Two-tier theming (`themeMode` + `componentStyles`). See [Styling & Theming](/widget-integration/styling.md) for the full property list.

```typescript
styles: {
  themeMode: "dark",
  componentStyles: { primaryColor: "#836FFF", backgroundColor: "#111111" },
}
```

### `supportedDepositOptions`

Restrict which funding methods appear on the home screen, as an array of keys. When omitted, the default set is shown (opt-in options excluded).

| Key                       | Method                                                 |
| ------------------------- | ------------------------------------------------------ |
| `"transferCrypto"`        | [Transfer crypto](/deposit-methods/transfer-crypto.md) |
| `"depositWithCash"`       | [Pay with card](/deposit-methods/fiat-onramp.md)       |
| `"walletDeposit"`         | [Wallet deposit](/deposit-methods/wallet-deposit.md)   |
| `"depositFromPolymarket"` | Opt-in source flow                                     |
| `"depositFromPerps"`      | Opt-in source flow                                     |

```typescript
supportedDepositOptions: ["transferCrypto", "depositWithCash"],
```

If only fiat-capable options apply to a destination, the widget narrows the list automatically.

### `actionLabel`

Wording mode across the UI: `"buy"` (default — "Buy with Fiat", "Buy with QR") or `"deposit"` ("Deposit with Fiat", …).

```typescript
actionLabel: "deposit",
```

### `minDepositUsd` / `maxDepositUsd`

Clamp deposit size in **USD**, validated against the USD value of a quote's destination (received) amount.

* `minDepositUsd` overrides the integrator-config minimum; in the transfer flow it's still floored by a gas-based estimate so fees are always covered.
* `maxDepositUsd` has no integrator-config equivalent.

```typescript
minDepositUsd: 5,
maxDepositUsd: 1000,
```

### `customContractCalls`

Extra on-chain actions to run after the swap (approve → stake → transfer, etc.). See [Custom Contract Calls](/widget-integration/custom-contract-calls.md).

### `wallet`

Hand the widget a signer / wallet handlers so a user who's already connected in your app doesn't reconnect. See [Connecting a Wallet](/widget-integration/connecting-a-wallet.md).

### `onEvent`

A wildcard event handler called for every [widget event](/tracking-deposits/widget-events.md) — shorthand for `on("*", …)`.

```typescript
onEvent: (event) => console.log(event.type, event.data),
```

## Iframe-SDK-only options

Passed to `SwapperIframe` / `SwapperModal` / `SwapperEmbed` (not the direct widget):

| Option                 | Type                    | Description                                                                                      |
| ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
| `container`            | `HTMLElement \| string` | Where to mount (`SwapperIframe`).                                                                |
| `iframeUrl`            | `string`                | Override the widget host. Default `https://deposit.swapper.finance/`.                            |
| `iframeAttributes`     | `object`                | Extra iframe attributes (`width`, `height`, `sandbox`, …).                                       |
| `flexibleHeight`       | `boolean`               | Opt in to auto-sizing home page + [`resize`](/tracking-deposits/widget-events.md#resize) events. |
| `deferSmartWalletAuth` | `boolean`               | Load everything but defer smart-wallet auth until `notifyWidgetOpened()`.                        |

## Widget-only props

Set on the hosted widget internally by the iframe host — you don't pass these directly, but they're documented here for reference:

| Prop                   | Type      | Description                                                                                                                                 |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `closable`             | `boolean` | Show a close affordance inside the widget.                                                                                                  |
| `webviewMode`          | `boolean` | Render the fiat on-ramp step as a plain user-clickable link (no `window.open`) so iOS/Android WebViews can hand off to the system browser.  |
| `flexibleHeight`       | `boolean` | Auto-scale the home page; the host is expected to honor `resize` events.                                                                    |
| `deferSmartWalletAuth` | `boolean` | Hold off creating the smart-wallet authorization until signaled visible.                                                                    |
| `integrationError`     | `string`  | Pre-set error — the widget skips its chain fetch and renders an error view (used by iframe hosts to surface URL-param validation failures). |

## Updating config at runtime

All of the above (except transport-level iframe options) can be patched live — the iframe never reloads:

```typescript
swapper.updateConfig({ dstChainId: "1", depositWalletAddress: "0x…" });
swapper.updateStyles({ themeMode: "light" });
swapper.updateCustomContractCalls([ /* … */ ]);
```