# 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

| Error | Description | Solution |
| --- | --- | --- |
| "Pairing URI expired" | The connection link has expired | Generate a new connection link from the dApp |
| "Session proposal channel not found" | Connection was interrupted | Try reconnecting to the dApp |
| "Invalid address" | Address format is incorrect | Check the address format and try again |
| "Transaction timeout" | Transaction took too long to process | Check network status and try again |

## API Reference

### Connecting to a dApp

HTTP

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

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

### Disconnecting from a dApp

HTTP

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

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

### Response Format

JSON

```json
{
  "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"
        }
      }
    ]
  }
}
```