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.
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';
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 chainsupportedChains
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>
The PrivyProvider
will throw an error if:
- an empty array (
[]
) is passed intosupportedChains
- a chain is passed into
defaultChain
that is not also included insupportedChains
array
That's it! You've successfully configured networks for external and embedded wallets in your app. ๐
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:
Network | Chain ID | Supported? |
---|---|---|
Arbitrum | 42161 | โ |
Arbitrum Goerli | 421613 | โ * |
Arbitrum Sepolia | 421614 | โ |
Avalanche C-Chain | 43114 | โ |
Avalanche Fuji | 43113 | โ |
Base | 8453 | โ |
Base Goerli | 84531 | โ |
Celo | 42220 | โ |
Celo Alfajores | 44787 | โ |
Ethereum | 1 | โ |
Ethereum Goerli | 5 | โ |
Ethereum Sepolia | 11155111 | โ |
Holesky | 17000 | โ |
Holesky Redstone | 17001 | โ |
Linea | 59144 | โ |
Linea Testnet | 59140 | โ |
Optimism | 10 | โ |
Optimism Goerli | 420 | โ |
Polygon | 137 | โ |
Polygon Mumbai | 80001 | โ |
Zora | 7777777 | โ |
Zora Goerli | 999 | โ |
*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.