For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

External wallet aggregator

The MetaMask Embedded Wallets Web SDK provides a wallet aggregator that unifies EVM and Solana wallet discovery, connection, and session management into a single layer you can integrate into any web app.

demo

Looking for a quick preview? See the Demo.

Highlights​

  • Cross-ecosystem: EVM and Solana in a single flow.
  • Standards-native: EIP-6963 (EVM) and Solana Wallet Standard.
  • Works with your stack: ethers, viem, Wagmi, @solana/kit.
  • First-class developer experience: Hooks and composables for React/Vue.
  • Central control: Manage everything in the Embedded Wallets dashboard.
Wallet Discovery

A familiar, unified wallet selection experience for users.

Connect and sign (Web SDK v11 default)​

Web SDK v11 overhauls the external wallet connection flow for @web3auth/modal (JavaScript, React, and Vue). External wallet sign-in now defaults to connect and sign, a Sign-In with Ethereum (SIWE) style flow that authenticates the wallet in one step instead of requiring a separate connect followed by a signature prompt.

Default authentication mode​

The SDK sets initialAuthenticationMode to connect-and-sign by default. To override it, pass initialAuthenticationMode in Web3AuthOptions:

import {
  CONNECTOR_INITIAL_AUTHENTICATION_MODE,
  WEB3AUTH_NETWORK,
  type Web3AuthOptions,
} from '@web3auth/modal'

const web3AuthOptions: Web3AuthOptions = {
  clientId: 'YOUR_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  initialAuthenticationMode: CONNECTOR_INITIAL_AUTHENTICATION_MODE.CONNECT_AND_SIGN,
}

Session persistence across reloads​

After a successful connect-and-sign flow, the SDK stores auth tokens (idToken, accessToken, refreshToken) and restores the session on page reload. Users are not re-prompted for a signature after a refresh while the session is still valid.

See Session management for how session keys and token storage work.

Benefits for dapps​

  • Fewer drop-offs at authentication because sign-in is one tap instead of two.
  • Less custom session-handling code in your integration.
  • SIWE-style nonces are generated via viem for external wallet connectors.

MetaMask connector (MetaMask Connect)​

The MetaMask connector in Web SDK v11 uses the MetaMask Connect SDK instead of the legacy integration path. This improves mobile MetaMask connections from web browsers, including:

  • iOS Safari deep linking between the browser and the MetaMask app.
  • Session handoff so users return to your dapp after approving a connection in the MetaMask mobile app.

MetaMask Wallet remains enabled by default in the dashboard and cannot be disabled.

Multi-wallet linking​

Users who sign in with an embedded wallet method can link additional external wallets and switch between them mid-session in the Web SDK. See Multi-wallet linking and switching for linkAccount(), switchAccount(), and the linkedAccounts user object.

Customize flow within the dashboard​

  • Wallet aggregator only: Drop‑in discovery, connection, and session state.
  • With social logins: Offer socials and external wallets side‑by‑side in one flow.
Dashboard Wallet Toggle

Toggle social logins and external wallets visibility.

Dashboard Wallet Selector

Toggle and manage supported wallets.

Next steps​

On this page