Wallet Client Integration
Module 3B: Connecting to User Wallets (Frontend Paradigm)
This module teaches you how to integrate MetaNet Desktop Wallet into your dApp using the BSV SDK's WalletClient component. This is the standard approach for building non-custodial BSV applications where users control their own keys.
Note: This module is for Frontend Integration Development. If you're building backend services where you control keys, see Managing Wallets Server-Side instead.
What is WalletClient?
WalletClient is a pre-built SDK component that:
β Connects your dApp to BSV Desktop (MetaNet Desktop Wallet)
β Requests user signatures for transactions
β Handles all wallet communication via BRC protocol
β Manages UTXO selection (wallet handles)
β Calculates fees automatically (wallet handles)
β Broadcasts transactions (wallet handles)
What is BSV Desktop?
BSV Desktop is the modern, standard wallet for BSV blockchain development. It provides:
π Secure key management with phone-based recovery
π Multi-network support (mainnet/testnet switching)
π Welcome gift: 99,991 Satoshis to start exploring
π Seamless app integration for blockchain applications
π± Identity Key management for dApp authentication
π§ Built-in testnet faucet for developers
Download BSV Desktop: https://desktop.bsvb.tech/
Complete Onboarding Guide: https://hub.bsvblockchain.org/demos-and-onboardings/onboardings/onboarding-catalog/metanet-desktop-mainnet
You don't need to:
β Manage private keys
β Track UTXOs
β Calculate fees
β Handle change outputs
β Configure ARC broadcasting
The wallet does all of this for you!
Prerequisites
Before starting:
β Completed Development Environment Setup
β BSV Desktop installed and set up
Download from: https://desktop.bsvb.tech/
Complete setup wizard
Switch to testnet mode for development
Get free testnet BSV from built-in faucet
β Basic understanding of React or your frontend framework
β Node.js and npm installed
First time using BSV Desktop? Follow the complete guide: https://hub.bsvblockchain.org/demos-and-onboardings/onboardings/onboarding-catalog/metanet-desktop-mainnet
Part 1: WalletClient Basics
Installation
WalletClient is included in @bsv/sdk:
Import
Core Methods
These are the main methods you'll use! WalletClient handles the complexity of key management, UTXO selection, and broadcasting.
Part 2: Connecting to MetaNet Desktop Wallet
Basic Connection
Connection Flow
React Hook for Wallet Connection
Wallet Connection Component
Part 3: Sending Transactions
Simple Payment
What Happens Under the Hood
When you call wallet.createAction():
WalletClient sends transaction request to MetaNet Desktop Wallet
Wallet popup appears showing transaction details
User reviews:
Recipient address
Amount to send
Fee (calculated by wallet)
Total deduction from balance
User approves or rejects
Wallet:
Selects UTXOs
Calculates optimal fee
Creates change output
Signs transaction
Broadcasts to BSV network
WalletClient returns TXID
Your dApp never sees the private key!
Payment Component
Part 4: Multiple Outputs
Batch Payments
Payment with Metadata (OP_RETURN)
Part 5: Message Signing
Sign and Verify Messages
Authentication with Signatures
Part 6: Error Handling
Common Error Codes
Comprehensive Error Handler
Part 7: Best Practices
1. Always Check Connection State
2. Provide Clear Transaction Previews
3. Handle User Cancellation Gracefully
4. Provide Fallback Instructions
5. Persist Connection State
Part 8: Complete dApp Example
Here's a complete React dApp integrating all concepts:
Summary
What You Learned:
β WalletClient connects your dApp to MetaNet Desktop Wallet
β Wallet handles all key management, UTXO selection, fees, and broadcasting
β Your dApp requests user approval for transactions
β Error handling for user rejections and failures
β Message signing for authentication
β Best practices for UX and state management
What You DON'T Need to Do:
β Manage private keys
β Track UTXOs
β Calculate fees
β Create change outputs
β Configure ARC
β Handle low-level transaction details
The wallet does all of this automatically!
Next Steps
Building Transactions - Learn transaction structure and SDK methods
BSV Fundamentals - Understand UTXOs, scripts, and blockchain concepts
Intermediate Projects - Build real-world dApps with WalletClient
Resources
Wallet Toolbox API: https://fast.brc.dev/
BRC Standards: https://hub.bsvblockchain.org/brc
MetaNet Desktop Wallet: https://desktop.bsvb.tech/
Get BSV - Orange Gateway: https://hub.bsvblockchain.org/demos-and-onboardings/onboardings/onboarding-catalog/get-bsv/orange-gateway
SDK Documentation: https://bsv-blockchain.github.io/ts-sdk/
Example dApps: code-features/
You're now ready to build non-custodial BSV dApps!
Last updated
