Documentation

Introduction

Adding support for a new wallet in WalletConnect requires implementing standardized methods in two core files. Once your pull request is merged, your wallet will be available to all WalletConnect users.

This guide walks you through the complete integration process, including:

  • Detecting wallet installation.
  • Verifying connection status.
  • Handling real-time wallet events (account changes, network switches, disconnections).

Clone WalletConnect Repository

The @btc-vision/walletconnect GitHub repository provides an easy and standardized way to integrate multiple wallets providers into your application.

  1. Request access to the @btc-vision/walletconnect repository on GitHub.
  2. Once you have access, clone the repository to your working directory using the git clone command.
Clone WalletConnect repositorybash
git clone [email protected]:btc-vision/walletconnect.git

Create Your Wallet Skeleton

  1. Navigate to the src/wallets directory from your repository root.
  2. Create your wallet directory (e.g., mywallet)
  3. Inside your wallet directory, create the two required files:
    • controller.ts
    • interface.ts

Your directory structure should now look like this:

  • src
    • wallets
      • mywallet (your new wallet directory)
        • controller.ts
        • interface.ts

controller.ts

This file implements your wallet controller, which provides the integration logic that connects your wallet to WalletConnect. The controller must implement the WalletBase interface, providing:

  • Wallet detection logic.
  • Connection management.
  • Data access methods.
  • Event handling.
WalletBase interfacetypescript
export interface WalletBase {
    isInstalled(): boolean;
    isConnected(): boolean;
    canAutoConnect(): Promise<boolean>;
    connect(): Promise<string[] | undefined>;
    disconnect(): Promise<void>;

    getWalletInstance(): OPWallet | null;
    getPublicKey(): Promise<string | null>;
    getNetwork(): Promise<WalletChainType>;
    getSigner(): Promise<null>;  // Reserved for future use.
    getBalance(): Promise<WalletBalance | null>;
    getProvider(): AbstractRpcProvider | null;

    setAccountsChangedHook(fn: (accounts: string[]) => void): void;
    removeAccountsChangedHook(): void;
    setDisconnectHook(fn: () => void): void;
    removeDisconnectHook(): void;
    setChainChangedHook(fn: (network: WalletChainType) => void): void;
    removeChainChangedHook(): void;
    switchNetwork(network: WalletNetwork|WalletChainType): Promise<void>;
    signMessage(message: string, messageType?: MessageType): Promise<string | null>;
    signMLDSAMessage(message: string): Promise<MLDSASignature | null>;
    verifyMLDSASignature(message: string, signature: MLDSASignature): Promise<boolean>;
}

interface.ts

This file defines your wallet's visual and type assets:

  • Wallet logo.
  • TypeScript type definitions.
  • Exported interfaces for the WalletInstance window object.

These exports enable type-safe integration when external applications interact with your wallet.

On this page