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 wallet-deposit flow the widget needs to request transactions and chain switches. (The QR flow needs no wallet connection.) 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:
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:
(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):
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.
Last updated