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

Advanced configuration

Configure the SDK in web3authConfig.ts and pass it to Web3AuthProvider through the config prop. The provider initializes the SDK with these options. Most settings can also be set on the dashboard; options you pass in code are merged with the dashboard settings.

Configuration file​

web3authConfig.ts
import {
  CHAIN_NAMESPACES,
  WEB3AUTH_NETWORK,
  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://ethereum-sepolia-rpc.publicnode.com',
        displayName: 'Ethereum Sepolia Testnet',
        blockExplorerUrl: 'https://sepolia.etherscan.io',
        ticker: 'ETH',
        tickerName: 'Ethereum',
      },
    ],
    defaultChainId: '0xaa36a7',
    // Optional advanced settings:
    sessionTime: 86400 * 7, // 7 days
    enableLogging: false,
  },
}

export default web3AuthConfig

web3AuthOptions reference​

ParameterRequiredDescription
clientIdYesClient ID of your project on the Embedded Wallets dashboard.
redirectUrlYesDeep link the in-app browser returns to after sign-in, for example yourapp://auth. Must be allowlisted on the dashboard.
networkYesWEB3AUTH_NETWORK.SAPPHIRE_MAINNET or WEB3AUTH_NETWORK.SAPPHIRE_DEVNET. Must match the network of your dashboard project.
chainsNoArray of CustomChainConfig objects. Merged with the chains configured on the dashboard; entries with the same chainId override the dashboard values. Initialization fails if no chains are configured in either place.
defaultChainIdNoHex chain ID of the chain to use after sign-in. If not set, the SDK uses the first chain in the merged list. Dashboard chains come first in that list, so set defaultChainId if you configure chains both on the dashboard and in code.
accountAbstractionConfigNoSmart account configuration, merged with the dashboard smart account settings. Set to null to turn off smart accounts that are enabled on the dashboard.
useAAWithExternalWalletNoWhether to use smart accounts with external wallets. If not set, the SDK uses the dashboard wallet scope setting.
walletServicesConfigNoWallet Services settings, such as confirmationStrategy ('default', 'auto-approve', or 'modal'), enableKeyExport, and whiteLabel. Overrides the dashboard Wallet UI settings.
whiteLabelNoBranding for the sign-in screens. Merged with the dashboard branding settings. See Whitelabel.
mfaSettingsNoMFA factor configuration. See Multi-factor authentication.
sessionTimeNoSession duration in seconds. If not set, the SDK uses the session duration configured on the dashboard (30 days by default).
authConnectionConfigNoAdditional auth connection definitions, merged with the connections configured on the dashboard.
useCoreKitKeyNoUse the Core Kit key instead of the default key. Only set this if you migrate users from a Core Kit integration.
enableLoggingNoPrint SDK debug logs. The default is false.
disableAnalyticsNoTurn off the anonymous usage analytics that the SDK sends. The default is false.
walletSdkURLNoOverride the Wallet Services URL, for example to point at a staging deployment. If not set, the SDK picks the URL for buildEnv (production by default).

Chain configuration​

Pass an array of CustomChainConfig objects to the chains field in web3AuthOptions. After sign-in, the SDK exposes connection.ethereumProvider for CHAIN_NAMESPACES.EIP155 chains and connection.solanaWallet for CHAIN_NAMESPACES.SOLANA chains, based on the active chain. Solana chains must use the chain IDs 0x65 (Mainnet), 0x66 (Testnet), or 0x67 (Devnet).

import { CHAIN_NAMESPACES, WEB3AUTH_NETWORK } 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://ethereum-sepolia-rpc.publicnode.com',
        displayName: 'Ethereum Sepolia',
        blockExplorerUrl: 'https://sepolia.etherscan.io',
        ticker: 'ETH',
        tickerName: 'Ethereum',
      },
    ],
    defaultChainId: '0xaa36a7',
  },
}

CHAIN_NAMESPACES​

ConstantUse for
CHAIN_NAMESPACES.EIP155All EVM-compatible chains
CHAIN_NAMESPACES.SOLANASolana mainnet, devnet, testnet

Session management​

Set sessionTime in web3AuthOptions to control how long users stay signed in, in seconds. If you don't set it, the SDK uses the session duration configured on the dashboard (30 days by default).

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

Advanced topics​

On this page