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

# Embedded Wallets SDK for Node.js

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

The MetaMask Embedded Wallets Node.js SDK (formerly Web3Auth Plug and Play) is a backend solution designed for server-side authentication and key management. This SDK integrates web3 authentication into backend applications, AI agents, and programmatic use cases.

Unlike frontend SDKs, the Node.js SDK is **stateless and sessionless**, making it ideal for:

- Backend AI agents
- Server-side wallet operations
- Programmatic blockchain interactions
- Custodial wallet services, without key management and recovery worries.

## Key features[​](#key-features "Direct link to Key features")

- **Stateless architecture:** No session management required
- **Multi-chain support:** Support for EVM chains, Solana, and other blockchains
- **Custom authentication:** Mandatory custom auth with single key share
- **Private key access:** Direct access to private keys for any blockchain
- **Backend-optimized:** Designed specifically for server environments

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

- Node.js 22+
- npm 10+
- Custom authentication setup (mandatory)
- Embedded Wallets dashboard project configuration

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

- Registered on the [Embedded Wallets dashboard](https://developer.metamask.io/)
- Set up a custom **Auth connection** (mandatory for Node.js SDK)

tip

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

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

Install the Web3Auth Node SDK

- npm
- Yarn
- pnpm
- Bun

```
npm install --save @web3auth/node-sdk

```

```
yarn add @web3auth/node-sdk

```

```
pnpm add @web3auth/node-sdk

```

```
bun add @web3auth/node-sdk

```

### 1. Custom authentication setup (required)[​](#1-custom-authentication-setup-required "Direct link to 1. Custom authentication setup (required)")

The Node.js SDK **only supports custom authentication**. You must create a custom auth connection:

1. Go to the [Embedded Wallets dashboard](https://developer.metamask.io/).
2. Select your project.
3. Navigate to **Authentication** → **Custom connections**.
4. Click **Create connections**.
5. Configure your auth connection with your custom JWT details.

info

You can refer to the [Custom JWT Setup](/embedded-wallets/authentication/custom-connections/custom-jwt/) guide to learn more.

### 2. SDK configuration[​](#2-sdk-configuration "Direct link to 2. SDK configuration")

Create a Web3Auth instance with your client ID, web3auth network name, and chain information:

```
const { Web3Auth } = require('@web3auth/node-sdk')

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: 'sapphire_mainnet', // or 'sapphire_devnet'
})

```

note

Chain configuration comes from your [Embedded Wallets dashboard](https://developer.metamask.io/) project. You can optionally pass a `chains` array in the constructor to add or override dashboard chains. Use `defaultChainId` to select which chain is active after `connect()`. If no chains are configured in the dashboard or constructor, `init()` throws an error.

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

Initialize the Web3Auth instance during your application startup:

```
await web3auth.init()

```

### 4. Authenticate users[​](#4-authenticate-users "Direct link to 4. Authenticate users")

Use the connect method with your custom authentication parameters:

```
const result = await web3auth.connect({
  authConnectionId: 'YOUR_AUTH_CONNECTION_ID', // Your custom authentication connection name
  idToken: 'USER_ID_TOKEN', // JWT token from your auth system
})

```

## Configuration options[​](#configuration-options "Direct link to Configuration options")

- Basic Configuration
- Advanced Configuration

```
const { Web3Auth } = require('@web3auth/node-sdk')

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

await web3auth.init()

```

```
const { Web3Auth } = require('@web3auth/node-sdk')

const web3auth = new Web3Auth({
  clientId: 'YOUR_WEB3AUTH_CLIENT_ID', // Pass your Web3Auth Client ID, ideally using an environment variable
  web3AuthNetwork: 'sapphire_mainnet', // or 'sapphire_devnet'
  defaultChainId: '0x1', // or '0x89' for Polygon
  enableLogging: true,
})

await web3auth.init()

```

## Configuration parameters[​](#configuration-parameters "Direct link to Configuration parameters")

- Table
- Interface

| Parameter       | Type    | Default           | Description                                                                                                                             |
| --------------- | ------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| clientId        | string  | Required          | Your Web3Auth client ID                                                                                                                 |
| web3AuthNetwork | string  | sapphire_mainnet  | Network: sapphire_mainnet or sapphire_devnet                                                                                            |
| authBuildEnv    | string  | production        | Build environment for fetching project configuration                                                                                    |
| defaultChainId  | string  | Optional          | Chain ID to use for the default chain (for example, 0x1 for Ethereum). If not provided, the first chain in the list is used.            |
| chains          | object  | Optional          | Chain configurations to add or override dashboard chains. Merged with dashboard config; constructor values take precedence per chainId. |
| enableLogging   | boolean | false             | Setting to true will enable logs                                                                                                        |
| usePnPKey       | boolean | false             | Setting to true returns the same key as the web SDK (Plug and Play key). Default returns an SFA key.                                    |
| useDKG          | boolean | false on Sapphire | Setting to true generates keys/shares via a DKG network. Always true on legacy networks.                                                |
| checkCommitment | boolean | true              | Setting to true checks the commitment of the shares                                                                                     |

```
import type { BUILD_ENV_TYPE } from '@web3auth/auth'
import type { CustomChainConfig, WEB3AUTH_NETWORK_TYPE } from '@web3auth/no-modal'

export interface Web3AuthOptions {
  /**
   * Client id for web3auth.
   * You can obtain your client id from the web3auth developer dashboard.
   * You can set any random string for this on localhost.
   */
  clientId: string

  /**
   * Web3Auth Network to use for login
   * @defaultValue sapphire_mainnet
   */
  web3AuthNetwork?: WEB3AUTH_NETWORK_TYPE

  /**
   * Build environment for fetching project configuration
   * @defaultValue production
   */
  authBuildEnv?: BUILD_ENV_TYPE

  /**
   * multiple chain configurations,
   * only provided chains will be used
   */
  chains?: CustomChainConfig[]

  /**
   * default chain Id to use
   */
  defaultChainId?: string

  /**
   * setting to true will enable logs
   *
   * @defaultValue false
   */
  enableLogging?: boolean

  /**
   * setting this to true returns the same key as web sdk (i.e., plug n play key)
   * By default, this sdk returns SFAKey
   */
  usePnPKey?: boolean

  /**
   * set this to true when you wants keys/shares to be generated by a dkg network
   *
   * Default:- false for sapphire network and always true for legacy networks.
   * Legacy networks doesnt support non dkg flow. So this is always true for legacy networks.
   */
  useDKG?: boolean

  /**
   * setting this to true will check the commitment of the shares
   *
   * @defaultValue true
   */
  checkCommitment?: boolean
}

```

## Usage[​](#usage "Direct link to Usage")

```
const { Web3Auth } = require('@web3auth/node-sdk')

// Dashboard Registration
const clientId =
  'BPi5PB_UiIZ-cPz1GtV5i1I2iOSOHuimiXBI0e-Oe_u6X3oVAbCiAZOTEBtTXw4tsluTITPqA8zMsfxIKMjiqNQ'

// Auth connection
const authConnectionId = 'w3a-node-demo'

const web3auth = new Web3Auth({
  clientId,
  web3AuthNetwork: 'sapphire_mainnet',
})

await web3auth.init()

const privateKey = await fs.readFile('privateKey.pem', 'utf8')

var idToken = jwt.sign(
  {
    sub: '9fcd68c4-af50-4dd7-adf6-abd12a13cb32',
    name: 'Web3Auth DevRel Team',
    email: 'devrel@web3auth.io',
    aud: 'urn:api-web3auth-io', // -> to be used in Custom Authentication as JWT Field
    iss: 'https://web3auth.io', // -> to be used in Custom Authentication as JWT Field
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + 60 * 60,
  },
  privateKey,
  { algorithm: 'RS256', keyid: '2ma4enu1kdvw5bo9xsfpi3gcjzrt6q78yl0h' }
)

console.log('\x1b[33m%s\x1b[0m', 'JWT Token:', idToken)

const result = await web3auth.connect({
  authConnectionId,
  idToken,
})

```