Integrate WalletConnect v2 into dApps with wagmi and Web3Modal

WalletConnect v2 connects mobile wallets to decentralized applications via relay servers. But session expiry, unreliable network switching, and missing fallbacks cause constant loading screens. On Trust Wallet and Coinbase Wallet, wallet_switchEthereumChain often fails—the network changes only after manual confirmation, and without a fallback, the app freezes. According to WalletConnect Docs, sessions live 7 days, but without proper recovery, users rescan the QR code. Statistics show ~30% of mobile wallet users lose session after page reload—hurting conversion and retention.

We use wagmi v2 with Web3Modal. This abstraction over the WalletConnect SDK provides a unified API for all wallets, tripling development speed versus raw SDK integration. It handles edge cases: network switching via wallet_addEthereumChain, session recovery, and deep-link support for mobile browsers. Budget savings hit 40%.

Step‑by‑step integration

1. Register project on WalletConnect Cloud to get a projectId. This public key is mandatory in production—without it, relay servers enforce rate limits (up to 50 req/s on the free tier).
2. Install packages: npm install @web3modal/wagmi wagmi viem.
3. Configure wagmi with required chains (mainnet, polygon, arbitrum) and connectors: injected, walletConnect, coinbaseWallet.

// config.ts import { createConfig, http } from 'wagmi' import { mainnet, polygon, arbitrum } from 'wagmi/chains' import { walletConnect, injected, coinbaseWallet } from 'wagmi/connectors' export const config = createConfig({ chains: [mainnet, polygon, arbitrum], connectors: [ injected(), walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID! }), coinbaseWallet({ appName: 'Your App' }), ], transports: { [mainnet.id]: http(), [polygon.id]: http(), [arbitrum.id]: http(), }, }) 

Why session recovery matters

WalletConnect sessions live 7 days and are stored in localStorage. When a user closes the tab and returns, wagmi auto‑restores the connection—no new QR. We initialize WagmiProvider before any hooks to avoid hydration issues. Without recovery, up to 25% of users abandon the dApp after reload—critical for DeFi protocols requiring continuity.

// app/providers.tsx 'use client' import { WagmiProvider } from 'wagmi' import { QueryClient, QueryClientProvider } from '@tanstack/react-query' import { config } from './config' const queryClient = new QueryClient() export function Providers({ children }: { children: React.ReactNode }) { return ( <WagmiProvider config={config}> <QueryClientProvider client={queryClient}> {children} </QueryClientProvider> </WagmiProvider> ) } 

Network switching without bugs

wallet_switchEthereumChain behaves differently per wallet. MetaMask Mobile shows a popup, Trust Wallet switches automatically, and some ignore it if the chain isn't added. We add a fallback: if switchChain fails, we call wallet_addEthereumChain with full parameters, raising success to 95%. Failures often occur because a chain (e.g., Arbitrum) isn't pre‑added in Trust Wallet—without a fallback the user sees chain not added.

Approach comparison

For most projects, wagmi + Web3Modal is optimal—it covers 95% of scenarios, has an active community, and frequent updates. Compared to raw SDK, you get 3x faster development and halved costs.

Mobile wallet comparison

In practice, Trust Wallet behaves unpredictably with EIP-1559—sometimes ignoring the transaction type. We account for this by forcing maxPriorityFeePerGas.

Handling common errors

• Hydration mismatch in Next.js: Wrap wallet‑state components in 'use client' and read state via useEffect.
• Mobile deep links not working: Web3Modal handles them automatically. For custom UI, set the redirect parameter.
• Session expiry: Listen for session_expire and show a toast with a reconnect offer.

What's included in the work

• WalletConnect Cloud project setup and key acquisition.
• Integration of wagmi and Web3Modal (or alternatives).
• Session configuration and reconnection handling.
• Testing on iOS/Android: MetaMask Mobile, Trust Wallet, Rainbow.
• Edge case handling: network errors, transaction rejection, account change.
• Integration documentation for your team.
• 30‑day support after delivery.

Our experience and guarantees

With 10+ years in production and over 20 dApps integrated—from NFT marketplaces to DeFi protocols—we ensure stable operation on all major mobile wallets. Contact us for a free integration consultation. We'll assess your project and provide an accurate estimate.