Skip to main content

Custom Chains

caution

This documentation is for Web3Modal v2. You can find Web3Modal v3 docs here

Custom wagmi chains​

Web3Modal's chain configuration happens entirely via wagmi. Please refer to wagmi chains documentation to see which defaults are available and how to create your own chain.

Below is a simplified example that sets up mainnet, avalanche and arbitrum chains:

import { w3mProvider } from '@web3modal/ethereum'
import { configureChains } from '@wagmi/core'
import { arbitrum, mainnet, avalanche } from 'viem/chains'

const chains = [mainnet, avalanche, arbitrum]
const { publicClient } = configureChains(chains, [
  w3mProvider({
    /* ... */
  })
])

Custom default chain​

By default Web3Modal will connect to the chain that was set by user's wallet. If you want user to be connected to a specific chain by default, you can set it via defaultChain option:

import { optimism } from 'viem/chains'

const web3modal = new Web3Modal({
  defaultChain: optimism
})

Custom chain providers​

Wagmi requires that one or more providers (RPCs) are configured that support all your target chains. Web3Modal provides WalletConnect RPC via w3mProvider helper. WalletConnect RPC https://rpc.walletconnect.com is free to use (rate limit may be applied to specific users if abuse is detected). WalletConnect RPC currently supports following chains:

1, 3, 4, 5, 10, 42, 56, 69, 97, 100, 137, 280, 324, 420, 42161, 42220, 43114, 80001, 421611, 421613, 1313161554, 1313161555

Please refer to wagmi providers documentation to see how to configure alternative providers, combine or prioritize them.

Below is a simplified example of how to combine WalletConnect RPC and Infura one:

import { mainnet } from 'viem/chains'
import { infuraProvider } from '@wagmi/core/providers/infura'
import { w3mProvider } from '@web3modal/ethereum'

const { chains, publicClient } = configureChains(
  [mainnet],
  [
    w3mProvider({
      /* ... */
    }),
    alchemyProvider({
      /* ... */
    })
  ]
)

Custom chain images​

Web3Modal tries to provide default images for most wagmi chain defaults, but if image for your chain is missing or you want to override it, you can use chainImages options:

const web3modal = new Web3Modal({
  chainImages: {
    1: 'https://example.com/ethereum.png',
    137: 'https://example.com/polygon.webp'
  }
})