Iframe SDK

@swapper-finance/deposit-sdk is the recommended way to integrate Swapper. It embeds the hosted widget (https://deposit.swapper.finance) in a sandboxed iframe and exposes a small, typed API to configure it, listen for events, and update it live.

• Written in TypeScript, typed API.

• Works in any framework or none, including mobile WebViews.

• postMessage communication with origin validation.

npm install @swapper-finance/deposit-sdk

SwapperIframe

The core class. It builds an iframe, validates your config, and mounts it into a container.

import { SwapperIframe } from "@swapper-finance/deposit-sdk";

const swapper = new SwapperIframe({
  container: "#swapper-container", // CSS selector or HTMLElement
  integratorId: "your-integrator-id",
  dstChainId: "8453",
  dstTokenAddr: "0x833…913",
  depositWalletAddress: "0x2A0…28A",
});

If you omit container, mount later:

const swapper = new SwapperIframe({ /* config, no container */ });
swapper.mount("#swapper-container");

The four required parameters (integratorId, dstChainId, dstTokenAddr, depositWalletAddress) are validated on construction. Everything else is optional — see the Configuration Reference.

Methods

Method	Description
mount(container)	Mount the iframe into an HTMLElement or CSS selector.
updateConfig(partial)	Patch any config field live via postMessage (no reload).
updateStyles(styles)	Update only the styling.
updateCustomContractCalls(calls)	Replace the custom calls.
getConfig()	Return the current config object.
on(name, handler) / off(name, handler)	Subscribe / unsubscribe to events. Use "*" for all.
notifyWidgetOpened()	Signal the widget it's now visible (see deferred auth).
destroy()	Remove the iframe and clean up listeners.

Updating configuration live

Config changes are sent to the widget over postMessage — the iframe never reloads:

swapper.updateConfig({
  depositWalletAddress: "0xNewAddress...",
  dstChainId: "1",
});

This is how you react to your own app's state — e.g. the user switched the account they're funding.

Listening for events

Pass an onEvent callback (equivalent to on("*", …)), or register handlers on the instance. Full details in Widget Events.

import { SwapperIframe, WidgetEventName } from "@swapper-finance/deposit-sdk";
import type { TransactionSuccessPayload } from "@swapper-finance/deposit-sdk";

const swapper = new SwapperIframe({ /* ...config */ });

swapper.on(WidgetEventName.TRANSACTION_SUCCESS, (event) => {
  const payload = event.data as TransactionSuccessPayload;
  console.log("Deposit complete:", payload.txHash, payload.depositOption);
});

Preloading and deferred authorization

To make the first open instant, build the iframe hidden and let it load in the background. Set deferSmartWalletAuth so authorization waits until the widget is actually revealed, then signal it with notifyWidgetOpened():

const iframe = new SwapperIframe({
  // ...config
  deferSmartWalletAuth: true,
});

// when your UI actually reveals the widget:
iframe.notifyWidgetOpened();

SwapperModal and SwapperEmbed handle this pattern for you — see Modal & Inline Embed.

Iframe options

Beyond the shared config, SwapperIframe accepts a few embed-only options:

Option	Description
container	HTMLElement or selector to mount into.
iframeUrl	Override the widget host. Default: https://deposit.swapper.finance/.
iframeAttributes	Extra iframe attributes: width, height, minWidth, borderRadius, title, allow, sandbox, …
flexibleHeight	Opt in to the widget's auto-sizing home page; the SDK animates the iframe to the requested height and the widget emits resize events.
deferSmartWalletAuth	Load everything but hold off creating a smart-wallet authorization until notifyWidgetOpened().

Connecting a wallet

If your app already has the user's wallet connected, you can hand the widget a signer so the user doesn't reconnect. See Connecting a Wallet.

Cleaning up

Always destroy() when your component unmounts to remove the iframe and detach the message listeners:

swapper.destroy();

Next

• Popup or in-place reveal → Modal & Inline Embed

• Every config field → Configuration Reference

• Theme it → Styling & Theming