Advanced configuration

All advanced SDK settings are configured in a web3authConfig.ts file and passed to Web3AuthProvider via the config prop. There is no constructor to call — the provider initialises the SDK automatically using the options you supply.

Configuration file

web3authConfig.ts

import {
  CHAIN_NAMESPACES,
  WEB3AUTH_NETWORK,
  MFA_LEVELS,
  type Web3AuthContextConfig,
} from '@web3auth/react-native-sdk'

const web3AuthConfig: Web3AuthContextConfig = {
  web3AuthOptions: {
    clientId: 'YOUR_CLIENT_ID', // from developer.metamask.io
    redirectUrl: 'yourapp://auth',
    network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
    chains: [
      {
        chainNamespace: CHAIN_NAMESPACES.EIP155,
        chainId: '0xaa36a7',
        rpcTarget: 'https://rpc.ankr.com/eth_sepolia',
        displayName: 'Ethereum Sepolia Testnet',
        blockExplorerUrl: 'https://sepolia.etherscan.io',
        ticker: 'ETH',
        tickerName: 'Ethereum',
      },
    ],
    defaultChainId: '0xaa36a7',
    // Optional advanced settings:
    mfaLevel: MFA_LEVELS.DEFAULT,
    sessionTime: 86400 * 7, // 7 days
    enableLogging: false,
  },
}

export default web3AuthConfig

web3AuthOptions parameter reference

Parameters

Parameter	Required	Description
clientId	Yes	Your project's Client ID from the Embedded Wallets dashboard.
network	Yes	Sapphire network to use. Use WEB3AUTH_NETWORK.SAPPHIRE_DEVNET for development (allows localhost) and WEB3AUTH_NETWORK.SAPPHIRE_MAINNET for production.
redirectUrl	Yes	Deep link URL that Web3Auth redirects to after authentication. Must be allowlisted in the dashboard under Allowed Origins.
chains?	No	Array of CustomChainConfig objects defining the EVM or Solana chains your app supports. Replaces the v8 privateKeyProvider pattern. The SDK creates the appropriate provider automatically based on chainNamespace.
defaultChainId?	No	Hex chain ID string for the default active chain (for example, "0xaa36a7"). Defaults to the first entry in chains.
accountAbstractionConfig?	No	Smart account configuration (AccountAbstractionMultiChainConfig). Set smartAccountType to "safe" or another supported provider to enable account abstraction. Set to null to disable.
walletServicesConfig?	No	Configuration for the Wallet Services in-app browser overlay. Controls confirmationStrategy and other embed parameters.
whiteLabel?	No	Custom branding and UI options (WhiteLabelData). Applies to the authentication screens launched in the in-app browser.
mfaLevel?	No	Default MFA prompt behavior. Accepts MFA_LEVELS.DEFAULT, MFA_LEVELS.OPTIONAL, MFA_LEVELS.MANDATORY, or MFA_LEVELS.NONE.
sessionTime?	No	Session duration in seconds. Minimum is 1; maximum is 86400 * 30 (30 days). Defaults to 86400 (1 day).
enableLogging?	No	Set to true to print SDK debug logs to the console. Defaults to false.
walletSdkURL?	No	Optional URL override for the Wallet Services embed. Leave unset to use the default production URL.

Interface

export interface SdkInitParams {
  /** Your project Client ID from the Embedded Wallets dashboard */
  clientId: string
  /** Sapphire network — SAPPHIRE_DEVNET or SAPPHIRE_MAINNET */
  network: WEB3AUTH_NETWORK_TYPE
  /** Deep link URL registered in the dashboard under Allowed Origins */
  redirectUrl: string
  /** EVM / Solana chain configurations — replaces privateKeyProvider */
  chains?: CustomChainConfig[]
  /** Default active chain ID (hex string) */
  defaultChainId?: string
  /** Smart account configuration; set to null to disable */
  accountAbstractionConfig?: AccountAbstractionMultiChainConfig | null
  /** Wallet Services overlay configuration */
  walletServicesConfig?: WalletServicesConfig
  /** Whitelabel and branding options */
  whiteLabel?: WhiteLabelData
  /** Default MFA level */
  mfaLevel?: MfaLevelType
  /** Session duration in seconds (default: 86400) */
  sessionTime?: number
  /** Enable SDK debug logging */
  enableLogging?: boolean
  /** Override URL for the Wallet Services embed */
  walletSdkURL?: string
}

Chain configuration

Pass an array of CustomChainConfig objects to the chains field in web3AuthOptions. The SDK selects the appropriate EVM or Solana provider automatically based on chainNamespace.

EVM chain

import { CHAIN_NAMESPACES } from '@web3auth/react-native-sdk'

const web3AuthConfig = {
  web3AuthOptions: {
    clientId: 'YOUR_CLIENT_ID',
    redirectUrl: 'yourapp://auth',
    network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
    chains: [
      {
        chainNamespace: CHAIN_NAMESPACES.EIP155,
        chainId: '0xaa36a7', // Ethereum Sepolia
        rpcTarget: 'https://rpc.ankr.com/eth_sepolia',
        displayName: 'Ethereum Sepolia',
        blockExplorerUrl: 'https://sepolia.etherscan.io',
        ticker: 'ETH',
        tickerName: 'Ethereum',
      },
    ],
    defaultChainId: '0xaa36a7',
  },
}

Solana chain

import { CHAIN_NAMESPACES } from '@web3auth/react-native-sdk'

const web3AuthConfig = {
  web3AuthOptions: {
    clientId: 'YOUR_CLIENT_ID',
    redirectUrl: 'yourapp://auth',
    network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
    chains: [
      {
        chainNamespace: CHAIN_NAMESPACES.SOLANA,
        chainId: '0x2', // Solana Testnet
        rpcTarget: 'https://api.testnet.solana.com',
        displayName: 'Solana Testnet',
        blockExplorerUrl: 'https://explorer.solana.com',
        ticker: 'SOL',
        tickerName: 'Solana',
        logo: 'https://images.toruswallet.io/solana.svg',
      },
    ],
    defaultChainId: '0x2',
  },
}

Interface

export interface CustomChainConfig {
  /** Chain namespace: CHAIN_NAMESPACES.EIP155 for EVM, CHAIN_NAMESPACES.SOLANA for Solana */
  chainNamespace: ChainNamespaceType
  /** Chain ID as a hex string (for example, "0x1" for Ethereum mainnet) */
  chainId: string
  /** JSON-RPC endpoint URL for this chain */
  rpcTarget: string
  /** Human-readable chain name shown in the UI */
  displayName?: string
  /** Block explorer base URL */
  blockExplorerUrl?: string
  /** Native token ticker symbol (for example, "ETH") */
  ticker?: string
  /** Native token full name (for example, "Ethereum") */
  tickerName?: string
  /** Token logo URL */
  logo?: string
  /** WebSocket endpoint URL (optional) */
  wsTarget?: string
}

CHAIN_NAMESPACES

Constant	Use for
CHAIN_NAMESPACES.EIP155	All EVM-compatible chains
CHAIN_NAMESPACES.SOLANA	Solana mainnet, devnet, testnet

Session management

Control how long users stay authenticated by setting sessionTime in web3AuthOptions:

• Minimum: 1 second
• Maximum: 86400 * 30 (30 days)
• Default: 86400 (1 day)

web3AuthOptions: {
  // ...
  sessionTime: 86400 * 7, // 7 days
}

Advanced topics

• Custom authentication — configure social login connections and custom JWT flows
• Smart accounts — enable ERC-4337 account abstraction
• Whitelabeling — customize authentication UI branding
• Multi-Factor Authentication — control MFA prompts and factor configuration
• Dapp share — pass a custom device share for MFA-enabled wallets