WalletConnect

The WalletConnectConnector uses WalletConnect v2 by default and wraps the WalletConnect Ethereum Provider and supports its configuration options. This is a great option for adding support for many wallets to your app.

import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'

Usage

To get started with Wallet Connect v2, you will need to retrieve a Project ID. You can find your Project ID here.

import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'
 
const connector = new WalletConnectConnector({
  options: {
    projectId: '...',
  },
})

Configuration

chains (optional)

Chains supported by app. Defaults to defaultChains.

import { mainnet, optimism, polygon } from 'wagmi/chains'
import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'
 
const connector = new WalletConnectConnector({
  chains: [mainnet, optimism, polygon],
  options: {
    projectId: '...',
  },
})

The above example is using chains from wagmi/chains.
Upon connection, the connector will connect to the previously connected chain unless otherwise specified by a chainId config on useConnect.

options

projectId

WalletConnect Cloud Project ID. You can find your Project ID here.

import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'
 
const connector = new WalletConnectConnector({
  options: {
    projectId: '...',
  },
})

isNewChainsStale (optional)

Determines whether or not new chains added to chains should be considered as stale. Defaults to true.

import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'
 
const connector = new WalletConnectConnector({
  options: {
    projectId: '...',
    isNewChainsStale: false,
  },
})

What is a stale chain & what does this flag do?

If a new chain is added to your previously existing chains, this flag will determine if that chain should be considered as stale. A stale chain is a chain that WalletConnect has yet to establish a relationship with (ie. the user has not approved or rejected the chain).

Preface: Whereas WalletConnect v1 supported dynamic chain switching, WalletConnect v2 requires the user to pre-approve a set of chains up-front. This comes with consequent UX nuances (see below) when a user tries to switch to a chain that they have not approved.

This flag mainly affects the behavior when a wallet does not support dynamic chain authorization with WalletConnect v2.

If true (default), the new chain will be treated as a stale chain. If the user has yet to establish a relationship (approved/rejected) with this chain in their WalletConnect session, the connector will disconnect upon the dapp auto-connecting, and the user will have to reconnect to the dapp (revalidate the chain) in order to approve the newly added chain. This is the default behavior to avoid an unexpected error upon switching chains which may be a confusing user experience (ie. the user will not know they have to reconnect unless the dapp handles these types of errors).

If false, the new chain will be treated as a validated chain. This means that if the user has yet to establish a relationship with the chain in their WalletConnect session, wagmi will successfully auto-connect the user. This comes with the trade-off that the connector will throw an error when attempting to switch to the unapproved chain. This may be useful in cases where a dapp constantly modifies their configured chains, and they do not want to disconnect the user upon auto-connecting. If the user decides to switch to the unapproved chain, it is important that the dapp handles this error and prompts the user to reconnect to the dapp in order to approve the newly added chain.

metadata (optional)

Metadata for your app. See more

import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'
 
const connector = new WalletConnectConnector({
  options: {
    projectId: '...',
    metadata: {
      name: 'wagmi',
      description: 'my wagmi app',
      url: 'https://wagmi.sh',
      icons: ['https://wagmi.sh/icon.png'],
    },
  },
})

showQrModal (optional)

Whether or not to show the QR Code Modal upon connection. See more. Defaults to true.

import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'
 
const connector = new WalletConnectConnector({
  options: {
    projectId: '...',
    showQrModal: false,
  },
})

Safe WalletConnect Legacy