Embedded Wallets events and status

This page documents the key properties and lifecycle events available from an Embedded Wallets instance. These allow you to track the connection status, react to changes, and build responsive user experiences.

connected

Returns true if a wallet is connected, otherwise false.

Interface

get connected(): boolean;

Usage

const isConnected = web3auth.connected

connection

Returns the active wallet connection, including the Ethereum provider and Solana wallet when connected.

Usage

const provider = web3auth.connection?.ethereumProvider ?? null
const solanaWallet = web3auth.connection?.solanaWallet ?? null

note

In Web SDK v11, reading web3auth.provider returns undefined. Use connection instead.

connectedConnectorName

Name of the currently connected wallet connector, or null if not connected.

Interface

connectedConnectorName: WALLET_CONNECTOR_TYPE | null

WALLET_CONNECTOR_TYPE

Table

Event	Description
AUTH	Web3Auth connector.
WALLET_CONNECT_V2	WalletConnect V2 connector.
COINBASE	Coinbase connector.
METAMASK	MetaMask connector.

Interface

export type WALLET_CONNECTOR_TYPE = (typeof WALLET_CONNECTORS)[keyof typeof WALLET_CONNECTORS]
export declare const WALLET_CONNECTORS: {
  readonly AUTH: 'auth'
  readonly WALLET_CONNECT_V2: 'wallet-connect-v2'
  readonly COINBASE: 'coinbase'
  readonly METAMASK: 'metamask'
}

Usage

const connectorName = web3auth.connectedConnectorName

status

Current status of the Web3Auth instance. Emits status change events.

Interface

status: CONNECTOR_STATUS_TYPE

CONNECTOR_STATUS_TYPE

Table

Event	Description
NOT_READY	Triggered when the connector is not ready.
READY	Triggered when the connector is ready.
CONNECTING	Triggered when a connection is being established.
CONNECTED	Triggered when a wallet is successfully connected.
DISCONNECTING	Triggered when the wallet is in the process of Disconnecting.
DISCONNECTED	Triggered when the wallet is Disconnected.
ERRORED	Triggered when an error occurs during the connection lifecycle.

Interface

export type CONNECTOR_STATUS_TYPE = (typeof CONNECTOR_STATUS)[keyof typeof CONNECTOR_STATUS]
export declare const CONNECTOR_STATUS: {
  readonly NOT_READY: 'not_ready'
  readonly READY: 'ready'
  readonly CONNECTING: 'connecting'
  readonly CONNECTED: 'connected'
  readonly DISCONNECTING: 'disconnecting'
  readonly DISCONNECTED: 'disconnected'
  readonly ERRORED: 'errored'
}

Usage

const status = web3auth.status

currentChain

Returns the current chain configuration if connected.

Interface

get currentChain(): CustomChainConfig | undefined;

chainConfig

In Web SDK v11, configure chains on the Embedded Wallets dashboard. The shape of each chain matches CustomChainConfig:

const chainConfig = {
  chainId: '0x1', // Please use 0x1 for Mainnet
  rpcTarget: 'https://rpc.ethereum.org',
  displayName: 'Ethereum Mainnet',
  blockExplorerUrl: 'https://etherscan.io/',
  ticker: 'ETH',
  tickerName: 'Ethereum',
  logo: 'https://images.toruswallet.io/eth.svg',
}

Table

Parameter	Description
chainNamespace	Namespace of the chain
chainId	Chain ID of the chain
rpcTarget	RPC target URL for the chain
wsTarget?	Web socket target URL for the chain
displayName?	Display name for the chain
blockExplorerUrl?	URL of the block explorer
ticker?	Default currency ticker of the network
tickerName?	Name for currency ticker
decimals?	Number of decimals for the currency
logo?	Logo for the token
isTestnet?	Whether the network is testnet or not

Type Declarations

export declare const CHAIN_NAMESPACES: {
  readonly EIP155: 'eip155'
  readonly SOLANA: 'solana'
  readonly CASPER: 'casper'
  readonly XRPL: 'xrpl'
  readonly OTHER: 'other'
}

export type ChainNamespaceType = (typeof CHAIN_NAMESPACES)[keyof typeof CHAIN_NAMESPACES]
export type CustomChainConfig = {
  chainNamespace: ChainNamespaceType
  /**
   * The chain id of the chain
   */
  chainId: string
  /**
   * RPC target Url for the chain
   */
  rpcTarget: string
  /**
   * web socket target url for the chain
   */
  wsTarget?: string
  /**
   * Display Name for the chain
   */
  displayName?: string
  /**
   * Url of the block explorer
   */
  blockExplorerUrl?: string
  /**
   * Default currency ticker of the network (e.g: ETH)
   */
  ticker?: string
  /**
   * Name for currency ticker (e.g: `Ethereum`)
   */
  tickerName?: string
  /**
   * Number of decimals for the currency ticker (e.g: 18)
   */
  decimals?: number
  /**
   * Logo for the token
   */
  logo?: string
  /**
   * Whether the network is testnet or not
   */
  isTestnet?: boolean
}

Usage

const chain = web3auth.currentChain

connectedConnector

Returns the connector instance for the connected wallet, or null.

Interface

get connectedConnector(): IConnector<unknown> | null;

Usage

const connector = web3auth.connectedConnector

accountAbstractionProvider

Returns the account abstraction provider if available.

Interface

get accountAbstractionProvider(): AccountAbstractionProvider | null;

Usage

const aaProvider = web3auth.accountAbstractionProvider

getConnector

Returns a connector instance for a given connector name and chain namespace.

Interface

getConnector(connectorName: WALLET_CONNECTOR_TYPE, chainNamespace?: ChainNamespaceType): IConnector<unknown> | null;

export type WALLET_CONNECTOR_TYPE = (typeof WALLET_CONNECTORS)[keyof typeof WALLET_CONNECTORS];
export declare const WALLET_CONNECTORS: {
  readonly AUTH: "auth";
  readonly WALLET_CONNECT_V2: "wallet-connect-v2";
  readonly COINBASE: "coinbase";
  readonly METAMASK: "metamask";
};
export type ChainNamespaceType = (typeof CHAIN_NAMESPACES)[keyof typeof CHAIN_NAMESPACES];

Usage

import { WALLET_CONNECTORS } from '@web3auth/modal'

const connector = web3auth.getConnector(WALLET_CONNECTORS.WALLET_CONNECT_V2, 'eip155')

getPlugin

Returns a plugin instance by name, or null if not found.

Interface

getPlugin(name: string): IPlugin | null;

export interface IPlugin extends SafeEventEmitter {
  name: string;
  status: PLUGIN_STATUS_TYPE;
  SUPPORTED_CONNECTORS: WALLET_CONNECTOR_TYPE[];
  pluginNamespace: PluginNamespace;
  initWithWeb3Auth(web3auth: IWeb3AuthCore, whiteLabel?: WhiteLabelData): Promise<void>;
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  cleanup(): Promise<void>;
}

Usage

const plugin = web3auth.getPlugin('walletServices')