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

Embedded Wallets SDK for Node.js

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​

  • 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​

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

Prerequisites​

tip

See the dashboard setup guide to learn more.

Installation​

Install the Web3Auth Node SDK

npm install --save @web3auth/node-sdk

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.
  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 guide to learn more.

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 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​

Initialize the Web3Auth instance during your application startup:

await web3auth.init()

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​

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()

Configuration parameters​

ParameterTypeDefaultDescription
clientIdstringRequiredYour Web3Auth client ID
web3AuthNetworkstringsapphire_mainnetNetwork: sapphire_mainnet or sapphire_devnet
authBuildEnvstringproductionBuild environment for fetching project configuration
defaultChainIdstringOptionalChain ID to use for the default chain (for example, 0x1 for Ethereum). If not provided, the first chain in the list is used.
chainsobjectOptionalChain configurations to add or override dashboard chains. Merged with dashboard config; constructor values take precedence per chainId.
enableLoggingbooleanfalseSetting to true will enable logs
usePnPKeybooleanfalseSetting to true returns the same key as the web SDK (Plug and Play key). Default returns an SFA key.
useDKGbooleanfalse on SapphireSetting to true generates keys/shares via a DKG network. Always true on legacy networks.
checkCommitmentbooleantrueSetting to true checks the commitment of the shares

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,
})
On this page