Connect to a wallet with WalletClient
Connect a Node.js script to BSV Desktop with WalletClient, confirm that the wallet answers on testnet, and read its identity key. Use WalletClient when your app asks the user’s wallet to create transactions, sign data or show keys, so that your code never holds a private key. The same class runs in a browser and in Node.js, and it calls any wallet that implements BRC-100The standard set of methods an app calls on a user's wallet. The example runs standalone, with read only calls that spend nothing. This page was written against @bsv/sdk 4.0.1 and Node.js 24.
Before you begin
You need:
-
Node.js 22 or newer, and a project with
"type": "module"in itspackage.jsonand@bsv/sdkinstalled. See Install the SDK in Node or React. To install the version this page was written against, run this in the project folder:npm install @bsv/sdk@4.0.1 -
BSV Desktop open and set to testnet. To set it up, follow Set up a testnet wallet in the Quick Start.
How it works
WalletClient holds no keys, the wallet does (see BRC-100: Wallet Application Interface). Each method you call, such as getPublicKey, travels to the wallet over a substrate, the transport between your code and the wallet, and the wallet answers or asks the user to approve. The constructor takes two values:
new WalletClient(substrate, originator)substratepicks the transport. The default,'auto', finds the wallet for you.originatoris the name of your app, a hostname with an optional port such asexample.comorlocalhost:8080. The wallet shows it when it asks the user to approve a request, and stores every permission of your app under it. In a browser, the page origin is sent instead. In Node.js you must pass it, since a script has no origin of its own.
The constructor does not connect. With 'auto', the first method call tries these substrates at the same time, waits up to 1 second for each, and keeps the first one that answers, in this order:
| Substrate | Where the wallet listens |
|---|---|
window.CWI | An object injected into the browser page |
Cicada | http://localhost:3301, binary wire format |
secure-json-api | https://localhost:2121, JSON |
json-api | http://localhost:3321, JSON, where BSV Desktop answers |
react-native | The React Native WebView bridge |
If none answers, WalletClient tries XDM, a postMessage bridge to a parent window that holds the wallet, for 200 milliseconds. Every later call reuses the substrate that answered.
Connect to BSV Desktop
Write a script that calls five read only wallet methods, then run it. Create connect.mjs in your project folder:
The script prints the identity key of your wallet. The key is public, but it links your activity across apps, so do not paste the key of a wallet you use in shared logs or issues.
Write the script
Create the client with the default substrate and localhost as the originator, then read the session, the network, the wallet version, the block height and the identity key:
import { WalletClient } from '@bsv/sdk'
const wallet = new WalletClient('auto', 'localhost')
const { authenticated } = await wallet.isAuthenticated()
const { network } = await wallet.getNetwork()
const { version } = await wallet.getVersion()
const { height } = await wallet.getHeight()
const { publicKey } = await wallet.getPublicKey({ identityKey: true })
console.log('Authenticated:', authenticated)
console.log('Network:', network)
console.log('Wallet version:', version)
console.log('Block height:', height)
console.log('Identity key:', publicKey)isAuthenticatedreturnstruewhen the user is signed in to the wallet.getNetworkreturnstestnetormainnet, the network the wallet is set to. Check it before you create transactions, so that your app does not send coins on the wrong network.getPublicKey({ identityKey: true })returns the public identity key of the wallet, a 66 character hexadecimal string that identifies the user to other apps. It is public and safe to share.
Run the script
Run it from the project folder, with BSV Desktop open:
node connect.mjsYour height and identity key differ. The key shown is a placeholder:
Authenticated: true
Network: testnet
Wallet version: wallet-brc100-1.0.0
Block height: 1768236
Identity key: 02aaaaaa…aaaaaaaaNetwork: testnet confirms that the script reached BSV Desktop on the network the examples on this site use. In this run, 'auto' connected over json-api, the HTTP port of BSV Desktop.
Choose a substrate
To skip the discovery, pass the name of a substrate instead of 'auto'. The client then connects only over that transport:
const wallet = new WalletClient('json-api', 'localhost')Keep 'auto' for an app that runs where you do not control which wallet the user has, such as a public web page. Name the substrate in a script or a test that always talks to the same wallet, such as BSV Desktop over json-api. You can also pass a substrate object, for example new WalletClient(new XDM('https://wallet.example')), with XDM imported from @bsv/sdk, to accept messages from that wallet origin only.
Call BRC-100 methods
WalletClient has the 28 methods of BRC-100. Each one takes one object of arguments and returns a promise:
| Group | Methods | Use them to |
|---|---|---|
| Actions | createAction, signAction, abortAction, listActions, internalizeAction | Create transactions, sign them in two steps, list past ones and accept incoming payments |
| Outputs | listOutputs, relinquishOutput | List the outputs the wallet tracks for your app, by basket, and stop tracking one |
| Keys and cryptography | getPublicKey, revealCounterpartyKeyLinkage, revealSpecificKeyLinkage, encrypt, decrypt, createHmac, verifyHmac, createSignature, verifySignature | Derive keys, encrypt and sign data with keys the app never sees |
| Certificates and identity | acquireCertificate, listCertificates, proveCertificate, relinquishCertificate, discoverByIdentityKey, discoverByAttributes | Hold identity certificates, reveal some of their fields and find other users |
| Session and chain | isAuthenticated, waitForAuthentication, getHeight, getHeaderForHeight, getNetwork, getVersion | Check the wallet state and read block headers |
A method that spends coins, such as createAction, opens an approval request in the wallet, and the promise waits until the user answers. A payment the user approves is broadcast and cannot be reversed. To send a payment with createAction, follow Send your first payment in the Quick Start. For the arguments and results of every method, see the BRC-100 wallet standard.
Troubleshooting
Script fails with "No wallet available over any communication substrate" #
The full message is No wallet available over any communication substrate. Install a BSV wallet today!. WalletClient with 'auto' found no wallet on any substrate. Open BSV Desktop and unlock it, then run the script again. In Node.js, the same message appears when the constructor has no originator, even with BSV Desktop open, because every HTTP substrate refuses the call. Pass a name as the second argument, such as new WalletClient('auto', 'localhost').
Script fails with "originator is required when using the HTTP substrate in Node.js" #
A client with a named HTTP substrate, such as new WalletClient('json-api'), was created without an originator in Node.js. Pass the name of your app as the second argument, such as new WalletClient('json-api', 'localhost').
Constructor fails with "The originator parameter must be a canonical DNS hostname" #
The originator holds more than a hostname and a port, such as https://my.app or a path. Pass the hostname alone, with an optional port, such as my.app or localhost:8080.
Next steps
With the wallet connected, set up the permissions of your app or let users log in with their wallet: