BSV blockchainBSV blockchain

Build a wallet with wallet-toolbox

Start a BRC-100BSV Request for Comments 100, the standard interface between apps and wallets wallet on @bsv/wallet-toolbox with its Setup helpers, then decide where the wallet keeps its records. At the end, you have a testnet wallet in Node.js with SQLite storage and a running Monitor, plus the calls that open a wallet with the same keys on remote storage or in a browser.

Before you begin

You need Node.js 22 or newer. The example runs on testnet with a new wallet that holds no coins, so it needs no funding. This page was written against @bsv/wallet-toolbox 2.15.1 and @bsv/wallet-toolbox-client 2.15.1, with @bsv/sdk 4.0.1.

How it works

The Setup class turns the keys in a .env file into a complete wallet:

  1. .env

    Testnet and Mainnet keys and placeholder API keys, written once by Setup.makeEnv()

  2. Setup.getEnv('test')

    Reads the testnet keys and sets the chain to testnet

  3. Setup.createWalletSQLite

    Builds the key deriver, the storage, the services and the Monitor, then the wallet

  4. setup

    The object your code uses: the wallet and every part behind it

The setup object it returns gives you each part by name:

FieldWhat you use it for
walletThe BRC-100 wallet. Your code and the apps call its methods, such as createAction and listOutputs
storageThe WalletStorageManager, which holds the active store and its backups and can switch between them
activeStorageThe StorageKnex provider that writes to the SQLite file
servicesThe Services the wallet uses on testnet to broadcast, track the chain and look up proofs
monitorThe MonitorThe toolbox component that broadcasts queued transactions, gathers proofs and repairs wallet state in the background. Setup creates it but does not start it
identityKey, keyDeriver, rootKeyThe keys from .env. identityKey is the public key that apps see
chain, userIdtest for testnet, and the ID of the wallet’s user record in the store

Create a testnet wallet

The first step is to create a Node.js project folder with the toolbox, the keys and a wallet that opens on SQLite:

Install the toolbox

In an empty folder, install @bsv/wallet-toolbox:

npm init -y
npm install @bsv/wallet-toolbox

The toolbox installs @bsv/sdk, Knex and SQLite with it, so the wallet needs no database server.

Keep the keys out of git

Add .gitignore to the project folder, so the keys and the wallet files never reach a repository:

.gitignore
.env
*.sqlite
node_modules

Generate the keys

The .env file holds the private keys of the wallet. Keep it private, never print it, paste it into code or commit it, and use this wallet only on testnet. The file also holds Mainnet keys that this page does not use. Anyone with this file can spend the coins of the wallet.

Setup.makeEnv() generates the keys. Save this script as create-env.mjs in the same folder, to write them to .env:

create-env.mjs
import { existsSync, writeFileSync } from 'node:fs'
import { Setup } from '@bsv/wallet-toolbox'

if (existsSync('.env')) {
  console.log('.env already exists, nothing was written.')
} else {
  writeFileSync('.env', Setup.makeEnv(), { mode: 0o600 })
  console.log('Wrote the test wallet keys to .env.')
}

Run it once with node create-env.mjs:

Wrote the test wallet keys to .env.
  • .env holds two testnet keys, two Mainnet keys and placeholder API keys. The wallet on this page uses the first testnet key.
  • { mode: 0o600 } lets only your user account read and write .env on Linux and macOS.
  • The script never prints the keys, and it does not replace an existing .env.

Open the wallet

Create wallet.mjs, a module that the other scripts import to open the wallet:

wallet.mjs
import { Setup } from '@bsv/wallet-toolbox'

process.loadEnvFile('.env')
const env = Setup.getEnv('test')

export const setup = await Setup.createWalletSQLite({
  env,
  filePath: './wallet.sqlite',
  databaseName: 'mywallet'
})
  • Setup.getEnv('test') reads the testnet keys and puts the wallet on testnet. test is the name the toolbox uses for testnet.
  • Setup.createWalletSQLite creates wallet.sqlite on the first run and sets up its tables. databaseName becomes the name of this store.

Check the wallet

Write check.mjs, which asks the wallet for its identity key, its network and its outputs:

check.mjs
import { setup } from './wallet.mjs'

const { wallet } = setup

const { publicKey } = await wallet.getPublicKey({ identityKey: true })
console.log('Identity key:', publicKey)

const { network } = await wallet.getNetwork({})
console.log('Network:', network)

const outputs = await wallet.listOutputs({ basket: 'default' })
console.log('Outputs:', outputs)

await wallet.destroy()

Run it with node check.mjs:

Identity key: 023d8dae...591b10
Network: testnet
Outputs: { totalOutputs: 0, outputs: [] }
  • default is the basketA named group of outputs the wallet tracks that holds the coins the wallet spends from. It is empty because the wallet is new.
  • destroy() closes the storage, so the script can end.

The wallet now answers BRC-100 calls on testnet and keeps its records in wallet.sqlite. To give a wallet like this its first coins, follow Fund the server wallet from BSV Desktop. It uses its own server-wallet.mjs module in place of wallet.mjs.

Start the Monitor

With the wallet open, start its Monitor, which finishes the work that wallet methods leave for later, such as delayed broadcasts and Merkle proofsThe proof that a transaction is in a block, checked against the block header. By default, createAction leaves the broadcast to the Monitor, so a wallet that sends transactions needs the Monitor running. A script that ends right away needs it too, unless it sends with acceptDelayedBroadcast: false.

Create monitor.mjs, which starts the Monitor and stops it cleanly on Ctrl+C:

monitor.mjs
import { setup } from './wallet.mjs'

const { wallet, monitor } = setup

const running = monitor.startTasks()
console.log('Monitor running. Press Ctrl+C to stop.')

process.once('SIGINT', async () => {
  monitor.stopTasks()
  await running
  await wallet.destroy()
  console.log('Monitor stopped.')
})
  • startTasks() runs the Monitor tasks on an interval until stopTasks() is called.
  • Stop the Monitor before destroy(), so no task writes to a closed store.

Run it with node monitor.mjs, and press Ctrl+C when you want it to stop:

Monitor running. Press Ctrl+C to stop.
Monitor stopped.

With the Monitor running, the wallet broadcasts its queued transactions and collects their proofs on its own. How the toolbox tracks UTXOs lists what each Monitor task does.

Choose the storage

Each Setup call opens a wallet with the same keys on a different store, with its own records. Pick the store by where the wallet runs:

For a wallet in Node.js, such as a server wallet or a desktop app. The records stay in a database you run, through Knex.

wallet.mjs above already uses SQLite:

const setup = await Setup.createWalletSQLite({ env, filePath: './wallet.sqlite', databaseName: 'mywallet' })

For MySQL, call Setup.createWalletMySQL({ env, databaseName }) instead. It reads the connection from MYSQL_CONNECTION in .env, a JSON string with the host, port, user and password, and the schema named by databaseName must already exist. Both calls go through Setup.createWalletKnex, which accepts any Knex instance in its knex argument.

For a wallet that keeps its records on a storage server and reaches it over HTTPS with StorageClient.

Save this as remote-wallet.mjs in the same project:

remote-wallet.mjs
import { Setup } from '@bsv/wallet-toolbox'

process.loadEnvFile('.env')
const env = Setup.getEnv('test')

const setup = await Setup.createWalletClient({
  env,
  endpointUrl: 'https://go-wallet-testnet-us-1.bsvblockchain.tech'
})

for (const store of setup.storage.getStores()) {
  console.log(store.storageClass, store.endpointURL)
}

await setup.wallet.destroy()

Run it with node remote-wallet.mjs:

StorageClient https://go-wallet-testnet-us-1.bsvblockchain.tech
  • endpointUrl here is a public testnet storage server, for trying remote storage. It must run on the same network as the wallet. Without endpointUrl, the call uses https://staging-storage.babbage.systems on testnet.
  • Production wallets run their own storage server, as Run a wallet backend describes.
  • The records live on the server, and the keys stay in .env on your machine.

For a wallet that runs in a browser and keeps its records on the user’s device.

Install the browser package in your web app:

npm install @bsv/wallet-toolbox-client

Then open the wallet with SetupClient.createWalletIdb:

wallet.js
import { SetupClient } from '@bsv/wallet-toolbox-client'

export async function openWallet (rootKeyHex) {
  return await SetupClient.createWalletIdb({
    chain: 'test',
    rootKeyHex,
    databaseName: 'mywallet'
  })
}

Open it in the browser and run the checks of check.mjs on the wallet it returns. In Chrome on testnet, with a new key, they print:

Identity key: 038524fd...50ba47
Network: testnet
Outputs: { totalOutputs: 0, outputs: [] }
  • A browser has no .env, so rootKeyHex comes from the key management of your wallet, such as a key the user unlocks. Never ship a key in the app bundle.
  • databaseName becomes the name of this store, as with SQLite. The records go to an IndexedDB database on the device named wallet-toolbox-testnet.

Whichever store you pick, the wallet methods stay the same. Some setup fields change with the store: createWalletClient returns endpointUrl and no activeStorage or userId, and the activeStorage of createWalletIdb is a StorageIdb.

The wallet needs its records to recover its outputs, since the keys in .env alone cannot rebuild them, so keep a backup store next to the active one. Plug in your own storage shows how to add one.

Next steps

With a working wallet, continue with how it handles its coins and its storage: