@web3auth/node-sdk

Web3Auth's Node.js SDK

Web3Auth is where passwordless auth meets non-custodial key infrastructure for Web3 apps and wallets. By aggregating OAuth (Google, Twitter, Discord) logins, different wallets and innovative Multi Party Computation (MPC) - Web3Auth provides a seamless login experience to every user on your application.

Documentation

Checkout the official Web3Auth Documentation and SDK Reference to get started!

Features

• Plug and Play, OAuth based Web3 Authentication Service
• Fully decentralized, non-custodial key infrastructure
• End to end Whitelabelable solution
• Threshold Cryptography based Key Reconstruction
• Multi Factor Authentication Setup & Recovery (Includes password, backup phrase, device factor editing/deletion etc)
• Support for WebAuthn & Passwordless Login
• Support for connecting to multiple wallets
• DApp Active Session Management

...and a lot more

Quick Start

Installation

npm install --save @web3auth/node-sdk

Get your Client ID from Web3Auth Dashboard

Hop on to the Web3Auth Dashboard and create a new project. Use the Client ID of the project to start your integration.

Initialize Web3Auth

import { Web3Auth } from "@web3auth/node-sdk";
import { CHAIN_NAMESPACES } from "@web3auth/no-modal";

const web3auth = new Web3Auth({
  clientId: "", // Get your Client ID from Web3Auth Dashboard
  web3AuthNetwork: "sapphire_mainnet",
  chains: [
    {
      chainNamespace: CHAIN_NAMESPACES.EIP155,
      displayName: "ETH Mainnet",
      blockExplorerUrl: "https://etherscan.io",
      ticker: "ETH",
      tickerName: "Ethereum",
      chainId: "0x1",
      rpcTarget: "https://rpc.ankr.com/eth",
    },
  ],
});

await web3auth.init();

Login your User

connect() returns a WalletResult containing a provider, a typed signer, and the chainNamespace:

const result = await web3auth.connect({
  authConnectionId: "your-auth-connection-id",
  idToken: "JWT Token",
  userId: "user@example.com",
});

// result.provider  — the underlying key provider
// result.signer    — a chain-specific signer (WalletClient for EIP155, TransactionSigner for Solana, null for OTHER)
// result.chainNamespace — "eip155" | "solana" | "other"

WalletResult

connect() returns a discriminated union based on chainNamespace:

chainNamespace	signer type	Description
eip155	WalletClient (viem)	EVM-compatible chains
solana	TransactionSigner (@solana/signers)	Solana chains
other	null	Other chain namespaces

if (result.chainNamespace === CHAIN_NAMESPACES.EIP155) {
  // result.signer is a viem WalletClient
  const address = result.signer.account?.address;
} else if (result.chainNamespace === CHAIN_NAMESPACES.SOLANA) {
  // result.signer is a @solana/signers TransactionSigner
  const address = result.signer.address;
}

Migration from v4.x

Breaking changes in v5.0.0

• init() no longer takes parameters. Chain configuration is now passed via the chains option in the constructor. Remove the provider parameter from init().
• chains is required. Pass at least one CustomChainConfig in the constructor.
• connect() returns WalletResult instead of a raw provider. Access the provider via result.provider and a chain-typed signer via result.signer.
• verifier / verifierId renamed. Use authConnectionId and userId instead.
• Node.js 22+ required.

Before (v4.x)

const provider = new EthereumPrivateKeyProvider({ config: { chainConfig } });
web3auth.init({ provider });

const provider = await web3auth.connect({
  verifier: "verifier-name",
  verifierId: "user@example.com",
  idToken: "JWT Token",
});

After (v5.0.0)

const web3auth = new Web3Auth({
  clientId: "...",
  web3AuthNetwork: "sapphire_mainnet",
  chains: [{ chainNamespace: CHAIN_NAMESPACES.EIP155, chainId: "0x1", rpcTarget: "...", /* ... */ }],
});
await web3auth.init();

const result = await web3auth.connect({
  authConnectionId: "your-auth-connection-id",
  userId: "user@example.com",
  idToken: "JWT Token",
});
// result.provider — same provider as before
// result.signer  — typed signer for the chain

Requirements

• Node 22+

Examples

Checkout the examples for your preferred blockchain and platform in our examples repository

Demo

Checkout the Web3Auth Demo to see how Web3Auth can be used in your application.

Troubleshooting and Discussions

• Have a look at our GitHub Discussions to see if anyone has any questions or issues you might be having.
• Checkout our Troubleshooting Documentation Page to know the common issues and solutions
• Join our Discord to join our community and get private integration support or help with your integration.