# BRC-100: Wallet Application Interface

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

The standard interface between an app and a wallet, where the app asks for an action, the wallet holds the keys and decides how to do it, and any compliant wallet can answer.

import WalletBoundary from '/snippets/WalletBoundary.jsx';
import SubstrateProbe from '/snippets/SubstrateProbe.jsx';

The Wallet Application Interface (BRC-100 (BSV 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](https://bsvblockchain.com/docs/wallets/bsv-desktop/), [BSV Browser](https://bsvblockchain.com/docs/wallets/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 (UTXOs (Unspent 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.

<WalletBoundary />

For `createAction`, the app sends a description and the outputs. The wallet asks the user to approve when its permissions require it, selects the coins, signs and broadcasts, unless your app must sign an input first, in which case it returns a signable transaction. For `getPublicKey` and `encrypt`, the wallet checks the permission for the protocol and derives the key. For `listOutputs`, it checks the permission for the basket and reads the outputs it tracks. The private key never leaves the wallet.

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 `originator` of 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](https://bsvblockchain.com/docs/reference/wallet-api/).

### 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 AtomicBEEF (Atomic 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.

<SubstrateProbe />

`WalletClient` asks `window.CWI`, the wallet wire on port 3301, the secure JSON API on port 2121, the JSON API on port 3321 and the React Native bridge in parallel, keeps the first of them that answers in that order, and asks XDM last.

### 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.CWI` (The 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 |
| XDM (Cross-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`:

```typescript roundtrip.mts
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 with `No wallet available over any communication substrate`.
- Replace `YOUR_APP_DOMAIN` with the domain name of your app, for example `localhost` while you develop. The `.mts` extension makes the script an ES module, which the top-level `await` needs, and `tsx` runs 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](https://bsvblockchain.com/docs/wallets/backup-recovery/).

## Related articles

To learn more about wallets and keys on the BSV blockchain, review these articles:

- [How your transaction worked](https://bsvblockchain.com/docs/concepts/how-your-payment-worked/)
- [Keys and identity](https://bsvblockchain.com/docs/concepts/keys-identity/)
- [Wallet API reference](https://bsvblockchain.com/docs/reference/wallet-api/)