> 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 enables seamless integration of 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 18+ - 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 The chain information is optional and will be used to setup the provider for connecting to the chain. If not provided, the first chain in the list will be used. ### 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, sessionTime: 3600, }) 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 | Required | Network: 'sapphire_mainnet' or 'sapphire_devnet' | | 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 will be used. | | chains | object | Optional | Chains to use for the authentication. It takes Chains as a value. | | enableLogging | boolean | Optional | Setting to true will enable logs. Default is false. | | usePnPKey | boolean | Optional | Setting to true will use the PnP key. Default is false. | | useDKG | boolean | Optional | Setting to true will use the DKG. Default is false. | | checkCommitment | boolean | Optional | Setting to true will check the commitment. Default is true. | ``` 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 mainnet */ web3AuthNetwork?: WEB3AUTH_NETWORK_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, }) ```