> 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/connecting-a-wallet.md).

# 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](/widget-integration/iframe-sdk.md) via the `wallet` config option.

## Why

For the [transfer-crypto](/deposit-methods/transfer-crypto.md) 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).

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

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

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

(`SwapperModal.updateSigner()` is safe to call before the modal is built — handy with [preloading](/widget-integration/modal-and-embed.md#preloading-the-modal).)

## 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.

{% hint style="info" %}
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.
{% endhint %}