Connecting a Wallet

By default the widget manages wallet connection itself (it bundles a full wallet UI). But if your app already has the user's wallet connected, you can hand the widget a signer so the user doesn't connect twice. This applies to the iframe SDK via the wallet config option.

Why

For the transfer-crypto flow the widget needs to request transactions and chain switches. Passing your existing connection means:

• no second "Connect Wallet" step for the user;

• transactions are signed by the wallet your app already trusts;

• the widget reflects the account/chain your app is on.

Option A — pass a signer

The simplest form: give the widget a signer object. The widget auto-connects with it as soon as it loads — no second "Connect Wallet" step, and no flag to set (the SDK reads the address and chain from the signer for you).

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

const swapper = new SwapperIframe({
  integratorId: "your-id",
  dstChainId: "8453",
  dstTokenAddr: "0x833…913",
  depositWalletAddress: "0x2A0…28A",
  wallet: { signer }, // an ethers/viem-compatible signer — auto-connected on load
});

The SDK ships adapters that normalize common wallet SDKs into a SwapperSigner — an object exposing getAddress(), getChainId(), sendTransaction(), and switchChain().

Option B — provide handlers

If you'd rather keep signing entirely in your app, provide callbacks. The widget calls them when it needs a transaction sent or a chain switched, and you return the result:

const swapper = new SwapperIframe({
  // ...required config
  wallet: {
    onTransactionRequest: async (tx) => {
      // tx: { to, data?, value?, gasLimit? }
      const hash = await myWallet.sendTransaction(tx);
      return { hash };
    },
    onChainSwitchRequest: async (chainId) => {
      await myWallet.switchChain(chainId);
    },
    autoConnect: { address: "0x…", chainId: 8453, walletName: "metamask" },
  },
});

In handler mode, auto-connect needs the connection details (address / chainId) — there's no signer for the SDK to read them from. Provide autoConnect to land the user in the connected state on load; omit it to let them connect inside the widget.

Updating the signer later

If the user switches accounts in your app, push the new signer to the widget:

swapper.updateSigner(newSigner); // also available directly on SwapperModal

(SwapperModal.updateSigner() is safe to call before the modal is built — handy with preloading.)

Under the hood: the wallet message protocol

The connection is bridged across the iframe boundary by SwapperWalletProvider using a small postMessage protocol (SWAPPER_WALLET_* messages):

Message	Direction	Meaning
SWAPPER_WALLET_READY	widget → host	Widget is ready to receive a connection.
SWAPPER_WALLET_CONNECT	host → widget	Report connected address / chainId.
SWAPPER_WALLET_DISCONNECT	host → widget	Wallet disconnected.
SWAPPER_WALLET_CHAIN_CHANGED	host → widget	Active chain changed.
SWAPPER_TX_REQUEST / SWAPPER_TX_RESPONSE	widget ↔ host	Request a tx be signed; return the hash (or error).
SWAPPER_CHAIN_SWITCH_REQUEST / …_RESPONSE	widget ↔ host	Request a chain switch.

You don't normally touch these directly — the wallet config and the adapters handle it. They're documented here so you can debug message flow if needed.

Recognized wallet names (for autoConnect.walletName) include metamask, rabby, coinbase, phantom, trust, okx, rainbow, walletconnect, ledger, safe, and others. The name is a hint for display; the signer / handlers do the real work.