# Build a wallet

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

Follow the path for building a BRC-100 wallet: the interface, wallet-toolbox, storage, permissions, conformance tests and backend services.

import BlueTable from '/snippets/BlueTable.jsx';

Follow the six stages below to build a BRC-100 (BSV Request for Comments 100, the standard interface between apps and wallets) wallet on `@bsv/wallet-toolbox`, from the interface to the backend services.

A BRC-100 wallet answers the requests of apps. Apps call methods such as `createAction` through BRC-100, and the wallet carries them out. It holds the keys, chooses the coins, signs, stores its outputs and checks permissions.

[BSV Desktop](https://bsvblockchain.com/docs/wallets/bsv-desktop/) and [BSV Browser](https://bsvblockchain.com/docs/wallets/bsv-browser/) are two of these wallets. Both are built on `@bsv/wallet-toolbox`, the TypeScript reference implementation. Build a wallet when you make a wallet product, a wallet-like service or a port to another language. If your app only uses a wallet, start from the [SDKs overview](https://bsvblockchain.com/docs/sdk/) instead.

## The path to a BRC-100 wallet

Each stage below builds on the one before it, from the interface your wallet answers to the servers it can run on.

### Learn the interface

Start with [BRC-100 Wallet Interface](https://bsvblockchain.com/docs/concepts/wallet-model/). It lists the method groups, the two ways `createAction` can end (an immediate action, or a `signableTransaction` that the app finishes with `signAction`) and the difference between labels, tags and baskets. An app written against BRC-100 expects those exact results from your wallet, without knowing which wallet answers.

### Start from wallet-toolbox

`@bsv/wallet-toolbox` connects the `@bsv/sdk` primitives to the parts a wallet needs. This page was written against `@bsv/wallet-toolbox` 2.14.

<BlueTable>

| Part | What it does |
| --- | --- |
| `Wallet` | Implements the BRC-100 methods |
| `WalletStorageManager` and storage providers | Keep the wallet's records in an active store, with optional backup stores |
| `WalletSigner` | Brings the wallet's keys into the SDK signing flow |
| Key managers | Derive keys with BRC-42 (BSV Key Derivation Scheme) and BRC-43 (Security levels, protocol IDs, key IDs and counterparties), manage privileged keys and run Shamir-based recovery |
| `Services` | Connect the wallet to broadcast, chain tracking and proof lookup |
| `Monitor` | Tracks confirmations, gathers Merkle proofs and rebroadcasts stalled transactions in the background |
| `WalletPermissionsManager` | Checks permissions around wallet methods |
| `MockChain` | Runs wallet tests without a live network |

</BlueTable>

The `Setup` class builds a wallet with its storage, services and monitor in one call, and the object it returns exposes each part so you can inspect or replace it. [Send a payment from a server](https://bsvblockchain.com/docs/get-started/quick-start-server/) builds a wallet this way on testnet, with `Setup.createWalletSQLite`.

### Choose the platform and storage

The toolbox ships in three packages, one per platform, and each supports different storage:

<BlueTable>

| Package | Platform | Storage |
| --- | --- | --- |
| `@bsv/wallet-toolbox` | Node.js | SQLite, MySQL or another database that Knex supports |
| `@bsv/wallet-toolbox-client` | Browser | IndexedDB on the device, or remote |
| `@bsv/wallet-toolbox-mobile` | React Native | Remote |

</BlueTable>

Remote storage keeps the records on a Wallet Infra server that the wallet calls over HTTPS. The records hold the derivation data of each output, so recovering a wallet needs both the root key material and these records. A seed alone cannot rebuild every output.

### Add permissions

`WalletPermissionsManager` sits in front of the wallet and decides what each app may do. A spending authorization covers an amount: the app can spend until it reaches that amount, and then the wallet asks the user again. Permission modules take over the protocols, baskets and labels reserved by BRC-98 (P Protocols, the wallet permission scheme for protocols), BRC-99 (P Baskets, the wallet permission scheme for baskets) and BRC-111 (P Labels, the wallet permission scheme for action labels), so a module can add its own rules for one kind of asset. For example, `@bsv/btms-permission-module` lets the spend prompt show a token's value, such as \$1.00 USD, instead of the 1 satoshi (The smallest unit of BitcoinSV (BSV). 100,000,000 satoshis make 1 BSV.) that typically funds the token output.

### Test conformance

The ts-stack repository turns BRC-100 behavior into JSON test vectors, each with its inputs and the expected outputs, under [`conformance/vectors/wallet/brc100/`](https://github.com/bsv-blockchain/ts-stack/tree/main/conformance/vectors/wallet/brc100). A wallet in any language reads the same files and compares its own results. Coverage is strongest for the deterministic crypto and key methods. Stateful cases carry an explicit classification instead of counting as passes, so a vector count alone does not prove a wallet passes every case.

The same vectors are how a port proves it matches the TypeScript reference. [go-wallet-toolbox](https://github.com/bsv-blockchain/go-wallet-toolbox) and [py-wallet-toolbox](https://github.com/bsv-blockchain/py-wallet-toolbox) bring the toolbox to Go and Python, and the [porting guide](https://github.com/bsv-blockchain/ts-stack/blob/main/conformance/PORTING_GUIDE.md) covers aligning another language.

### Run the backend services

Two ts-stack servers run only when the wallet needs them:

- Wallet Infra serves the toolbox storage over JSON-RPC, backed by MySQL, with mutual authentication and records scoped to each user. Wallets reach it with `StorageClient`. Run it to host remote storage for many wallet clients.
- The WAB (Wallet Authentication Backend) verifies a user's phone number with a one-time code and returns the user's presentation key (A 256-bit key the WAB gives back after the phone check. It is one of three factors, with the password and a recovery key, and any two of them unlock the wallet). On a new device, the wallet combines that key with the user's password to unlock the root key, and the WAB never sees the password. It can also keep optional recovery shares and pay new users a one-time faucet. Phone verification is the only sign-in method it offers for real users today, so run it when your wallet offers phone sign-in and recovery.

[Run a wallet backend](https://bsvblockchain.com/docs/wallet-dev/infrastructure/) runs both services on testnet and connects a wallet to each.

## Related articles

To learn more about building a BRC-100 wallet, review these articles:

- [BRC-100 Wallet Interface](https://bsvblockchain.com/docs/concepts/wallet-model/)
- [Run a wallet backend](https://bsvblockchain.com/docs/wallet-dev/infrastructure/)
- [Send a payment from a server](https://bsvblockchain.com/docs/get-started/quick-start-server/)
- [BSV Desktop](https://bsvblockchain.com/docs/wallets/bsv-desktop/)