Connect to a browser wallet
Connect a web page to BSV Desktop with createWallet from @bsv/simple/browser, then read the wallet’s identity keyThe public key that identifies a wallet to apps and other users, network and balance. Do this first in a web app where each user approves spending in their own wallet, before you call the payment, token or data methods of @bsv/simple. The example is a page of its own, served by Vite, and its calls read the wallet without spending. This page was written against @bsv/simple 0.7.2, @bsv/sdk 4.0.1 and Vite 8.3.8.
Before you begin
You need:
-
Node.js 22.12 or newer, which Vite 8 requires.
-
A Vite project. To create one, run
npm create vite@latest my-app -- --template vanilla --no-interactive. It ends withDone. Now run:and the next commands. Then install the packages in themy-appfolder:npm install @bsv/simple @bsv/sdkThe install ends with:
added 173 packages, and audited 174 packages in 1m found 0 vulnerabilities -
BSV Desktop open and set to testnet. To set it up, follow Set up a testnet wallet in the Quick Start.
How it works
createWallet creates a WalletClient from @bsv/sdk with the 'auto' substrateThe transport between your code and the wallet, such as the HTTP port of BSV Desktop, which finds the wallet running on the user’s machine, and asks it for the user’s identity key. It then returns a wallet object that holds the key and the @bsv/simple methods. The page holds no private key: every method that spends or signs goes to the wallet, which can ask the user to approve it. A payment the user approves is broadcast and cannot be reversed. To see how the package wraps @bsv/sdk, read How @bsv/simple is built. To see how the substrates and the origin work, read Connect to a wallet with WalletClient.
createWallet takes an optional object of defaults for the wallet object’s methods. The main ones:
| Default | Value when left out | Used for |
|---|---|---|
network | 'main' | The network field that getStatus() and getWalletInfo() return |
description | 'BSV-Simplify transaction' | The description of the transactions that send() and the inscription methods create |
outputDescription | 'BSV-Simplify output' | The description of the outputs of those transactions |
tokenBasket | 'tokens' | The basketA named group of outputs that a wallet tracks together where the token methods keep tokens |
messageBoxHost | 'https://messagebox.babbage.systems' | The message box server that pay() uses |
The wallet decides the network, not the network default. Pass network: 'testnet' so that getStatus() reports the network you test on, and read the network of the wallet itself with getClient().getNetwork().
Connect from a web page
The first step is a page with one button that starts the connection. In the my-app folder:
getAddress() returns the address of the identity key in the Mainnet format, which starts with 1, even when the wallet is on testnet. Do not show it to users as a testnet address, and do not ask anyone to send coins to it. To receive a payment, use the payment methods of @bsv/simple instead.
Add the button
Replace the content of index.html with a button, an area for the results and the script of the page:
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Browser wallet</title></head>
<body>
<button id="connect">Connect wallet</button>
<pre id="out"></pre>
<script type="module" src="/main.js"></script>
</body>
</html>Write the script
Create main.js next to index.html. On a click, it connects to the wallet and writes five values on the page:
import { createWallet } from '@bsv/simple/browser'
const out = document.getElementById('out')
const log = (line) => { out.textContent += line + '\n' }
document.getElementById('connect').addEventListener('click', async () => {
try {
const wallet = await createWallet({ network: 'testnet' })
log('Identity key: ' + wallet.getIdentityKey())
log('Status: ' + JSON.stringify(wallet.getStatus()))
log('Address: ' + wallet.getAddress())
const { network } = await wallet.getClient().getNetwork()
log('Wallet network: ' + network)
const balance = await wallet.getBalance()
log('Balance: ' + JSON.stringify(balance))
} catch (e) {
log('Error: ' + e.message)
}
})getIdentityKey()returns the public identity key thatcreateWalletreceived from the wallet. It identifies the user to other apps and is safe to share.getClient()returns theWalletClientunder the object, so you can call any BRC-100The standard set of methods an app calls on a user's wallet method that@bsv/simpledoes not wrap, such asgetNetwork.getBalance()with no basket returns the balance of the wallet’s default basket intotalSatoshisandspendableSatoshis, and0in the two output counts. Pass a basket name, such asgetBalance('tokens'), to count the outputs of that basket too.
Start the page
Run the Vite development server from the my-app folder:
npx vite --port 5173Vite prints the address of the page. Your startup time differs:
VITE v8.3.8 ready in 209 ms
➜ Local: http://localhost:5173/Open that address in the browser, with BSV Desktop open.
Connect the wallet
Click Connect wallet. If BSV Desktop asks whether the page may use the wallet, approve it. The page then shows the five values. Your key, address and balance differ. YOUR_IDENTITY_KEY and YOUR_ADDRESS stand for the 66 character key and the address of your wallet:
Identity key: YOUR_IDENTITY_KEY
Status: {"isConnected":true,"identityKey":"YOUR_IDENTITY_KEY","network":"testnet"}
Address: YOUR_ADDRESS
Wallet network: testnet
Balance: {"totalSatoshis":985000,"totalOutputs":0,"spendableSatoshis":985000,"spendableOutputs":0}The Wallet network line comes from BSV Desktop, so the page runs on testnet.
Each call to createWallet creates a new WalletClient and asks the wallet for the identity key again, so an app keeps one wallet object and calls pay() or getBalance() on it.
Next steps
With the page connected, use the wallet object in a guide, then look up its methods: