WalletConnect is an open protocol that lets a dapp (running in your browser or on desktop) talk to a wallet (usually on your phone) without the wallet being installed on the same device.

You’ve probably seen it: a dapp shows a QR code, you open your mobile wallet, scan it, and suddenly the dapp knows your address and can ask you to sign transactions. That’s WalletConnect.

The Problem It Solves#

Before WalletConnect, your options for connecting a wallet to a dapp were limited:

• Browser extension wallet (MetaMask, Rabby): works only in the browser where it’s installed. No good if you’re on a different machine, or if you prefer a mobile wallet.
• Custodial wallet accounts: you’d trust an exchange or service with your keys. Not really self-custody.
• Hardware wallets: required a browser extension or native app to bridge them.

If your wallet was on your phone (Trust Wallet, Rainbow, MetaMask Mobile, Ledger Live) and the dapp was on your laptop, there was no clean way to connect them. WalletConnect fixed that.

Why Use It#

Phone as a hardware wallet#

Your phone is already a decent security device — it has a secure enclave, biometrics, and is usually kept close. WalletConnect lets your phone act like a hardware wallet for dapps running on any other device. Keys never leave your phone.

Works across devices#

You can sit at any computer, open a dapp, scan a QR code, and sign transactions from your phone. The laptop never sees your private key.

Wallet-agnostic#

WalletConnect is an open protocol, not a single wallet. Over 300 wallets support it — MetaMask, Rainbow, Trust, Safe, Ledger Live, Rabby Mobile, and so on. As a dapp developer, you implement WalletConnect once and support all of them.

Supports smart contract wallets#

Safe and other smart contract wallets use WalletConnect to connect to dapps. This is how you use a Safe on OpenSea or Uniswap — the dapp talks to the Safe app via WalletConnect.

How It Works#

The core idea: WalletConnect is a relay protocol. The dapp and wallet never talk to each other directly. They both connect to a relay server, exchange encrypted messages through it, and the relay just shuffles bytes back and forth without being able to read them.

Here’s the flow in more detail.

1. The dapp generates a URI#

When you click “Connect Wallet” and pick WalletConnect, the dapp generates a URI that looks something like:

wc:abc123...@2?relay-protocol=irn&symKey=def456...

This URI contains:

• A topic (abc123...) — a unique session identifier.
• A symmetric encryption key (symKey) — used to encrypt/decrypt all messages in this session.
• The relay protocol to use.

This URI is shown to you as a QR code, or as a deep link if you’re on mobile.

2. The wallet scans/opens it#

You open your wallet app and scan the QR code (or tap the deep link). The wallet now has the topic and the symmetric key. Both the dapp and the wallet know the same secret.

3. Both subscribe to the relay#

Both the dapp and the wallet open a WebSocket connection to the WalletConnect relay server and subscribe to the topic. Any message published on that topic gets forwarded to both of them.

Because both sides share the symmetric key, they can encrypt messages before sending and decrypt after receiving. The relay only sees encrypted blobs.

4. The wallet approves the session#

The wallet prompts you: “Dapp X wants to connect. It’s requesting these permissions on these chains.” You approve, and the wallet sends back an encrypted response with your address and the chains you’ve approved.

The dapp now knows your address and the session is live.

5. Signing transactions#

When the dapp needs a signature (e.g., to send a transaction or sign a message):

1. The dapp encrypts a request like eth_sendTransaction with the session key and publishes it to the topic.
2. The wallet receives it, decrypts it, shows you a prompt.
3. You approve on your phone. The wallet signs with your private key.
4. The wallet encrypts the signed transaction and sends it back through the relay.
5. The dapp receives it, decrypts it, and broadcasts the transaction on-chain (or uses the signature however it needs).

Your private key never leaves your phone. The laptop just receives a signature.

What the Relay Can and Can’t See#

A common concern: “if there’s a relay server in the middle, can they spy on me?”

• Can see: that a session exists on a given topic, when messages are sent, and encrypted payload sizes.
• Can’t see: your address, the transaction contents, or the signatures. Everything is encrypted with a key the relay never has.

WalletConnect is end-to-end encrypted between dapp and wallet. The relay is untrusted infrastructure.

WalletConnect v1 vs v2#

v1 was the original spec — one session per QR code, one chain per session, one dapp at a time.

v2 is the current version and is much more flexible:

• Multi-chain sessions: one connection can cover Ethereum, Arbitrum, Optimism, etc. at the same time.
• Multi-session: a wallet can have many active dapp connections.
• Persistent sessions: sessions survive app restarts and reconnects.
• Namespaces: the protocol generalizes beyond EVM — Cosmos, Solana, and other chains can use the same flow.

v1 is deprecated. If you’re building today, use v2.

When You’d Use It as a User#

• You use a mobile wallet (Rainbow, Trust, etc.) but want to use dapps on your laptop.
• You have a Safe and want to connect it to a dapp — Safe uses WalletConnect as the bridge.
• You want to sign on a device that isn’t running a browser extension (e.g., Ledger Live on desktop connecting to a dapp on another machine).

When You’d Use It as a Developer#

Basically always, if you’re building a dapp. Most apps use a wrapper like RainbowKit, ConnectKit, or Web3Modal that bundles WalletConnect alongside MetaMask-style injected connections. Users click “Connect,” pick their wallet, and the library handles the rest.

Summary#

WalletConnect essentially turns “which wallet do I have installed on this computer?” into “which wallet do I own, anywhere?” — and that’s a big unlock for self-custody.

This blog post was written with the help of Claude.