BRC-100: Wallet Application Interface
The Wallet Application Interface (BRC-100BSV Request for Comments 100, the standard interface between apps and wallets) is the interface between your app’s code and a wallet’s code. A full BRC-100 wallet exposes the same 28 methods, so the same app code works with BSV Desktop, BSV Browser or a wallet inside your own server. Read this before your app calls a wallet. By the end, you know how a request reaches the wallet and have run one script that makes the same calls to a wallet inside your process and to the user’s wallet.
Why your app does not hold the key
A wallet holds keys and signs transactions. It does not hold coins, since the coins are unspent outputs (UTXOsUnspent transaction output) on the blockchain that its keys can spend. In BRC-100 the wallet does the work that needs a key, and your app asks.
The diagram follows a request from your app to the wallet. Select a call and press Play to see which of the wallet’s steps use the key.
The app asks for a transaction: a description and the outputs it wants.
0 of 6. The app asks for a transaction: a description and the outputs it wants.
What this means for your app:
- The wallet derives keys, signs, encrypts and decrypts, and it selects the coins, sets the fee and broadcasts. When the wallet is a separate application, the private key never reaches your app, so a bug or a leak in your app cannot expose it, and your app does not track outputs.
- Permissions are applied by the wallet, which uses the
originatorof each request to decide whether to ask the user. In BSV Desktop, a spend waits for Authorize in the Spending Request. - The user can change wallet without your app changing, since the two sides only share the interface.
What your app can ask a wallet to do
A BRC-100 wallet answers a fixed set of methods, grouped by what they do.
The five groups of methods
| Group | Purpose | Methods |
|---|---|---|
| Actions | Build and manage transactions | createAction, signAction, abortAction, listActions, internalizeAction |
| Outputs | Query and release tracked outputs | listOutputs, relinquishOutput |
| Keys and crypto | Keys, signing and encryption | getPublicKey, encrypt, decrypt, createHmac, verifyHmac, createSignature, verifySignature, revealCounterpartyKeyLinkage, revealSpecificKeyLinkage |
| Certificates | Identity certificates | acquireCertificate, listCertificates, proveCertificate, relinquishCertificate, discoverByIdentityKey, discoverByAttributes |
| Wallet state | Authentication, chain and wallet information | isAuthenticated, waitForAuthentication, getHeight, getHeaderForHeight, getNetwork, getVersion |
The parameters and results of each method are in the Wallet API reference.
What createAction can return
createAction is how an app asks for a transaction, which BRC-100 calls an action. The result depends on who has to sign:
| Outcome | What the app receives | What happens next |
|---|---|---|
| Immediate action | A txid and the transaction as an AtomicBEEFAtomic BEEF (BRC-95): one transaction packaged with the proofs of its ancestors in tx | The wallet funded, signed and processed the transaction. |
| Signable action, when the request spends an output the wallet does not control, such as one locked to a key your app holds | Only signableTransaction: { tx, reference }, with the transaction in tx | Your app signs the inputs it controls, then calls signAction({ reference, spends }) with the unlocking script of each input. The wallet adds its signatures and returns the txid. |
Labels, tags and baskets
Three different indexes group what the wallet tracks, and they are not interchangeable:
| Concept | Applies to | Used by |
|---|---|---|
| Labels | A whole action | createAction, listActions |
| Tags | One output | createAction, listOutputs |
| Baskets | A named group of outputs | listOutputs, internalizeAction |
How a request reaches the wallet
Where the wallet runs decides the channel your request takes: a computer, a phone or your own server.
The diagram shows what WalletClient('auto') does on its first call. Switch a substrate on to mark that a wallet answers there, then press Play to see which one it keeps. Select Only XDM to see the last resort, or None to see the call fail.
Switch a substrate on to say that a wallet answers there. WalletClient asks the first five at once and gives each up to 1 s.
Switch a substrate on to say that a wallet answers there. WalletClient asks the first five at once and gives each up to 1 s.
How an app finds the wallet
BRC-100 defines the methods, not the channel that carries them. A wallet reaches your app over a substrate. WalletClient from @bsv/sdk supports these:
| Substrate | Where the wallet is | Address |
|---|---|---|
window.CWIThe wallet injects a window.CWI object into the page | In the same browser | Not applicable |
| Wallet wire | A wallet on the user’s machine, over a binary protocol | http://localhost:3301 |
| Secure JSON API | A wallet on the user’s machine, over JSON and HTTPS | https://localhost:2121, named secure-json-api |
| JSON API | A wallet on the user’s machine, over JSON | http://localhost:3321, named json-api |
| React Native WebView | A native wallet that embeds the web app, such as BSV Browser | A postMessage bridge |
| XDMCross-document messaging | A wallet in another frame or window | Cross-document postMessage |
In @bsv/sdk 4.x, new WalletClient('auto', 'YOUR_APP_DOMAIN') does not connect to a wallet until the first call. On that call it asks every substrate except XDM for getVersion in parallel and waits up to one second. It keeps the first one that answers, in the order of the table, and asks XDM last, with a 200 ms wait. When none answers, the call fails with No wallet available over any communication substrate.
The second argument is the originator, the domain name of your app, with an optional port and without a scheme or a path. WalletClient sends it with every method. You can also name one substrate, for example new WalletClient('json-api', 'YOUR_APP_DOMAIN'), or pass any object that implements the interface.
Desktop and phone
On a computer, WalletClient reaches a wallet such as BSV Desktop through a localhost port. On a phone, BSV Browser embeds the web app and exposes the same methods through a bridge. Only the substrate changes, so the same app code works on both.
Where the wallet runs
The interface does not say where the wallet is. It can be a separate application, as above, or an object in your own process, such as a server wallet built with @bsv/wallet-toolbox. In that case your process holds the key. The app and the wallet are the same program.
ProtoWallet in @bsv/sdk is not a full wallet. It holds one private key and implements only the nine methods of the keys and crypto group, so it cannot build a transaction.
The key in this script exists only while it runs. Never paste a real private key into code or commit one.
To try it, save this standalone script as roundtrip.mts, install the packages with npm install @bsv/sdk tsx and run it with npx tsx roundtrip.mts. It was written against @bsv/sdk 4.x, and the function takes any wallet that has encrypt and decrypt:
import { WalletClient, ProtoWallet, PrivateKey } from '@bsv/sdk'
import type { WalletInterface } from '@bsv/sdk'
async function roundTrip(wallet: Pick<WalletInterface, 'encrypt' | 'decrypt'>) {
const args = { protocolID: [1, 'demo app'] as [1, string], keyID: '1', counterparty: 'self' }
const { ciphertext } = await wallet.encrypt({ ...args, plaintext: [1, 2, 3] })
const { plaintext } = await wallet.decrypt({ ...args, ciphertext })
return plaintext
}
const inProcess = new ProtoWallet(PrivateKey.fromRandom())
console.log(await roundTrip(inProcess))
const userWallet = new WalletClient('auto', 'YOUR_APP_DOMAIN')
console.log(await roundTrip(userWallet))- The first call prints
[ 1, 2, 3 ], with a key generated for the run. - The second call needs a BRC-100 wallet running, such as BSV Desktop, and the wallet may ask the user to approve the request. It prints
[ 1, 2, 3 ]too. When no wallet answers, it rejects withNo wallet available over any communication substrate. - Replace
YOUR_APP_DOMAINwith the domain name of your app, for examplelocalhostwhile you develop. The.mtsextension makes the script an ES module, which the top-levelawaitneeds, andtsxruns the TypeScript.
What BRC-100 does not cover
BRC-100 standardizes how an app talks to a wallet. It does not define how a wallet recovers from a lost key or a dead device. That is the wallet’s own job, and the wallet has to keep the recoverable keys and the records that go with them, such as the derivation data and the output history. Link to the recovery controls of the user’s wallet instead of backing up wallet data in your app. Never collect wallet secrets. For BSV Desktop, see Back up and recover a wallet.
Related articles
To learn more about wallets and keys on the BSV blockchain, review these articles: