Skip to main content

Integration Checklist

To ensure a smooth integration process, we strongly recommend conducting internal testing of the WalletConnect v2.0 experience to ensure seamless UX.

Example Dapp​

Our primary example of a WalletConnect v2.0 dapp is linked here. This uses Web3Modal v2.0 + wagmi and supports the following methods:

  • eth_sendTransaction
  • eth_signTransaction
  • personal_sign
  • eth_sign (standard)
  • eth_signTypedData
  • connect
  • disconnect

The source code for this WalletConnect v2.0 dapp is here.

Required and Optional Namespaces and Methods​

With V2, we allow for specific chains or methods to be specified as required or optional via session namespaces. If you are looking to configure specific chains or methods for your session, please refer to these respective guidance on the ethereum provider:

Required and Optional Chains Required and Optional Methods

Testing​

Please test your dapp's WalletConnect v2.0 integration with as wide a range of wallets as possible to ensure a correct implementation that follows a similar flow to our aforementioned example dapp. Wallets that you can test with include:

  1. Web3Wallet example wallet (Link)
  2. Alpha Wallet (iOS) (Android)
  3. Trust (iOS) (Android)
  4. Zerion (iOS) (Android)

Common Errors and Fixes​

There are several warnings and errors dapp developers may face when integrating with certain libraries during the V2 migration.

Failed to execute 'postMessage' on 'DOMWindow': the target origin provided ('https://verify.walletconnect.com)' does not match the recipient window's origin (XXX). This can be ignored until your dapp is ready to be in production. We have a service called Verify API which has been implemented to verify domains and prevent malicious site. When ready to verify your domain:

  1. Go to https://cloud.walletconnect.com/sign-in
  2. Access your project with the associated projectID
  3. Submit your dapp project in the Explorer tab
  4. Once submitted in your Settings you will see a next verification code
  5. Follow the instructions to map your DNS record. This allows Verify API to ensure you are the rightful domain owner.
  6. Allows 48-72 hours for the DNS to propagate.

Uncaught (in promise) Error: no matching key.history: XXXXX This can be resolved by clearing local storage cache and refreshing. This is should no longer be appearing in our next release.

Missing or invalid. request() method: eth_call or Missing or invalid. request() method: eth_getBalance This error was fixed and relevant to those using < wagmi v0.12.16 and ethers 5.7.2. It usually occurs when getting balance through the provider or useContract wagmi hook. Please upgrade to ^v0.12.16in order to resolve this error.

If you are still facing issues with the above or different issues, feel free to search our GitHub Discussions or file a ticket here

Testing Process​

We highly recommend testing with ALL of the above wallets.

Please follow these steps:

  • Have your dapp deployment open + show the QR code
  • Scan with the respective wallet
  • Approve the methods
  • Test with the methods that your dapp uses (i.e. eth_sendTransaction)
  • Successful connect - disconnect experience

Testing Resources​

We have created a sample QA Testing Rubric Guide here.

We also have a list of example wallets and dapps on the Awesome WalletConnect page. You can use the resources here to test your WalletConnect v2.0 integration!

Below are screenshots that show testing our Web3Wallet SDK example wallet against our WalletConnect v2.0 example dapp.

session-request-example

The above shows scanning the example dapp from the example wallet.

session-request-example

The above shows a preview of the eth methods your dapp may use.

Done with Your Integration?​

Once you feel confident with the QA process, please check out the explorer submission process to add your dapp to the WalletConnect Explorer.