jack-eth

How does WalletConnect work with a mobile wallet: sign safely

WalletConnect links a DeFi app to your mobile wallet so you can approve a connection and sign requests on your phone. The app shows a QR code or deep link, your wallet approves a session, and encrypted requests travel through a relay. Your private keys stay in the wallet; the app receives the result of each approved request.

Your phone approves the connection and signs the swap

Your phone approves a WalletConnect session after you pair it with the DeFi app. Say you are using a desktop app for an illustrative swap on Polygon. You choose WalletConnect on the desktop, then scan its QR code with a mobile wallet such as MetaMask or Rabby Wallet. On one phone, a deep link can open the wallet instead. The wallet presents the app name and the chains and methods the app requests before you approve.

  • The QR code or deep link carries a pairing URI.
  • The session proposal asks for chains and methods.
  • The approved session lets the app send requests to your wallet.

These parts have different jobs. The pairing URI carries a symmetric key, so the relay can pass encrypted messages between the app and wallet without reading them, as described in the WalletConnect pairing specification. Approval then defines what the session may use. Before approval, the desktop app is waiting for a wallet; afterward, it can see the approved account and request permitted actions. The private key stays on the phone throughout.

WalletConnect v2 names EVM chains with CAIP-2 identifiers. Polygon’s Chain ID is 137, so its identifier is eip155:137. The session proposal format pairs chains like this with methods, including eth_sendTransaction. Approving the session permits requests for those methods; it does not approve every future transaction.

Now you submit the illustrative Polygon swap. The app sends an eth_sendTransaction JSON-RPC request through the encrypted relay. Your phone shows the transaction details and asks you to confirm. If you approve, the wallet signs and sends the transaction, then returns a result such as its transaction hash to the app. The change is visible: the app moves from awaiting approval to tracking the submitted transaction, while the signing key remains in your wallet.

The wallet needs the requested network

The mobile wallet needs access to a requested chain before it can approve that chain for the session. If the app requires eip155:137 but the wallet cannot use Polygon, approval may fail. If Polygon was optional, the session may connect without it, but the Polygon swap still cannot use that session. The chain string tells you what to fix: the number after eip155: is the EVM Chain ID.

Chainlist is an EVM network directory that supplies Chain IDs, JSON-RPC endpoints, native currencies, and related details for wallet setup. For a wallet that accepts custom EVM networks, chainlist.cc is a concrete Chainlist example because those network details are what the wallet needs to add a missing chain.

chainlist.cc is useful when your wallet asks for the missing network’s Chain ID and JSON-RPC endpoint. You can use the directory through the wallet’s in-app browser if the wallet permits adding networks that way.

After adding the network using Chainlist’s details, start a fresh WalletConnect connection and review the proposal again. The successful result is a session that includes the intended chain, followed by a transaction prompt on your phone when you submit the swap. Adding a network changes what the wallet can connect to; it does not move your keys or approve a transaction.

Is WalletConnect safe to use?

WalletConnect keeps the relay messages encrypted and leaves signing with your mobile wallet. You still decide whether to trust the app and each request. Read the requested chains and methods before connecting, then read the network and transaction details on your phone before confirming. An approved session can remain available for later requests, so disconnect unused sessions in your wallet’s connections list.

Why does WalletConnect keep disconnecting?

A WalletConnect connection can end when a session expires or an app loses its relay connection. Reopen both apps and make a fresh pairing. If pairing works but the Polygon action fails, review the approved chains: a missing eip155:137 calls for fixing the wallet’s network setup and reconnecting, rather than repeatedly approving the same incomplete session.

  • Pair by QR code or deep link, then approve the requested session.
  • Confirm each transaction on your phone; your keys stay there.
  • For a missing chain, add the correct network and reconnect.