Skip to main content

Ethereum Provider

info

Web3Modal SDK v3 is out! Learn how to integrate it here

EIP-1193 compliant Provider for WalletConnect v2. You can use this on it's own or pass down to libraries like ethers, viem, web3js and others.

Installation​

npm install @walletconnect/ethereum-provider @walletconnect/modal

Initialization​

import { EthereumProvider } from '@walletconnect/ethereum-provider'

const provider = await EthereumProvider.init({
  projectId, // REQUIRED your projectId
  showQrModal, // REQUIRED set to "true" to use @walletconnect/modal

  /* Optional Namespaces - RECOMMENDED FOR MULTI-CHAIN APPS */
  optionalChains, // chains - required for optional namespaces
  optionalMethods, // ethereum methods - all ethereum methods are already set by default so this is not required
  optionalEvents, // ethereum events - all ethereum events are already set by default so this is not required

  /* Required Namespaces - NOT RECOMMENDED FOR MULTI-CHAIN APPS*/
  chains, //  chain ids
  methods, // ethereum methods
  events, // ethereum events

  rpcMap, // OPTIONAL rpc urls for each chain
  metadata, // OPTIONAL metadata of your app
  qrModalOptions // OPTIONAL - `undefined` by default, see https://docs.walletconnect.com/web3modal/options
})

Use with WalletConnectModal​

When showQrModal is enabled and @walletconnect/modal package is installed, ethereum provider will automatically show and hide WalletConnectModal. You can also pass all relevant modal options under qrModalOptions. See WalletConnectModal options for all available fields.

Use without WalletConnectModal​

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

provider.on('display_uri', (uri: string) => {
  // ... custom logic
})

await provider.connect()
// or
await provider.enable()

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 disconnect
provider.on('disconnect', handler)

Required and Optional Chains​

With Ethereum Provider, the package passed the required chains through chains and if your dapp wants to provide other optionalNamespaces this is passed through optionalChains.

Example code can be found here and further documentation on namespaces can be found in this spec.

The example below specifies Ethereum Mainnet (chainId 1) as a required chain via chains, and Ethereum Goerli (chainId 5) as an optional chain via optionalChains.

await EthereumProvider.init({
  projectId: process.env.TEST_PROJECT_ID,
  chains: [1], // chains added to required namespaces
  optionalChains: [5] // chains added to optional namespaces
  ...
})

Another example of those that want to pass several optional chains:

await EthereumProvider.init({
  projectId: process.env.TEST_PROJECT_ID,
  chains: [1], // chains added to required namespaces
  optionalChains: [5, 56, 137, 10, 100] // chains added to optional namespaces
  ...
})

Required and Optional Methods​

By default, EthereumProvider specifies eth_sendTransaction and personal_sign as required methods. For those that want to request additional methods for the session, we recommend passing these through optionalMethods. The default behaviour for the required methods can also be overridden by specifying the methods option directly.

For more information of the source code, please refer to here. This optional passing is them consumed in our Sign Client here.

await EthereumProvider.init({
  projectId: process.env.TEST_PROJECT_ID,
  chains: [1],
  optionalChains,
  optionalMethods: ['eth_signTypedData', 'eth_signTypedData_v4', 'eth_sign'],
  ...
})