Connecting a wallet
How an app connects to a person's BSV wallet: what it can ask for, how little to ask for, and how the wallet knows who is asking.
Connecting is the moment an app asks a person's wallet to act for it. We recommend the Wallet Application Interface as the default way to connect, with each feature asking for the least it needs.
On BSV, an app never holds the user's keys. It asks the wallet to do things for it: create a payment, sign a message, prove an attribute. The wallet decides whether to allow each request, does the work and returns the result.
The Wallet Application Interface (BRC-100) is the standard way for apps and wallets to talk. Any wallet that implements it works with any app that uses it. An app built once works with BSV Desktop, BSV Browser and other compatible wallets, with no custom integration.
Naming
"Wallet Application Interface" is the name of the thing. "BRC-100" is the number of the proposal that specifies it, and belongs in a citation, not a sentence. In an interface, the string people see is Connect wallet.
This page covers the connect moment: how the connection works, what to ask for and how the wallet knows who is asking. What the app holds afterwards has its own page. The guardrails here come from an independent risk assessment of the interface (BRC-151).
How it works
The app calls a wallet method, such as "create this transaction" (createAction) or "give me a public key" (getPublicKey). The request travels to the user's wallet:
- On desktop, the app talks over a local connection to a wallet running on the same computer, such as BSV Desktop.
- On mobile, the app runs inside a wallet's built-in browser, such as BSV Browser, which passes requests to the native wallet.
Installed desktop and phone apps reach the wallet differently again, and cannot prove their name the way a website can. Web apps and native apps covers each platform.
Either way, the keys stay in the wallet. The app sees only results: a signed transaction, a signature, a key, a proof.
Every request carries the requesting app's domain. The wallet uses it to decide which permissions apply and to show the user who is asking.
The app never needs to know which wallet the user has.
Do
Write the connect flow around "your wallet". Name a specific wallet only when helping somebody install one.
What apps can ask for
The interface is broad. An app can ask the wallet to:
- create, sign and list transactions, and import incoming ones
- list and manage the outputs it tracks, grouped into named baskets
- provide public keys, encrypt and decrypt, and create signatures
- request, prove and discover Passes (see Identity)
- reveal the link between keys, for audits
That breadth is the main design risk. The risk assessment puts it plainly: money, permissions, history, identity and Passes can all pass through one wallet. That makes the wallet a high-value target and a control point over much of a person's digital life. The answer is to use as little of the interface as each feature needs.
Ask for the minimum
Before you design a permission prompt, decide what your product needs. Sort every capability into one of three groups:
- Required. The product cannot do its core job without it.
- Optional. It adds convenience but is not essential.
- Not used. It adds more risk than value, so the app never asks for it.
Typical minimum profiles:
| Product | Needs | Should not ask for |
|---|---|---|
| Payment-only app | Create a payment, confirm receipt | Root identity key, Passes, transaction history, key linkage |
| Token app | One protocol and one basket for its token | Unrelated outputs |
| Login | A key derived for this app only | The wallet's root identity key |
| Regulated service | One specific Pass field | Anything beyond that field |
| AI agent | A small budget in its own wallet | The owner's main wallet or identity |
Do
Request each permission when the user first uses the feature that needs it.
Don’t
Bundle every permission into one approval screen during onboarding.
After the connection
Connecting gives the app nothing on its own. Every capability it uses afterwards is a separate grant: charging an allowance, reading one basket, reading one field of a Pass. The wallet holds each grant for that app, shows it to the user and lets them take it back.
Permissions and allowances covers how to word those prompts, how to size an allowance and what the permissions dashboard shows. Signing in covers recognising a returning user.
Verify who's asking
The app's domain is useful only if the wallet confirms the request really came from it. A browser fills the domain in itself; an installed app states its own, so only the first can be shown as checked (see Who is asking). If you build a wallet, defend against:
- forged domain values
- malicious local requests
- lookalike and internationalised domains
- development settings left on in production
Do
Warn the user and ask for approval again when an app's domain or certificate changes unexpectedly.
Disclose what you use
An exposure statement tells reviewers and users what your product touches. Publish one, and keep it current.
Do
Publish an exposure statement for your app: the wallet methods you call, the protocols and baskets you use, whether you request the identity key or Passes, what wallet data you keep, and whether agents can act through your app.
Do
If you build a wallet, publish one for the wallet too: what is allowed automatically, how apps are kept apart, where data is stored, what a full backup contains, and whether users can move funds without your service.
If your product is both an app and a wallet, publish the two statements separately.
Open questions
- Do people expect connecting to give the app access to their money, when it gives nothing until the app asks?
- Should the connect button change when the app can tell a wallet is present, or stay "Connect wallet" for everyone?
- Does anybody other than reviewers read an exposure statement, and where should an app link to it?
- How should a wallet tell somebody that an app they trusted now answers from a different domain?
Related
- Connected web app: a whole site built on this pattern, from connecting to signing in and holding a ticket
- Permissions and allowances: prompts, allowances, the dashboard and revoking
- Web apps and native apps: how websites, desktop apps and phone apps each reach the wallet
- Signing in: recognising a returning user with an app-specific key
- Errors and failed payments: no wallet installed, permission refused and the rest
- Wallet setups: operating, reserve and agent wallets
- Identity: identity keys and Passes
- Backups: why a connected wallet's backup needs more than recovery words
- Legacy compatibility: apps that do not use the interface
Written from: BRC-100, BRC-151, ts-stack architecture docs.
Checklist
The rules on this page, in a form you can work through.
6 rules