> 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/iframe-sdk.md).

# Iframe SDK

[`@swapper-finance/deposit-sdk`](https://www.npmjs.com/package/@swapper-finance/deposit-sdk) is the recommended way to integrate Swapper. It embeds the hosted widget ([`https://deposit.swapper.finance`](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.

```bash
npm install @swapper-finance/deposit-sdk
```

## `SwapperIframe`

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

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

```typescript
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](/widget-integration/configuration.md).

## 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](/widget-integration/styling.md).                                        |
| `updateCustomContractCalls(calls)`         | Replace the [custom calls](/widget-integration/custom-contract-calls.md).                         |
| `getConfig()`                              | Return the current config object.                                                                 |
| `on(name, handler)` / `off(name, handler)` | Subscribe / unsubscribe to [events](/tracking-deposits/widget-events.md). Use `"*"` for all.      |
| `notifyWidgetOpened()`                     | Signal the widget it's now visible (see [deferred auth](#preloading-and-deferred-authorization)). |
| `destroy()`                                | Remove the iframe and clean up listeners.                                                         |

### Updating configuration live

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

```typescript
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](/tracking-deposits/widget-events.md).

```typescript
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()`:

```typescript
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](/widget-integration/modal-and-embed.md).

## 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`](/tracking-deposits/widget-events.md#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](/widget-integration/connecting-a-wallet.md).

## Cleaning up

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

```typescript
swapper.destroy();
```

## Next

* Popup or in-place reveal → [Modal & Inline Embed](/widget-integration/modal-and-embed.md)
* Every config field → [Configuration Reference](/widget-integration/configuration.md)
* Theme it → [Styling & Theming](/widget-integration/styling.md)