Connect to dApp

Learn how to connect Cave Wallet to your dApp.

Installation

First, install the Cave SDK:

npm install @cave/sdk

Connection Flow

1. Check Installation

import { CaveWallet } from '@cave/sdk';

async function checkWallet() {
  const isInstalled = await CaveWallet.isInstalled();
  
  if (!isInstalled) {
    // Redirect to install page or show message
    window.open('https://chrome.google.com/webstore/detail/cave/oefglhbffgfkcpboeackfgdagmlnihnh');
    return false;
  }
  
  return true;
}

2. Request Connection

async function connectWallet() {
  try {
    const wallet = await CaveWallet.connect();
    const account = await wallet.getAccount();
    
    console.log('Connected:', account.address);
    return wallet;
  } catch (error) {
    if (error.code === 4001) {
      // User rejected the connection
      console.log('User rejected connection');
    } else {
      console.error('Connection error:', error);
    }
  }
}

3. Handle Connection State

// Store connection state
let connectedWallet = null;

async function handleConnect() {
  connectedWallet = await connectWallet();
  
  if (connectedWallet) {
    updateUI(connectedWallet);
  }
}

function updateUI(wallet) {
  // Update your UI to show connected state
  document.getElementById('connectBtn').textContent = 'Connected';
}

Event Listeners

Account Changes

wallet.on('accountChanged', (account) => {
  console.log('New account:', account.address);
  // Update UI with new account
});

Disconnect

wallet.on('disconnect', () => {
  console.log('Wallet disconnected');
  connectedWallet = null;
  // Reset UI
});

Network Changes

wallet.on('networkChanged', (network) => {
  console.log('Network changed to:', network.chainId);
  // Handle network change
});

Complete Example

import { CaveWallet } from '@cave/sdk';

class WalletConnection {
  constructor() {
    this.wallet = null;
    this.account = null;
  }
  
  async connect() {
    // Check if installed
    const isInstalled = await CaveWallet.isInstalled();
    if (!isInstalled) {
      throw new Error('Cave Wallet not installed');
    }
    
    // Connect
    this.wallet = await CaveWallet.connect();
    this.account = await this.wallet.getAccount();
    
    // Setup listeners
    this.setupListeners();
    
    return this.account;
  }
  
  setupListeners() {
    this.wallet.on('accountChanged', (account) => {
      this.account = account;
      this.onAccountChange?.(account);
    });
    
    this.wallet.on('disconnect', () => {
      this.wallet = null;
      this.account = null;
      this.onDisconnect?.();
    });
  }
  
  disconnect() {
    this.wallet?.disconnect();
    this.wallet = null;
    this.account = null;
  }
  
  isConnected() {
    return this.wallet !== null;
  }
}

// Usage
const connection = new WalletConnection();
connection.onAccountChange = (account) => console.log('Account:', account);
connection.onDisconnect = () => console.log('Disconnected');

await connection.connect();

UI Best Practices

Connect Button States

<!-- Not Connected -->
<button id="connectBtn">Connect Wallet</button>

<!-- Connecting -->
<button disabled>Connecting...</button>

<!-- Connected -->
<button>0x1234...5678</button>

Error Handling

async function safeConnect() {
  try {
    await connectWallet();
  } catch (error) {
    switch (error.code) {
      case 4001:
        showToast('Connection rejected by user');
        break;
      case -32002:
        showToast('Connection request pending');
        break;
      default:
        showToast('Failed to connect wallet');
    }
  }
}

Next Steps

• Sign Transactions
• API Reference