WalletConnect Monorepo Documentation

The SDK uses a provider abstraction to support different environments. It auto-detects the best available provider:

• NativeProvider: Uses the React Native uniffi module (currently supported).
• WasmProvider: Uses a WebAssembly module (coming soon).

You can use provider utilities to check availability or manually inject the native module if auto-discovery fails.

import {
  isProviderAvailable,
  detectProviderType,
  isNativeProviderAvailable,
  setNativeModule,
} from "@walletconnect/pay";

// Check if any provider is available
if (isProviderAvailable()) {
  // SDK can be used
}

// Detect which provider type is available
const providerType = detectProviderType(); // 'native' | 'wasm' | null

// Check specifically for native provider
if (isNativeProviderAvailable()) {
  // React Native native module is available
}

// Manually inject native module (if auto-discovery fails)
import { NativeModules } from "react-native";
setNativeModule(NativeModules.RNWalletConnectPay);

Because EthereumProvider relies on browser-specific APIs (window, document, localStorage), it cannot be initialized on the server. When using SSR frameworks like Next.js, follow these steps:

1. Isolate in a Client Component: Create a component (e.g., WalletConnectLogic.tsx) and mark it with the "use client"; directive.
2. Dynamic Import: In your server-side or parent component, import the client component using next/dynamic with ssr: false to prevent the server from attempting to execute the provider code.

// src/app/page.tsx
"use client";

import dynamic from 'next/dynamic';
import { Suspense } from 'react';

const WalletConnectLogic = dynamic(
  () => import('@/components/WalletConnectLogic'),
  { ssr: false }
);

export default function Home() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <WalletConnectLogic />
    </Suspense>
  );
}

After initialization, call provider.connect() to establish a connection. You must define namespaces to specify which chains and methods your application supports.

For EIP-155 (Ethereum) namespaces, you should provide:

• methods: An array of supported JSON-RPC methods (e.g., eth_sendTransaction).
• chains: An array of chain identifiers in the format <namespace>:<chainId> (e.g., eip155:80001).
• events: An array of supported events (e.g., chainChanged).
• rpcMap: A mapping of chain IDs to their respective RPC URLs.

Optional connection parameters:

• pairingTopic: A specific topic to connect to.
• skipPairing: A boolean (defaults to false) to skip the pairing process.

import { ethers } from "ethers";
import UniversalProvider from "@walletconnect/universal-provider";

//  Initialize the provider
const provider = await UniversalProvider.init({
  logger: "info",
  relayUrl: "ws://<relay-url>",
  projectId: "12345678",
  metadata: {
    name: "React App",
    description: "React App for WalletConnect",
    url: "https://walletconnect.com/",
    icons: ["https://avatars.githubusercontent.com/u/37784886"],
  },
  client: undefined, // optional instance of @walletconnect/sign-client
});

//  create sub providers for each namespace/chain
await provider.connect({
  namespaces: {
    eip155: {
      methods: [
        "eth_sendTransaction",
        "eth_signTransaction",
        "eth_sign",
        "personal_sign",
        "eth_signTypedData",
      ],
      chains: ["eip155:80001"],
      events: ["chainChanged", "accountsChanged"],
      rpcMap: {
        80001:
          "https://rpc.walletconnect.org?chainId=eip155:80001&projectId=<your walletconnect project id>",
      },
    },
    pairingTopic: "<123...topic>", // optional topic to connect to
    skipPairing: false, // optional to skip pairing ( later it can be resumed by invoking .pair())
  },
});

//  Create Web3 Provider
const web3Provider = new ethers.providers.Web3Provider(provider);