> For the complete documentation index, see [llms.txt](/llms.txt).

# Getting started with the Web SDK

Naming

Embedded Wallets SDKs were previously known as Web3Auth Plug and Play SDKs. Package names and APIs remain Web3Auth (for example, `@web3auth/modal`).

## Overview[​](#overview "Direct link to Overview")

Embedded Wallets provide a seamless authentication experience for web applications with social logins, external wallets, and more. Our JavaScript SDK simplifies how you connect users to their preferred wallets and manage authentication state.

## Requirements[​](#requirements "Direct link to Requirements")

- This is a frontend SDK and must be used in a browser environment.
- Basic knowledge of JavaScript.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

- Set up your project on the [Embedded Wallets dashboard](https://developer.metamask.io/)

tip

See the [dashboard setup](/embedded-wallets/dashboard/) guide to learn more.

## Installation[​](#installation "Direct link to Installation")

Install the Web3Auth Modal SDK using npm or yarn:

- npm
- Yarn
- pnpm
- Bun

```
npm install --save @web3auth/modal

```

```
yarn add @web3auth/modal

```

```
pnpm add @web3auth/modal

```

```
bun add @web3auth/modal

```

### 1\. Configuration[​](#1-configuration "Direct link to 1. Configuration")

Create an instance of Embedded Wallets containing the basic required configuration. This configuration will contain your Embedded Wallets Client ID and network details from the [Embedded Wallets dashboard](https://developer.metamask.io/).

```
import { Web3Auth, WEB3AUTH_NETWORK } from '@web3auth/modal'

const web3auth = new Web3Auth({
  clientId: 'YOUR_WEB3AUTH_CLIENT_ID', // Pass your Web3Auth Client ID, ideally using an environment variable // Get your Client ID from MetaMask Developer Dashboard
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET, // or WEB3AUTH_NETWORK.SAPPHIRE_DEVNET
})

```

### 2\. Initialize Embedded Wallets[​](#2-initialize-embedded-wallets "Direct link to 2. Initialize Embedded Wallets")

Initialize the Web3Auth instance before using any authentication methods:

```
await web3auth.init()

```

## Advanced configuration[​](#advanced-configuration "Direct link to Advanced configuration")

The Web3Auth Modal SDK offers a rich set of advanced configuration options:

- **[Smart accounts](/embedded-wallets/sdk/js/advanced/smart-accounts/):** Configure account abstraction parameters.
- **[Custom authentication](/embedded-wallets/sdk/js/advanced/custom-authentication/):** Define authentication methods.
- **[Whitelabeling and UI customization](/embedded-wallets/sdk/js/advanced/whitelabel/):** Personalize the modal's appearance.
- **[Multi-Factor Authentication (MFA)](/embedded-wallets/sdk/js/advanced/mfa/):** Set up and manage MFA.
- **[Wallet Services](/embedded-wallets/sdk/js/advanced/wallet-services/):** Integrate additional Wallet Services.

tip

See the [advanced configuration](/embedded-wallets/sdk/js/advanced/) section to learn more about each configuration option.

- Basic Configuration
- Advanced Configuration

```
import { Web3Auth, WEB3AUTH_NETWORK } from '@web3auth/modal'

const web3auth = new Web3Auth({
  clientId: 'YOUR_WEB3AUTH_CLIENT_ID', // Pass your Web3Auth Client ID, ideally using an environment variable
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET, // or WEB3AUTH_NETWORK.SAPPHIRE_DEVNET
})

```

```
import { Web3Auth, WEB3AUTH_NETWORK, WALLET_CONNECTORS, MFA_LEVELS } from '@web3auth/modal'

const web3auth = new Web3Auth({
  clientId: 'YOUR_WEB3AUTH_CLIENT_ID', // Pass your Web3Auth Client ID, ideally using an environment variable
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  modalConfig: {
    connectors: {
      [WALLET_CONNECTORS.AUTH]: {
        label: 'auth',
        loginMethods: {
          google: {
            name: 'google login',
            // logoDark: "url to your custom logo which will shown in dark mode",
          },
          facebook: {
            name: 'facebook login',
            showOnModal: false, // hides the facebook option
          },
          email_passwordless: {
            name: 'email passwordless login',
            showOnModal: true,
            authConnectionId: 'w3a-email_passwordless-demo',
          },
          sms_passwordless: {
            name: 'sms passwordless login',
            showOnModal: true,
            authConnectionId: 'w3a-sms_passwordless-demo',
          },
        },
        showOnModal: true, // set to false to hide all social login methods
      },
    },
    hideWalletDiscovery: true, // set to true to hide external wallets discovery
  },
  mfaLevel: MFA_LEVELS.MANDATORY,
})

```

## Blockchain integration[​](#blockchain-integration "Direct link to Blockchain integration")

Web3Auth is blockchain agnostic, enabling integration with any blockchain network. Out of the box, Web3Auth offers robust support for both **Solana** and **Ethereum**, each with dedicated provider methods.

### Solana integration[​](#solana-integration "Direct link to Solana integration")

To interact with Solana networks, you can get the provider from Web3Auth and use it with Solana libraries:

```
await web3auth.connect()
// Use with a Solana library
const solanaWallet = new SolanaWallet(web3auth.provider)

```

### Ethereum integration[​](#ethereum-integration "Direct link to Ethereum integration")

For Ethereum integration, you can get the provider and use it with ethers or viem:

```
await web3auth.connect()
// Use with ethers.js
const ethProvider = new ethers.BrowserProvider(web3auth.provider)
// OR
// Use with viem
const walletClient = createWalletClient({
  chain: getViewChain(web3auth.provider),
  transport: custom(web3auth.provider),
})

```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Bundler issues: missing dependencies[​](#bundler-issues-missing-dependencies "Direct link to Bundler issues: missing dependencies")

You might encounter errors related to missing dependencies in the browser environment:

- `Buffer is not defined`
- `process is not defined`
- Other Node.js-specific modules missing errors

These Node.js dependencies need to be polyfilled in your application. See the detailed troubleshooting guides for popular bundlers:

- **[Vite Troubleshooting Guide](/embedded-wallets/troubleshooting/vite-issues/)**
- **[Svelte Troubleshooting Guide](/embedded-wallets/troubleshooting/svelte-issues/)**
- **[Nuxt Troubleshooting Guide](/embedded-wallets/troubleshooting/nuxt-issues/)**
- **[Webpack 5 Troubleshooting Guide](/embedded-wallets/troubleshooting/webpack-issues/)**

### JWT errors[​](#jwt-errors "Direct link to JWT errors")

When using custom authentication, you may encounter JWT errors:

- [**Invalid JWT verifiers ID field**](/embedded-wallets/troubleshooting/jwt-errors/#invalid-jwt-verifiers-id-field)
- [**Failed to verify JWS signature**](/embedded-wallets/troubleshooting/jwt-errors/#failed-to-verify-jws-signature)
- [**Duplicate token**](/embedded-wallets/troubleshooting/jwt-errors/#duplicate-token)
- [**Expired token**](/embedded-wallets/troubleshooting/jwt-errors/#expired-token)
- [**Mismatch JWT validation field**](/embedded-wallets/troubleshooting/jwt-errors/#mismatch-jwt-validation-field)