WalletConnect v2 Explained: How It Works and Why It Replaced v1
A clear explanation of how WalletConnect v2 works, what changed from v1, and what developers need to know to implement it correctly in their dApps.
If you have ever connected a mobile wallet to a desktop dApp by scanning a QR code, you used WalletConnect. It is the dominant open protocol for bridging wallets to dApps across devices and ecosystems — but it is also frequently integrated poorly, leading to connection failures, broken mobile flows, and confusing error states. Understanding how the protocol actually works makes it significantly easier to integrate correctly.
What WalletConnect Is
WalletConnect is an open protocol that establishes an encrypted communication channel between a dApp and a wallet. Neither party directly calls the other — instead, they both connect to a relay server that passes signed, encrypted messages between them.
This relay architecture is what makes cross-device connections possible. The dApp is running in a browser on a laptop. The wallet is an app on a phone. They cannot communicate directly. The relay provides the transport layer, and end-to-end encryption ensures the relay cannot read the messages it forwards.
WalletConnect is not a wallet itself. It is a communication protocol that any wallet can implement. MetaMask, Coinbase Wallet, Rainbow, Trust Wallet, and hundreds of other wallets support it, which is why dApps that support WalletConnect can reach nearly any wallet a user might have.
How the Connection Is Established
QR Code Flow (Desktop dApp to Mobile Wallet)
- The dApp generates a connection URI that encodes the relay server endpoint, a symmetric encryption key, and a session topic identifier.
- The URI is encoded as a QR code displayed in the dApp's connect modal.
- The user scans the QR code with their mobile wallet app.
- The wallet decodes the URI, connects to the relay server on the same topic, and sends a session proposal.
- The dApp receives the proposal, the user approves it in the wallet, and a session is established.
All messages from this point forward are encrypted with the shared key exchanged during the connection handshake. The relay server only sees encrypted blobs.
Deep Link Flow (Mobile Browser to Mobile Wallet)
When the user is already on mobile, there is no QR code to scan. Instead, the connection URI is encoded as a deep link that opens the user's wallet app directly. The wallet decodes the URI, establishes the relay connection, and returns the user to the browser via another deep link.
This flow is the correct default for mobile browsers and is what most users on mobile expect. Showing a QR code to a mobile user is a UX dead end — they cannot scan their own screen.
What Changed from v1 to v2
WalletConnect v1 was shut down in 2023. If you are still using v1 endpoints, your integration is broken for any user whose wallet has migrated. Here is what changed:
Multi-chain support. v1 was chain-specific — a session connected to a single chain. v2 supports multiple chains in a single session, which aligns with how users actually operate in a multi-chain ecosystem.
Multi-account support. v1 exposed one account per connection. v2 supports multiple accounts across multiple chains in one session, with the wallet deciding which accounts to expose.
Sign API standardization. v2 introduced the Sign API, which standardizes how signing requests and responses are structured. This replaces the ad-hoc method handling in v1 and makes wallet compatibility more predictable.
New relay infrastructure. The relay servers changed. v1 used bridge.walletconnect.org; v2 uses relay.walletconnect.com. Projects must register at cloud.walletconnect.com and use a project ID. Without a valid project ID, connections will fail or be rate-limited.
Pairing and session separation. v2 separates the concept of a pairing (the underlying connection between the two clients) from a session (an application-specific context on top of that pairing). One pairing can support multiple sessions, enabling features like wallet-to-wallet communication and multi-app connections.
Common Integration Issues
Rate limiting due to shared project IDs. Every dApp integration must use a project ID registered to your project at cloud.walletconnect.com. Example IDs from tutorials, forked repos, or libraries will rate-limit in production.
Mobile deep link not triggering the wallet app. This usually means the deep link format is wrong for the target platform, or the wallet app does not have the WalletConnect URI scheme registered. Test with actual physical devices across iOS and Android — simulators handle deep links differently.
Session not persisting after page reload. v2 sessions are persisted in localStorage by the SDK. Ensure nothing in your app clears localStorage on navigation. Also ensure your CSP headers do not block the localStorage access pattern used by the SDK.
Wrong namespace configuration. When requesting a session, the dApp specifies required and optional namespaces — which chains and methods it needs access to. If the wallet does not support the requested namespace, the connection will fail. Be conservative: only require what you genuinely need and make everything else optional.
Event listeners not cleaned up. The WalletConnect SDK emits events for session updates, account changes, and disconnection. If you do not clean up these listeners when components unmount (in React, in the useEffect cleanup function), you will accumulate duplicate handlers and see events handled multiple times.
Using WalletConnect in Practice
Most developers interact with WalletConnect through a higher-level abstraction rather than the raw SDK. Wagmi v2's WagmiProvider and RainbowKit both use the WalletConnect SDK under the hood and handle the relay connection, session persistence, and event management for you.
If you are integrating at a lower level — for example, adding WalletConnect support to a non-React frontend or a native mobile app — use the official @walletconnect/sign-client SDK and follow the setup guide at docs.walletconnect.com for your platform.
WalletConnect integration is straightforward when done correctly and a significant source of user-facing bugs when done hastily. If your team needs a solid wallet integration built and tested across wallets and devices, Start a build with Clixo.