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 Institutional Vault, WalletConnect enables you to:

• Connect a Vault account to dApps using a pairing URI (QR code or deep link)
• Approve signing requests initiated by connected dApps
• Manage multiple dApp connections
• Disconnect from dApps when needed

The same pairing and session APIs cover EVM chains and Canton. Canton dApps use the canton WalletConnect namespace and Canton RPC methods (canton_*). Pairing still uses POST /api/cwp/walletconnect/pair.

Getting Started

Prerequisites

• An active Institutional Vault account
• For EVM dApps: at least one EVM address on a registered chain
• For Canton dApps: Canton enabled on the deployment, a registered Canton chain (for example canton:devnet, canton:testnet, or canton:mainnet), and a Vault account with a Canton party
• A dApp that supports WalletConnect (Canton dApps typically use the Canton WalletConnect adapter and request the canton namespace)

Connecting to a dApp using the Wallet Interface

1. Navigate to your wallet and select the account or address you want to connect (an EVM address, or a Canton party account)
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 request:

1. The dApp sends a request through WalletConnect
2. Your wallet receives the request and creates a Vault operation
3. Review the request in the wallet and ApproverApp (when policy requires confirmation or approval)
4. Approve or reject the operation
5. The result is returned to the dApp after the operation completes

EVM requests typically include recipient, amount, gas, and calldata. Canton requests follow the Canton dApp methods below (status, accounts, ledger calls, message signing, or prepare-sign-execute). They do not use EVM gas fields.

EVM

Institutional Vault supports:

• Native transfers
• Contract interactions
• ERC-20 token transfers (when the token is registered)

Typical WalletConnect methods: eth_sendTransaction, personal_sign.

Canton

Canton sessions use CAIP-2 chain IDs such as canton:devnet, canton:testnet, or canton:mainnet. Session account strings are canton:\{network\}:\{party\} where the party ID is URL-encoded because Canton party IDs contain ::.

Supported WalletConnect methods:

canton_prepareSignExecute is the one-shot path Canton dApps use to prepare, sign, and submit. Policy, confirmation, and approval apply the same way as other Vault signing operations.

Do not point Canton dApps at a public /api/v0/dapp URL on Institutional Vault. Use WalletConnect (/api/cwp/walletconnect) for the dApp session. Direct MPC signing without WalletConnect remains on POST /api/cwp/canton.

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 request details before approving
• Verify recipient addresses or Canton parties are correct
• On EVM, check gas fees are reasonable
• Be cautious with unknown dApps and their 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 (EVM chain ID, or Canton CAIP-2 such as canton:devnet)
• Try refreshing the dApp and generating a new connection link

Request Fails

• On EVM, check native balance for gas fees
• On Canton, confirm the party exists on the registered chain and that Canton is enabled
• Verify the request parameters are correct
• Ensure the dApp requested the canton namespace for Canton sessions (EVM dApps use eip155)
• On EVM, 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

WalletConnect pairing and session management use the Core Wallet Platform endpoints (not the removed v2 address PATCH routes).

Connecting to a dApp

POST /api/cwp/walletconnect/pair
Content-Type: application/json

{
  "uri": "wc:abc123@2?relay-protocol=irn&symKey=def456",
  "masterKeyName": "Default",
  "accountName": "my-account",
  "initiatorUserID": "[email protected]"
}

uri is the WalletConnect pairing URI from the dApp. masterKeyName and accountName select the Vault account used for signing. initiatorUserID is optional and is used for policy evaluation when set.

Disconnecting from a dApp

POST /api/cwp/walletconnect/disconnect
Content-Type: application/json

{
  "topic": "<session-or-pairing-topic>"
}

Obtain active session topics with GET /api/cwp/walletconnect/sessions (optional query filters: masterKeyName, accountName, initiatorUserID).

List sessions response

{
  "sessions": [
    {
      "topic": "abc123...",
      "expiry": 1735689600,
      "accounts": ["eip155:1:0x1234..."],
      "peerMetadata": {
        "name": "Example dApp",
        "url": "https://example-dapp.com",
        "icons": ["https://example-dapp.com/icon.png"]
      }
    }
  ]
}

Exact session fields follow the OpenAPI CwpWalletConnectSessionInfo schema in your deployment Swagger. Canton sessions list accounts as canton:<network>:<url-encoded-party-id> (party IDs are URL-encoded because they contain ::).