Skip to main content

Dapps

The following steps describe the various steps necessary for dapps to migrate to WalletConnect v2.0.

  1. Getting Started
  2. Testing Your Integration
  3. Submitting Your Dapp to the WalletConnect Explorer

Getting Started​

In order to get started, we recommend identifying which library your dapp utilizes. If none of your approaches are listed, feel free to reach out to us via GitHub Discussions here.

  1. web3-provider
  2. ethereum-provider
  3. Web3Modal v1.0
  4. Web3Modal v2.0
  5. react-native-dapp
  6. web3-onboard
  7. Dynamic
  8. solana-labs/wallet-adapter
  9. web3-react
  10. ConnectKit
  11. wagmi
  12. RainbowKit
  13. Privy

web3-provider​

If you are using @walletconnect/web3-provider, we stopped supporting this provider in favor of the improved version published under @walletconnect/ethereum-provider and you will be able to check the latest version on NPM here.

ethereum-provider​

caution

For usage with Typescript, make sure you are using Typescript version 5.0.0 or higher.

  • Ensure you have a projectId from the WalletConnect Cloud. You can get one here.
  • Upgrade @walletconnect/ethereum-provider from 1.x.x to 2.x.x.

Previously, you would have passed in an infuraId like:

import WalletConnectProvider from '@walletconnect/ethereum-provider'

const web3Provider = new WalletConnectProvider({
  infuraId: 'INFURA_ID'
})

The new implementation requires projectId and chains instead. Here is an example of the new initialization:

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

const provider = await EthereumProvider.init({
  projectId: 'WALLETCONNECT_PROJECT_ID', // required
  chains: [1], // required
  showQrModal: true // requires @walletconnect/modal
})
  • Install @walletconnect/modal if you want to use the QR Code modal. You can find more information about WalletConnectModal here.

Web3Modal v1.0​

We recommend that you replace your existing integration with the latest version of Web3Modal by following one of these paths:

  • Web3Modal: Web3modal feature rich modal with wagmi, has WalletConnect, extension wallets, connectors, chain switching, account modal and more.
  • WalletConnectModal: WalletConnectModal is a lightweight modal to add into your existing workflows.

Web3Modal v2.0​

If you are using our redesigned Web3Modal (often referred to as Web3Modal v2.0), you are ready to go. Please ensure that you are using a minimum version of 2.6.0. Here is a code example:

import { w3mConnectors, w3mProvider } from '@web3modal/ethereum'
import { createConfig } from 'wagmi'

// ...
const { publicClient } = configureChains(chains, [w3mProvider({ projectId })])

const config = createConfig({
  autoConnect: true,
  connectors: [
    w3mConnectors({
      projectId,
      chains
    })
  ],
  publicClient
})

const ethereumClient = new EthereumClient(config, chains)
// ...

For more documentation, follow the docs for Web3Modal here.

react-native-dapp​

We are currently developing our new SDK @walletconnect/modal-react-native, which is now available in release-candidate version.

To ensure a seamless transition, we have developed a comprehensive example here that simplifies the migration process.

Follow this steps along with the migration example:

  1. Remove @walletconnect/react-native-dapp and all it's implementation
  2. Remove crypto polyfill and rn-nodeify logic (if present)
  3. Install new packages: yarn add @walletconnect/modal-react-native react-native-get-random-values react-native-modal react-native-svg @react-native-async-storage/async-storage @react-native-community/netinfo
  4. If the project uses react native < 0.70, install big-integer and add BigInt polyfill
  5. Run pod install in /ios

You can also find detailed documentation on how to install & utilize the new SDK here.

The latest SDK introduces a powerful combination of Universal Provider and our Cloud Explorer API. This integration forms the solid foundation for a React Native dapp to effortlessly connect with wallets."

If you need assistance at any point during the migration process, please feel free to reach out to us via GitHub Discussions.

web3-onboard​

If you are using the WalletConnect package with Blocknative's web3-onboard, the migration is straightforward. The latest WalletConnect package is backwards-compatible (until the WalletConnect v1.0 shutdown comes into effect). When you are ready to transition, bump the @web3-onboard/walletconnect package version to >= 2.3.0 and adjust the initialization params:

const walletConnect = walletConnectModule({
  version: 2, // **New Param** Defaults to version: 1 - this behavior will be deprecated after the WalletConnect v1 sunset
  handleUri: uri => console.log(uri),
  projectId: '', // ***New Param* Project ID associated with [WalletConnect account](https://cloud.walletconnect.com)
  requiredChains: [1, 56] // chains required to be supported by WC wallet
})

// for optional chains/optionalNamespaces
const onboard = Onboard({
  wallets: [walletConnect],
  chains: [
    // chains that are passed as optional chains to WC wallet after cleaning and parsing as number[]
    {
      id: '0x89',
      token: 'MATIC',
      label: 'Polygon',
      rpcUrl: 'https://matic-mainnet.chainstacklabs.com'
    }
    // ...
  ]
})

Note: The @web3-onboard/walletconnect package will default to version 1 until the WalletConnect v1 sunset is complete

Dynamic​

Switching to WalletConnect v2.0 is straightforward using Dynamic. To upgrade, ensure you are using v0.15 or later for @dynamic-labs/sdk-react. Once set up, visit your Dynamic developer dashboard and head to the integrations page. Select the WalletConnect card, toggle v2.0 on and add your WalletConnect project ID. Once enabled, Dynamic will automatically use WalletConnect v2.0 for wallets that support it, and v1.0 for wallets that don’t.

solana-labs/wallet-adapter​

If you are using solana-labs/wallet-adapter, this is already working on WalletConnect v2.0, so there is nothing to change here. There will be a new version released with an updated UI modal shortly.

web3-react​

web3-react has created their own modules for WalletConnect v2.0. You can test their playground here and read their example implementation here. In order to get started with the migration, we suggest upgrading your @web3-react/types, @web3-react/store and @web3-react/core as well as installing @web3-react/walletconnect-v2.

After you have the respective packages, you will have to obtain a projectId from the WalletConnect Cloud and add it your .env file.

You will need to then initialize WalletConnect v2.0 as a connector as referenced here.

import { initializeConnector } from '@web3-react/core'
import { WalletConnect as WalletConnectV2 } from '@web3-react/walletconnect-v2'

import { MAINNET_CHAINS } from '../chains'

const [mainnet, ...optionalChains] = Object.keys(MAINNET_CHAINS).map(Number)

export const [walletConnectV2, hooks] = initializeConnector<WalletConnectV2>(
  actions =>
    new WalletConnectV2({
      actions,
      options: {
        projectId: process.env.walletConnectProjectId,
        chains: [mainnet],
        optionalChains,
        showQrModal: true
      }
    })
)

Note: Be sure to test with several chains in order to complete your implementation of WalletConnect v2.0.

Then use the @web3-react/walletconnect-v2 package with the following methods in your components.

  • URIListener: Event listener for when v2 URI is created. Code reference here.
  • activate: Create a session pairing with WalletConnect v2. Code reference here.
  • deactivate: Disconnect your session from your wallet. Code reference here.
  • connectEagerly: Connect to v2 protocol on mount. Code reference here.

Sample codes of reference can be found in:

ConnectKit​

To migrate to WalletConnect v2.0 using ConnectKit, you need to upgrade connectkit and wagmi to the latest version.

caution

WalletConnect V2 is only supported in ConnectKit v1.3.0 and above

info

For version 1.4.0 and above, you need to remove ethers and install viem instead.

yarn remove ethers
yarn add wagmi@latest viem@latest

Run the following command to install it using Yarn:

yarn add connectkit@^latest wagmi@^latest

WalletConnect v2.0 requires a projectId to be set and included in the configuration. You can easily get a projectId by creating an account on the WalletConnect Cloud.

Create a new environment variable WALLETCONNECT_PROJECT_ID in your .env file and set it to your projectId.

WALLETCONNECT_PROJECT_ID=YOUR_PROJECT_ID

Next, update your code by including the walletConnectProjectId inside the config object for getDefaultClient:

...
const client = createClient(
  getDefaultClient({
    ...
+    walletConnectProjectId: process.env.WALLETCONNECT_PROJECT_ID,
    ...
  }),
);
...

Note:

  • For a version specific upgrade, refer to the official migration guide from Family.
  • When customizing your configuration for advanced usage, it is important to include the projectId within your WalletConnectConnector object. You can learn more about it here.
  • Make sure you have compatible versions of ethers and viem. Check your project's dependencies to ensure compatibility with ConnectKit.

For a comprehensive example, refer to the provided sample code:

wagmi​

To migrate to WalletConnect v2.0 using wagmi, you need to upgrade wagmi to either 0.12.16 if you are using ethers or 1.x.x if you are using viem.

caution

WalletConnect v2.0 is only supported in wagmi 0.12.8 and above.

Upgrading to wagmi 0.12.16​

Run the following command to install it using Yarn:

yarn add wagmi@^0.12.16

WalletConnect v2.0 requires a projectId to be set and included in the configuration. You can easily get a projectId by creating an account on the WalletConnect Cloud.

Create a new environment variable WALLETCONNECT_PROJECT_ID in your .env file and set it to your projectId.

WALLETCONNECT_PROJECT_ID=YOUR_PROJECT_ID

Next, update your code by including the walletConnectProjectId inside the config object for WalletConnectConnector:

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

const connector = new WalletConnectConnector({
  options: {
    projectId: process.env.WALLETCONNECT_PROJECT_ID,
    showQrModal: true
  }
})

const client = createClient({
  autoConnect: true,
  provider,
  connectors: [connector],
});

...

Upgrading to wagmi 1.x.x​

wagmi 1.x.x drops support for ethers and only supports viem. If you are using ethers, you will need to migrate to viem before upgrading to wagmi 1.x.x.

yarn remove ethers
yarn add wagmi viem@latest

WalletConnect v2.0 requires a projectId to be set and included in the configuration. You can easily get a projectId by creating an account on the WalletConnect Cloud.

Create a new environment variable WALLETCONNECT_PROJECT_ID in your .env file and set it to your projectId.

WALLETCONNECT_PROJECT_ID=YOUR_PROJECT_ID

Next, update your code by including the walletConnectProjectId inside the config object for WalletConnectConnector:

import { createConfig, configureChains, mainnet } from 'wagmi'
import { publicProvider } from 'wagmi/providers/public'
import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'

const { chains, publicClient } = configureChains([mainnet], [publicProvider()])

const connector = new WalletConnectConnector({
  chains,
  options: {
    projectId: process.env.WALLETCONNECT_PROJECT_ID,
  },
}),

const config = createConfig({
  connectors: [connector],
  publicClient,
})

...

wagmi 1.x.x introduces several breaking changes due to the migration from ethers to viem. For a version-specific upgrade, refer to:

RainbowKit​

If you've already adopted RainbowKit 0.12.x and 1.0.x, then you're almost there! Just upgrade to the latest RainbowKit patch release and give it a try. RainbowKit has been API compatible with WalletConnect v2 since 0.12.8 was released in April.

RainbowKit has enabled WalletConnect v2 by default with 0.12.15 and 1.0.2. RainbowKit will continue to support 0.12.x in case your dApp has not yet upgraded to Wagmi and RainbowKit v1.

1. Upgrading dependencies

npm i @rainbow-me/rainbowkit@^1.0.2 wagmi@^1.2

If you're using a version of RainbowKit before 0.12.x or 1.0.x, just follow the Migration Guides to get up-to-date.

It is recommended that 0.12.x dApps also begin to upgrade wagmi, as improvements to WalletConnect v2 will only be included in future versions of wagmi.

2. Supplying a projectId

Every dApp that relies on WalletConnect now needs to obtain a projectId from WalletConnect Cloud. This is absolutely free and only takes a few minutes.

Supply your projectId to getDefaultWallets and individual RainbowKit wallet connectors like the following:

const projectId = 'YOUR_PROJECT_ID'
const { wallets } = getDefaultWallets({
  appName: 'My RainbowKit App',
  projectId,
  chains
})
const connectors = connectorsForWallets([
  ...wallets,
  {
    groupName: 'Other',
    wallets: [
      argentWallet({ projectId, chains }),
      trustWallet({ projectId, chains }),
      ledgerWallet({ projectId, chains })
    ]
  }
])

RainbowKit is type-safe and will warn you when a projectId is missing. Refer to RainbowKits' examples to see v2 in action:

Privy​

To upgrade Privy to use WalletConnect v2.0, the only thing you need to do is install the latest version of the Privy SDK:

npm i @privy-io/react-auth@latest

That's it! You've upgraded to WalletConnect v2.0.

Optional​

If you want to configure your own WalletConnect Cloud Project instead of using the default one provided by Privy, proceed to the following steps. This is optional.

1. Get a WalletConnect Cloud Project ID​

Go to WalletConnect Cloud and create a new account. Once your account is created, create a new project and collect the Project ID.

2. Configure your Project ID in the PrivyProvider​

In the config property of your PrivyProvider, add a walletConnectCloudProjectId with your project ID from step 1.

Example configuration of Privy with WalletConnect v2.0 in NextJS
import type { AppProps } from 'next/app'
import Head from 'next/head'
import { PrivyProvider } from '@privy-io/react-auth'

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <PrivyProvider
      appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID || ''}
      config={{
        walletConnectCloudProjectId: 'YOUR_WALLETCONNECT_CLOUD_PROJECT_ID'
      }}
    >
      <Component {...pageProps} />
    </PrivyProvider>
  )
}

For more information:​