Ethereum Provider

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.

Installation

npm

npm install @walletconnect/ethereum-provider

Initialization

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.

Init Params

The Ethereum Provider’s init method takes the following parameters:

Value	Description	Type	Required
projectId	Your project ID obtained from Reown Dashboard: https://dashboard.reown.com/	string	true
optionalChains	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.	string[]	false

Use with AppKit

The QRModal is enabled by default on reown’s AppKit. In order to use it, all you need to do is to create an AppKit instance.

Installation

npm

npm install @reown/appkit

Setup

Upon integrating the below code, you will be able to see the QRModal on your Web3 App.

import { createAppKit } from "@reown/appkit";
import { mainnet, arbitrum, sepolia } from "@reown/appkit/networks";

// 1. Get projectId from https://dashboard.reown.com
const projectId = "YOUR_PROJECT_ID";

// 2. Create the AppKit instance
const modal = createAppKit({
  networks: [mainnet, arbitrum, sepolia],
  projectId,
});

Use without AppKit

You can subscribe to the display_uri event and handle the URI yourself.

function handleURI(uri: string) {
  //code...
}

provider.on("display_uri", handleURI);

await provider.connect();
// or
const accounts = await provider.enable();

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.

Sending Requests

const result = await provider.request({ method: "eth_requestAccounts" });

// OR

provider.sendAsync({ method: "eth_requestAccounts" }, CallBackFunction);

Events

// chain changed
provider.on("chainChanged", handler);
// accounts changed
provider.on("accountsChanged", handler);
// session established
provider.on("connect", handler);
// session event - chainChanged/accountsChanged/custom events
provider.on("session_event", handler);
// connection uri
provider.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);

Session data

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.

interface Namespaces {
  chains?: string[];
  accounts: string[];
  methods: string[];
  events: string[];
}

• requiredNamespaces, optionalNamespaces & sessionProperties: These objects contain the namespaces and properties proposed for the session.
• peer: The session.peer.metadata object contains the metadata of the connected wallet.

interface Metadata {
  name: string;
  description: string;
  url: string;
  icons: string[];
  verifyUrl?: string;
  redirect?: {
    native?: string;
    universal?: string;
  };
}

Find the complete type definition of the session object here.