Configuration Reference

Every option the widget accepts through the iframe SDK (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.
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.

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

Optional

styles

Two-tier theming (themeMode + componentStyles). See Styling & Theming for the full property list.

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
"depositWithCash"	Pay with card
"walletDeposit"	Wallet deposit
"depositFromPolymarket"	Opt-in source flow
"depositFromPerps"	Opt-in source flow

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", …).

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.

minDepositUsd: 5,
maxDepositUsd: 1000,

customContractCalls

Extra on-chain actions to run after the swap (approve → stake → transfer, etc.). See Custom Contract Calls.

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.

onEvent

A wildcard event handler called for every widget event — shorthand for on("*", …).

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 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:

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