EIP-1193 compliant Provider for the WalletConnect v2 protocol.
Built on top of Universal Provider and WalletConnectModal.
You can use this on it’s own or pass it down to libraries like ethers, viem or web3js.
showQrModal has been deprecated as WalletConnect’s Web3Modal is now rebranded as Reown’s AppKit. If you are looking to use this, please refer to the “Use with AppKit” section below.
Initialize Ethereum Provider by calling its init method and passing down the required arguments:
import { EthereumProvider } from "@walletconnect/ethereum-provider";const provider = await EthereumProvider.init({ projectId: "YOUR_PROJECT_ID", metadata: { name: "My Website", description: "My Website Description", url: "https://mywebsite.com", // origin must match your domain & subdomain icons: ["https://avatars.githubusercontent.com/u/37784886"], }, showQrModal: true, optionalChains: [1, 137, 2020], /*Optional - Add custom RPCs for each supported chain*/ rpcMap: { 1: "mainnet.rpc...", 137: "polygon.rpc...", },});
Make sure that url from metadata matches your domain and subdomain. This will later be used by Verify API to confirm if your application has been verified or not.
We recommend using optionalChains (optional namespaces) over chains (required namespaces). Required namespaces will block wallets from connecting to your application if any of the chains are not supported by the wallet. Smart Contract Wallets can only support one chain,
the one that they had been deployed to, this might cause issues when using required namespaces.
Using chains, methods or events will create a Required Namespaces object internally.
optionalMethods and optionalChains default to the following methods and events: Read source code.
If rpcMap is not defined it will fallback to Blockchain API RPCs. Keep in mind that Blockchain API supports a limited list of chains.
An array of the chain IDs you want to support. It is highly recommended to use “optionalChains” over “chains” for multi-chain dapps, ensuring compatibility with Smart Contract Wallets.
number[]
false
optionalMethods
The Ethereum methods you want to support and send in the session proposal under the “optionalNamespaces” scope. If undefined, it defaults to all EIP-1193 compatible methods.
string[]
false
optionalEvents
The Ethereum events you want to support and send in the session proposal under the “optionalNamespaces” scope. If undefined, it defaults to all EIP-1193 compatible events.
string[]
false
rpcMap
An object whose keys are chain IDs and values are their RPC endpoints.
Record<number, string>
false
metadata
Your application’s metadata. It is important to set the correct URL, as this will later be used by the Verify API to check if your domain has been verified.
Metadata
false
qrModalOptions
An array of WalletConnectModal options. See WalletConnectModal options.
QrModalOptions
false
chains
An array of required chain IDs you want to support. If the wallet does not support these chains, it will not be able to connect. Not recommended for multi-chain applications.
number[]
false
methods
The required methods you want to support. Not recommended for multi-chain applications.
string[]
false
events
The required events you want to support. Not recommended for multi-chain applications.
You can then use the URI to generate a QR Code or redirect the user from the mobile browser to the wallet and request to connect.
The later one will require you to use the wallet’s deep link and the URI. You can get the deep link of wallets that support the WalletConnect v2 protocol from the Explorer API.
// chain changedprovider.on("chainChanged", handler);// accounts changedprovider.on("accountsChanged", handler);// session establishedprovider.on("connect", handler);// session event - chainChanged/accountsChanged/custom eventsprovider.on("session_event", handler);// connection uriprovider.on("display_uri", handler);// session disconnected from the wallet - this won't be called when the disconnect function is called from the dapp.provider.on("disconnect", handler);
Once a wallet is connected you can find the session data in the provider.session object.The session object includes the following properties, among others:
namespaces: session.namespaces is an object that contains the approved session data.
Note that the chains object is an optional parameter and may be undefined. Therefore, we encourage apps to obtain the approved chains from the session.accounts object instead.