WalletConnect Usage Guide

WalletConnect enables seamless integration between your Blockdaemon wallet and decentralized applications (dApps). This guide explains how to use WalletConnect to connect your wallet to dApps and manage those connections.

Overview

WalletConnect is a protocol that allows secure communication between wallets and dApps through encrypted peer-to-peer connections. In the Blockdaemon wallet system, WalletConnect enables you to:

• Connect your wallet to dApps using deep links
• Approve transactions initiated by connected dApps
• Manage multiple dApp connections
• Securely disconnect from dApps when needed

Getting Started

Prerequisites

• An active Blockdaemon wallet account
• At least one EVM-compatible address in your wallet
• A dApp that supports WalletConnect

Connecting to a dApp using the Wallet Interface

1. Navigate to your wallet and select the address you want to connect
2. Click the WalletConnect button (purple icon) next to your address
3. Paste the WalletConnect URI provided by the dApp into the input field
4. Click "Connect" to initiate the pairing process
5. Wait for confirmation - the dApp will appear in your connected dApps list

Managing Connections

Viewing Connected dApps

Once connected, you can view all your dApp connections:

1. Go to your address details in the wallet
2. Look for the "WalletConnections" section
3. See all connected dApps with their names, URLs, and icons

Disconnecting from a dApp

To disconnect from a dApp:

1. Navigate to your address with the connected dApp
2. Click the WalletConnect button to open the connection dialog
3. Find the dApp you want to disconnect from
4. Click "Disconnect" next to the dApp name
5. Confirm the disconnection

Transaction Approval

When a connected dApp initiates a transaction:

1. The dApp sends a transaction request through WalletConnect
2. Your wallet receives the request and displays transaction details
3. Review the transaction including:
   • Recipient address
   • Amount to send
   • Gas fees
   • Transaction data
4. Approve or reject the transaction
5. The transaction is broadcast to the blockchain if approved

Supported Transaction Types

Currently, the Blockdaemon wallet supports:

• ETH transfers - Sending native Ethereum tokens
• Contract interactions - Calling smart contract functions
• Token transfers - Moving ERC-20 tokens (when supported)

Security Considerations

Connection Security

• All connections are encrypted using WalletConnect's secure protocol
• Private keys never leave your wallet during WalletConnect sessions
• Each connection is isolated and cannot access other connections

Transaction Security

• Always review transaction details before approving
• Verify recipient addresses are correct
• Check gas fees are reasonable
• Be cautious with unknown dApps and their transaction requests

Troubleshooting

Common Issues

Connection Fails

• Check the WalletConnect URI is valid and not expired
• Ensure your wallet is unlocked and the address is active
• Verify network compatibility between dApp and wallet
• Try refreshing the dApp and generating a new connection link

Transaction Fails

• Check your ETH balance for gas fees
• Verify the transaction parameters are correct
• Ensure the dApp is compatible with your wallet version
• Try increasing gas limits if the transaction is complex

dApp Not Responding

• Check your internet connection
• Refresh the dApp page
• Disconnect and reconnect the WalletConnect session
• Clear browser cache if using a web dApp

Error Messages

API Reference

Connecting to a dApp

PATCH /api/v2/addresses/{addressId}
Content-Type: application/json

{
  "walletConnectionPairingURI": "wc:abc123@2?relay-protocol=irn&symKey=def456"
}

Disconnecting from a dApp

PATCH /api/v2/addresses/{addressId}
Content-Type: application/json

{
  "dappURIToDisconnectFrom": "https://example-dapp.com"
}

Response Format

{
  "metadata": {
    "id": 123,
    "name": "My Ethereum Address"
  },
  "config": {
    "address": "0x1234567890123456789012345678901234567890",
    "network": "sepolia",
    "protocol": "ethereum",
    "walletConnections": [
      {
        "addressID": 123,
        "dapp": {
          "name": "Example dApp",
          "url": "https://example-dapp.com",
          "iconURL": "https://example-dapp.com/icon.png"
        }
      }
    ]
  }
}