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

primaryConnectorName​

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

Interface​

get primaryConnectorName(): WALLET_CONNECTOR_TYPE | null;
WALLET_CONNECTOR_TYPE​
EventDescription
AUTHWeb3Auth connector.
WALLET_CONNECT_V2WalletConnect V2 connector.
COINBASECoinbase connector.
BASE_ACCOUNTBase Account connector.
METAMASKMetaMask connector.

Usage​

const connectorName = web3auth.primaryConnectorName

status​

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

Interface​

status: CONNECTOR_STATUS_TYPE
CONNECTOR_STATUS_TYPE​
EventDescription
NOT_READYTriggered when the connector is not ready.
READYTriggered when the connector is ready.
CONNECTINGTriggered when a connection is being established.
CONNECTEDTriggered when a wallet is successfully connected.
DISCONNECTINGTriggered when the wallet is in the process of Disconnecting.
DISCONNECTEDTriggered when the wallet is Disconnected.
ERROREDTriggered when an error occurs during the connection lifecycle.
AUTHORIZINGTriggered while the SDK requests a signature to issue the idToken.
AUTHORIZEDTriggered when the wallet is connected and the idToken is issued.
CONSENT_REQUIRINGTriggered when the user must accept the terms before the session continues.

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 = {
  chainNamespace: 'eip155',
  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',
}
ParameterDescription
chainNamespaceNamespace of the chain
chainIdChain ID of the chain
rpcTargetRPC target URL for the chain
wsTarget?Web socket target URL for the chain
displayNameDisplay name for the chain
blockExplorerUrlURL of the block explorer
tickerDefault currency ticker of the network
tickerNameName for currency ticker
decimals?Number of decimals for the currency
logoLogo for the token
isTestnet?Whether the network is testnet or not
fallbackRpcTargets?Fallback RPC target URLs
fallbackWsTargets?Fallback web socket target URLs

Usage​

const chain = web3auth.currentChain

primaryConnector​

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

Interface​

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

Usage​

const connector = web3auth.primaryConnector

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 BASE_ACCOUNT: "base-account";
  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, analytics?: Analytics): Promise<void>;
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  cleanup(): Promise<void>;
}

Usage​

import { EVM_PLUGINS } from '@web3auth/modal'

// EVM_PLUGINS.WALLET_SERVICES is 'wallet-services'
const plugin = web3auth.getPlugin(EVM_PLUGINS.WALLET_SERVICES)

Events​

The Web3Auth instance is an event emitter. Subscribe to lifecycle events with web3auth.on() and the CONNECTOR_EVENTS constants.

import { CONNECTOR_EVENTS } from '@web3auth/modal'

web3auth.on(CONNECTOR_EVENTS.CONNECTED, data => {
  console.log('Connected with', data.connectorName)
})

web3auth.on(CONNECTOR_EVENTS.DISCONNECTED, () => {
  console.log('Disconnected')
})

web3auth.on(CONNECTOR_EVENTS.ERRORED, error => {
  console.error(error)
})

CONNECTOR_EVENTS includes every CONNECTOR_STATUS value, plus:

export const CONNECTOR_EVENTS = {
  ...CONNECTOR_STATUS,
  CONNECTOR_DATA_UPDATED: 'connector_data_updated',
  CACHE_CLEAR: 'cache_clear',
  CONNECTORS_UPDATED: 'connectors_updated',
  MFA_ENABLED: 'mfa_enabled',
  REHYDRATION_ERROR: 'rehydration_error',
  // Emitted when the active connection changes without a full reconnect (for example, account switch)
  CONNECTION_UPDATED: 'connection_updated',
  CONSENT_ACCEPTED: 'consent_accepted',
} as const
On this page