Skip to main content

Network Configuration

Privy is compatible with most EVM chains, and makes it easy to configure networks for your users' wallets.

Check out a high-level overview of network configuration with Privy, or jump directly into concrete instructions!

Overview​

Privy exposes two parameters to configure networks: a single default chain and a list of supported chains.

If you choose not to use these parameters in your app, you can instead use Privy's default configuration and supported chains.

Default Chain​

The default chain should be the primary network that wallets should use in your app.

For embedded wallets, when a user logs in or creates a wallet in your app, Privy will initialize the embedded wallet's network to the default chain. Thereafter, the embedded wallet will by default use the default chain, unless you manually switch the wallet's network to another supported chain.

For external wallets, when a user connects their wallet to your app, Privy will prompt the user to switch their network to the default chain, as long as the wallet supports the network. If the user declines to switch their network to the default chain, they will still be permitted to connect their wallet.

Supported Chains​

The supported chains list should be a list of networks that wallets are permitted to use in your app. This is intended as a guardrail against accidentally taking actions on the wrong network.

For embedded wallets, attempting to send a transaction on or switch the wallet to a network not in the list of supported chains will throw an error.

For external wallets, attempting to programmatically switch the wallet to a network not in the list of supported chains will throw an error.

If a list of supported chains is set but no default chain is set, the first entry of the supported chains list will be used as the default chain.

info

For external wallets (e.g. MetaMask), note that users may switch their wallet's network manually, independent of both Privy and your application. There is no way to prevent this behavior; you can only re-prompt the user to switch to a different network.

If a user manually switches their wallet to a network not in your app's list of supported chains, Privy will not throw an error. Instead, you can detect this via the wallet's EIP1193 provider's chainChanged event.

Configuration​

To configure networks for your app, first, install the viem/chains package. This package contains JSON representations of several EVM networks, which will be used to initialize the Privy SDK.

npm i viem/chains

Next, import your default chain and/or supported chains from the viem/chains package:

// Replace this with any of the networks listed at https://viem.sh/docs/clients/chains.html
import {base, baseGoerli, mainnet, goerli, polygon, polygonMumbai} from 'viem/chains';
info

If the EVM network you need is not included in viem/chains, you can create a custom representation using viem's defineChain method!

Lastly, configure your PrivyProvider with these additional network(s). In particular, the config property of the PrivyProvider contains the optional parameters:

  • defaultChain field, where you should pass a single chain object for your desired default chain
  • supportedChains field, where you should pass a list of chain objects for your desired supported chains
<PrivyProvider
    appId='your-privy-app-id'
    config={{
        ...theRestOfYourConfig,
        // Replace this with your desired default chain
        defaultChain: base
        // Replace this with a list of your desired supported chains
        supportedChains: [base, baseGoerli, mainnet, goerli, polygon, polygonMumbai]
    }}
>
    {/* your app's content */}
</PrivyProvider>
note

The PrivyProvider will throw an error if:

That's it! You've successfully configured networks for external and embedded wallets in your app. 🎉

tip

If you were previously using the config.additionalChains property to configure networks for your app, you should use config.supportedChains instead.

Default Configuration​

If you do not set defaultChain or supportedChains for your app, Privy defaults to the following:

  • External wallets will not be prompted to switch networks when connecting to your app.
  • Embedded wallets will initialize on Ethereum mainnet or the network used in the user's previous session on that device.

For both external and embedded wallets, you can switch a wallet to any of the following networks that are available from Privy out-of-the-box:

NetworkChain IDSupported?
Arbitrum42161✅
Arbitrum Goerli421613✅*
Arbitrum Sepolia421614✅
Avalanche C-Chain43114✅
Avalanche Fuji43113✅
Base8453✅
Base Goerli84531✅
Celo42220✅
Celo Alfajores44787✅
Ethereum1✅
Ethereum Goerli5✅
Ethereum Sepolia11155111✅
Holesky17000✅
Holesky Redstone17001✅
Linea59144✅
Linea Testnet59140✅
Optimism10✅
Optimism Goerli420✅
Polygon137✅
Polygon Mumbai80001✅
Zora7777777✅
Zora Goerli999✅

*As of November 18, 2023, Arbitrum Goerli has been deprecated. The @privy-io/react-auth package still includes client-side support for Arbitrum Goerli but RPC requests may fail.