BSV blockchainBSV blockchain

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 its package.json and @bsv/sdk installed. 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)
  • substrate picks the transport. The default, 'auto', finds the wallet for you.
  • originator is the name of your app, a hostname with an optional port such as example.com or localhost: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:

SubstrateWhere the wallet listens
window.CWIAn object injected into the browser page
Cicadahttp://localhost:3301, binary wire format
secure-json-apihttps://localhost:2121, JSON
json-apihttp://localhost:3321, JSON, where BSV Desktop answers
react-nativeThe 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:

connect.mjs
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)
  • isAuthenticated returns true when the user is signed in to the wallet.
  • getNetwork returns testnet or mainnet, 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.mjs

Your 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…aaaaaaaa

Network: 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:

GroupMethodsUse them to
ActionscreateAction, signAction, abortAction, listActions, internalizeActionCreate transactions, sign them in two steps, list past ones and accept incoming payments
OutputslistOutputs, relinquishOutputList the outputs the wallet tracks for your app, by basket, and stop tracking one
Keys and cryptographygetPublicKey, revealCounterpartyKeyLinkage, revealSpecificKeyLinkage, encrypt, decrypt, createHmac, verifyHmac, createSignature, verifySignatureDerive keys, encrypt and sign data with keys the app never sees
Certificates and identityacquireCertificate, listCertificates, proveCertificate, relinquishCertificate, discoverByIdentityKey, discoverByAttributesHold identity certificates, reveal some of their fields and find other users
Session and chainisAuthenticated, waitForAuthentication, getHeight, getHeaderForHeight, getNetwork, getVersionCheck 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: