Setting Up WalletConnect v2 for Enterprise dApps

WalletConnect v2 introduces a fundamental architectural shift from its predecessor, moving from a centralized relay to a decentralized, permissionless network. This upgrade is critical for enterprise dApps as it eliminates single points of failure, significantly improves scalability, and reduces latency. The new protocol uses a topic-based publish-subscribe model where clients communicate via a shared symmetric key, ensuring messages are only readable by intended participants. For production environments, this translates to enhanced reliability and a better user experience during peak traffic periods.

The first step is to choose and initialize a client SDK. For web dApps, the @walletconnect/universal-provider is the recommended package, as it abstracts multi-chain interactions. Installation is straightforward with npm install @walletconnect/universal-provider. Initialization requires a Project ID from the WalletConnect Cloud Dashboard, which manages your application's metadata and connection permissions. The core initialization object defines your app's name, description, URL, and required chains, such as Ethereum Mainnet (eip155:1) or Polygon (eip155:137).

Establishing a connection involves creating a pairing URI and listening for session approval. The provider.connect() method triggers this flow, returning a URI that can be displayed as a QR code or used for deep links. Your dApp must then subscribe to critical events: session_proposal for when a wallet responds, session_request for transaction signing prompts, and session_delete for disconnection handling. Implementing robust error handling for these events is non-negotiable for production stability, ensuring the UI responds appropriately to network issues or user rejections.

A key feature of v2 is multi-chain namespace support, allowing a single session to manage accounts across multiple blockchains. This is configured in the requiredNamespaces during connection. For an EVM-centric dApp, you would specify eip155 with methods like eth_sendTransaction and events like chainChanged. The session object returned upon approval contains an array of accounts formatted as chain_id:address (e.g., eip155:1:0x...), enabling seamless interaction across networks without re-pairing the wallet, a significant UX improvement for complex DeFi applications.

For enterprise deployment, security and performance optimizations are paramount. Always use the latest SDK version to patch known vulnerabilities. Implement server-side logging (without exposing private keys) to monitor connection success rates and error codes. Consider using the signClient from @walletconnect/sign-client for more granular control if the universal provider is too abstract. Furthermore, design your UI to gracefully handle the asynchronous nature of wallet interactions, providing clear pending states and fallbacks if the preferred wallet is not installed.

WalletConnect v2 is a suite of open-source protocols for establishing secure, remote connections between wallets and dApps. For enterprise integration, you must first understand its core architectural shift from v1. The new version is built on a universal JSON-RPC relay network, replacing the centralized bridge. This provides enhanced scalability, multi-chain support via namespaces, and improved session management. The protocol is defined in the WalletConnect v2 Specification.

Your development environment must be configured before writing any integration code. You will need a Node.js environment (v16 or later) and a package manager like npm or yarn. The primary SDKs are @walletconnect/universal-provider for dApps and @walletconnect/web3wallet for wallets. Install them via npm install @walletconnect/universal-provider. You will also need a Project ID from the WalletConnect Cloud, which is required for the relay service and analytics.

The most critical prerequisite is defining your application's required and optional namespaces. Namespaces are the multi-chain foundation of v2, specifying which blockchains and methods your dApp needs. A namespace defines the chains, methods, and events for a specific CAIP-2 chain identifier (e.g., eip155:1 for Ethereum Mainnet). Incorrect namespace configuration is the most common integration failure point. Your dApp's capabilities are explicitly declared in the session proposal.

For security and user experience, you must plan your session management logic. WalletConnect v2 sessions are persistent and can include multiple chains. Your dApp needs handlers for core lifecycle events: session_proposal for connection requests, session_request for transaction signing, and session_delete for disconnections. Implementing proper state synchronization between your dApp's UI and the WalletConnect session state is essential.

Finally, ensure you have access to the necessary blockchain infrastructure. While WalletConnect handles the connection, your dApp still needs RPC endpoints for reading chain data and broadcasting transactions. For testing, services like Alchemy or Infura provide reliable RPCs. You should also decide on a signing method; most Ethereum dApps use personal_sign and eth_sendTransaction. Verify that your target wallet supports the specific methods listed in your namespaces.

Before writing any code, ensure your development environment meets the core requirements. You will need Node.js version 18 or higher and a package manager like npm or yarn. For the dApp frontend, we'll use Next.js 14 with TypeScript as our framework, but the WalletConnect SDK is framework-agnostic. Create a new project using npx create-next-app@latest and follow the setup prompts. This establishes a clean, modern codebase with built-in routing and tooling.

The primary dependency is the WalletConnect client SDK, @walletconnect/universal-provider. This package is the core of v2, replacing the older, less scalable v1 @walletconnect/web3-provider. Install it alongside the essential Ethereum library viem and the WalletConnect utility for Ethereum-specific methods: npm install @walletconnect/universal-provider viem @walletconnect/ethereum-provider. Using viem is recommended over ethers.js for its superior TypeScript support and modular design, which aligns with WalletConnect v2's architecture.

Next, you must obtain a Project ID from the WalletConnect Cloud Dashboard. This ID is mandatory for v2 and enables message relaying, analytics, and push notifications. It ties your dApp to WalletConnect's infrastructure. Never hardcode this ID; instead, store it as an environment variable (e.g., NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID) in a .env.local file. This keeps your key secure and makes configuration environment-specific.

With dependencies installed, create a utility file to initialize the provider. Import UniversalProvider and EthereumProvider from the installed packages. The initialization is asynchronous. You must configure the provider with your Project ID, the list of required namespaces (starting with the eip155 namespace for EVM chains), and optional metadata about your dApp for wallet UIs. This setup is significantly more structured than v1, enabling multi-chain and multi-protocol support from the start.

Here is a basic initialization example for an Ethereum-focused dApp:

typescriptCopy
import { UniversalProvider } from '@walletconnect/universal-provider';
import { EthereumProvider } from '@walletconnect/ethereum-provider';

export async function createWalletConnectProvider() {
  const provider = await UniversalProvider.init({
    projectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID,
    metadata: {
      name: 'My Enterprise dApp',
      description: 'A description for wallet UIs',
      url: 'https://myapp.com',
      icons: ['https://myapp.com/icon.png']
    }
  });

  const ethereumProvider = await EthereumProvider.init({
    universalProvider: provider,
    chains: [1], // Ethereum Mainnet chain ID
    methods: ['eth_sendTransaction', 'personal_sign'], // Required RPC methods
    events: ['chainChanged', 'accountsChanged'] // Events to listen for
  });

  return { provider, ethereumProvider };
}

This code creates two objects: the core UniversalProvider for session management and the EthereumProvider wrapper that exposes a familiar EIP-1193 interface for Ethereum interactions.

Finally, integrate this provider factory into your application's state management. A common pattern is to create a React context or a singleton service that calls createWalletConnectProvider and makes the ethereumProvider instance globally available. This setup is now complete. The next steps involve building the UI components to connect a wallet, handle sessions, and listen for events, which will utilize this configured provider.

In WalletConnect v2, a namespace is a structured object that defines which blockchains, accounts, and methods your dApp can interact with. Unlike v1, which was Ethereum-centric, v2's namespace system is the foundation for true multi-chain support. The core structure includes chains, methods, and events. For enterprise applications, precise namespace configuration is critical for security, user experience, and ensuring your dApp only requests permissions for relevant chains.

The chains array uses CAIP-2 chain IDs (e.g., eip155:1 for Ethereum Mainnet, cosmos:cosmoshub-4) to explicitly declare supported networks. You must list every chain your dApp's logic requires. The methods and events arrays define the JSON-RPC calls (like eth_sendTransaction, personal_sign) and events (chainChanged, accountsChanged) your dApp will request from the wallet. Wallets use this configuration to filter and present only compatible chains to the user during the connection handshake.

Here is a basic namespace configuration for a dApp operating on Ethereum and Polygon:

jsonCopy
{
  "eip155": {
    "chains": ["eip155:1", "eip155:137"],
    "methods": ["eth_sendTransaction", "personal_sign", "eth_signTypedData_v4"],
    "events": ["chainChanged", "accountsChanged"]
  }
}

This tells WalletConnect and the user's wallet that your application needs access to Ethereum and Polygon accounts, and will request specific signing methods.

For complex dApps, you can define multiple namespaces. A cross-chain DeFi aggregator might include eip155 for EVM chains, cosmos for Cosmos SDK chains, and solana for Solana. Each namespace is configured independently. It is a best practice to dynamically generate this configuration based on your dApp's feature set and the user's selected networks, rather than using a static, overly permissive list that could confuse users or pose a security risk.

During the connection process, the wallet evaluates your proposed namespaces. It may only approve a subset (e.g., only the chains the user has accounts on) or reject incompatible requests. Your dApp must handle this negotiation gracefully. Always validate the final, approved namespace returned in the session object (session.namespaces) and adjust your UI accordingly—only show features for chains the user has actually granted access to.

A WalletConnect v2 session is a persistent, encrypted connection between your dApp's frontend and a user's wallet. Unlike a simple transaction approval, a session allows for multiple requests over time without re-pairing. The session's state is managed by a Session object, which contains critical metadata like the connected chains, accounts, and the session's unique topic used for relay communication. Your dApp must store this object (e.g., in localStorage or a state manager) to reconnect to the session after a page refresh.

To initialize a session, you first create a SignClient instance with your project ID from the WalletConnect Cloud. The core method is signClient.connect(), which takes a ConnectParams object. You must define the required namespaces, which are the cornerstone of v2's multi-chain architecture. For an EVM dApp, this typically includes the eip155 namespace with the specific chain IDs and methods/events you intend to use.

javascriptCopy
const { uri, approval } = await signClient.connect({
  requiredNamespaces: {
    eip155: {
      chains: ['eip155:1', 'eip155:137'], // Ethereum & Polygon
      methods: ['eth_sendTransaction', 'personal_sign'],
      events: ['chainChanged', 'accountsChanged']
    }
  }
});

The method returns a uri for the pairing QR code/module and an approval promise that resolves with the Session object once the user approves in their wallet.

After receiving the session, you must listen for events to keep your UI in sync. Subscribe to the session_event, session_update, and session_delete events. The session_event listener handles requests from the wallet (like chain changes), while session_update manages namespace modifications. Crucially, session_delete is emitted when the wallet disconnects; your dApp must clear the local session state and update the UI accordingly. Failing to handle this event will leave users with a stale connection state.

To submit requests within an active session, use signClient.request(). You must target the session's topic and specify the chain-aware CAIP-2 chain ID within the request. For example, to request a signature on Ethereum Mainnet:

javascriptCopy
const result = await signClient.request({
  topic: session.topic,
  chainId: 'eip155:1',
  request: {
    method: 'personal_sign',
    params: [message, accountAddress]
  }
});

All session operations—requests, events, updates—are encrypted and routed through the WalletConnect relay, ensuring communication persists even if your dApp's frontend temporarily loses connectivity.

Finally, implement a clean disconnect flow. Call signClient.disconnect() with the session's topic and a reason object. This sends a disconnect request to the wallet, triggers the session_delete event on both ends, and removes the session from the relay. Always pair this programmatic disconnect with the cleanup of your local application state. For enterprise applications, consider implementing session health checks and automatic reconnection logic for a resilient user experience.

Once a session is established, your dApp can request the user to sign transactions. The core method for this is signClient.request, which sends a JSON-RPC request to the connected wallet. You must specify the chainId (e.g., eip155:1 for Ethereum Mainnet), the user's topic from the active session, and the specific request method like eth_sendTransaction. The request parameters must match the wallet's expected format, typically an object containing from, to, value, gas, and data fields. Always handle the asynchronous response, which will contain the transaction hash or signature.

Constructing a transaction object requires careful attention to gas estimation and nonce management for a smooth user experience. For Ethereum transactions, use eth_estimateGas via your provider to suggest a gas limit and fetch the current nonce for the from address to prevent conflicts. For complex interactions like token approvals or contract calls, the data field must be the encoded function call. Libraries like ethers.js or viem simplify this encoding. Remember, the wallet may modify these parameters (like increasing gas price) before signing, so your UI should manage pending states.

You must implement listeners for the wallet's response using signClient.on('session_event', ...) and signClient.on('session_delete', ...). The session_event listener captures the approval or rejection of the request, returning a result or error. The session_delete listener signals the user disconnected the session, requiring your dApp to reset its connection state. Always pair outgoing requests with these listeners to update the UI, show success messages, or handle errors like "User rejected the request." This ensures your application remains synchronized with the wallet's state.

For enterprise applications, consider batching multiple operations into a single request where possible, using methods like eth_sendRawTransaction for pre-signed bundles. Implement robust error handling for common failure modes: network switches (wrong chainId), insufficient funds, or wallet-specific limitations. Logging request IDs and corresponding responses is crucial for debugging user-reported issues. Furthermore, you can extend functionality by listening for chainChanged and accountsChanged events from the EIP-1193 provider provided by WalletConnect to keep your dApp's state aligned with the wallet.

WalletConnect v2 introduces a multi-chain, multi-account architecture built on a decentralized relay network, moving away from the v1 bridge model. For enterprise dApps, this means improved reliability and scalability. The core component is the Sign Client, initialized with a mandatory projectId from the WalletConnect Cloud. This ID enables encrypted communication through the public relay and provides access to analytics. Always initialize the client as a singleton to prevent connection state conflicts across your application. Use the official @walletconnect/universal-provider for EVM chains or the @walletconnect/sign-client for more granular control.

Secure session management is critical. The requiredNamespaces parameter defines which blockchains and methods your dApp needs, enforcing a principle of least privilege. For an EVM dApp, specify eip155 with the required chains (e.g., ["eip155:1"] for Ethereum Mainnet), methods like eth_sendTransaction, and events like chainChanged. Never request unnecessary permissions. Handle the session_delete event to clean up local state when a user disconnects from their wallet. Implement robust error handling for connection timeouts and rejected pairing attempts to maintain a smooth user experience.

For production reliability, implement a layered connection strategy. Use the pair method with a URI from signClient.connect to generate a QR code. Simultaneously, listen for pairing_delete events to detect failed attempts. For desktop users, deep linking via window.location.href is essential. Monitor connection stability using the built-in relay ping/pong and log events to your observability platform. Key metrics to track include pairing success rate, session approval time, and method call failure rates. These insights help identify issues with specific wallets or network conditions.

Optimize for a multi-chain future by leveraging WalletConnect v2's native multi-chain support. A single session can include multiple namespaces (e.g., eip155 for Ethereum, solana for Solana). Structure your requiredNamespaces to request only the chains you currently support, but design your state management to handle additional chains approved by the user. This makes it easier to expand your dApp's blockchain support without breaking existing user sessions. Always validate the active chain ID from the session namespace before submitting transactions to prevent user errors.

Finally, ensure your integration is maintainable. Pin your SDK versions to avoid breaking changes. Subscribe to WalletConnect's GitHub releases for updates. Implement a feature flag to allow rolling back to a legacy connection method if needed. Thoroughly test with a wide range of wallet apps, including MetaMask, Trust Wallet, and Rainbow, to ensure compatibility. By following these practices, you build a wallet integration that is secure, resilient, and ready for scale.