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:

  • βœ… 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():

  1. WalletClient sends transaction request to MetaNet Desktop Wallet

  2. Wallet popup appears showing transaction details

  3. User reviews:

    • Recipient address

    • Amount to send

    • Fee (calculated by wallet)

    • Total deduction from balance

  4. User approves or rejects

  5. Wallet:

    • Selects UTXOs

    • Calculates optimal fee

    • Creates change output

    • Signs transaction

    • Broadcasts to BSV network

  6. 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