Skip to main content
The WalletConnect provider enables integration with any wallet that supports the WalletConnect v2 protocol for Algorand.

Installation

Install the required peer dependencies:
npm install @walletconnect/modal @walletconnect/sign-client

Basic usage

import { WalletId } from '@txnlab/use-wallet'

const walletManager = new WalletManager({
  wallets: [
    {
      id: WalletId.WALLETCONNECT,
      options: { projectId: 'YOUR_PROJECT_ID' }
    }
  ]
})

Configuration

Required options

projectId
string
required
Your WalletConnect Cloud project ID. Get one at WalletConnect Cloud.

Optional options

relayUrl
string
default:"wss://relay.walletconnect.com"
Custom relay server URL.
metadata
SignClientTypes.Metadata
Custom metadata for your dApp displayed in wallet connection prompts.Properties:
  • name: dApp name
  • description: dApp description
  • url: dApp URL
  • icons: Array of icon URLs
enableExplorer
boolean
default:"true"
Show the wallet explorer in the connection modal.
Array of wallet IDs to recommend in the explorer.
privacyPolicyUrl
string
URL to your privacy policy.
termsOfServiceUrl
string
URL to your terms of service.
themeMode
'light' | 'dark' | 'auto'
default:"'auto'"
Theme mode for the WalletConnect modal.
themeVariables
Record<string, string>
Custom CSS variables for theming the modal.
skin
string | WalletConnectSkin
Apply a custom skin to this WalletConnect instance. Can be a built-in skin ID (e.g., ‘biatec’) or a custom skin object with id, name, and icon properties.When a skin is applied, the wallet uses the skin’s metadata and a unique wallet key for state isolation.

Type definitions

export interface WalletConnectOptions {
  // Required
  projectId: string
  
  // Optional sign client options
  relayUrl?: string
  metadata?: SignClientTypes.Metadata
  
  // Optional modal options
  enableExplorer?: boolean
  explorerRecommendedWalletIds?: string[]
  privacyPolicyUrl?: string
  termsOfServiceUrl?: string
  themeMode?: 'light' | 'dark' | 'auto'
  themeVariables?: Record<string, string>
  
  // Skin support
  skin?: WalletConnectSkinOption
}

interface SignClientTypes.Metadata {
  name: string
  description: string
  url: string
  icons: string[]
}

Features

Universal wallet support

Connect to any Algorand wallet that supports WalletConnect v2, including mobile wallets, browser extensions, and desktop applications.

QR code connection

Displays a QR code for mobile wallet connection. Users scan the code with their mobile wallet to establish a connection.

Skin support

Use the skin option to customize the appearance and branding of WalletConnect instances. This allows multiple WalletConnect-based wallets with different identities.
{
  id: WalletId.WALLETCONNECT,
  options: {
    projectId: 'YOUR_PROJECT_ID',
    skin: 'biatec'  // or { id: 'custom', name: 'My Wallet', icon: '...' }
  }
}

Automatic metadata detection

If no metadata is provided, WalletConnect automatically detects your dApp’s metadata from the HTML document (title, description, favicon).

Methods

connect()

Initiates WalletConnect session. Opens the WalletConnect modal with QR code. Returns: Promise<WalletAccount[]>

disconnect()

Disconnects the WalletConnect session and closes the modal. Returns: Promise<void>

signTransactions()

Signs transactions via the connected wallet. The wallet will prompt the user for approval. Parameters:
  • txnGroup: Transaction or array of transactions to sign
  • indexesToSign?: Optional array of indexes to sign
Returns: Promise<(Uint8Array | null)[]>

Session management

WalletConnect v2 sessions persist across page reloads. Sessions are stored in the browser’s localStorage and automatically restored when the app initializes.

Network configuration

WalletConnect uses CAIP-2 chain IDs. Ensure your network configuration includes the caipChainId property:
const walletManager = new WalletManager({
  wallets: [{ id: WalletId.WALLETCONNECT, options: { projectId: 'YOUR_PROJECT_ID' } }],
  network: 'testnet'  // or custom NetworkConfig with caipChainId
})

Platform support

  • Web: Full support
  • Mobile: Full support (via QR code scanning)
  • Desktop: Full support

Troubleshooting

Missing project ID error

Ensure you’ve created a project at WalletConnect Cloud and provided the project ID in the options.

Network not supported

Verify that your network configuration includes a valid caipChainId. The library includes CAIP chain IDs for MainNet, TestNet, BetaNet, and Sandbox by default.

Source code

View the WalletConnect implementation: walletconnect.ts

Build docs developers (and LLMs) love