---
name: bsv-wallet-connection
description: "Design or implement how an app connects to a user's BSV wallet and asks it to pay, sign or prove something: the connect step, permission prompts, spending allowances, sign-in with an app-specific key, presenting a Pass, and revocation. Use when asked to 'add wallet connect', 'design the permission prompt', 'implement BRC-100', 'ask for a spending allowance', 'sign in with a wallet', 'ask for proof of age', or anything about an app talking to a BSV wallet."
---

> Start from [bitcoinsv-design](../bitcoinsv-design/SKILL.md). Shared states, labels, errors, amounts and fees: [shared patterns](../bitcoinsv-design/references/shared-patterns.md).

# Connect an app to a BSV wallet

**Scope:** Everything an app asks of a user's wallet through the Wallet Application Interface, and how those asks are presented and taken back.

**Does NOT cover:**

- Building and signing transactions: see [bsv-actions](../bsv-actions/SKILL.md)
- Paying people and handles: see [bsv-payments](../bsv-payments/SKILL.md)
- Charging per use: see [bsv-micropayments](../bsv-micropayments/SKILL.md)
- Software spending on its own: see [bsv-agent-spending](../bsv-agent-spending/SKILL.md)

**Cross-references:** [bsv-actions](../bsv-actions/SKILL.md), [bsv-micropayments](../bsv-micropayments/SKILL.md), [bsv-agent-spending](../bsv-agent-spending/SKILL.md), [shared patterns](../bitcoinsv-design/references/shared-patterns.md).

On BSV an app never holds the user's keys. It asks the wallet to act, the wallet shows the user who is asking and decides, and the app only ever sees results. The standard for that conversation is the Wallet Application Interface (BRC-100); in an interface the words on the button are **Connect wallet**. Every request carries the app's domain, which is how the wallet knows which permissions apply and whose name to show.

## ALWAYS

- Make a ticket valid at the door from the token alone, so it still works after Anna deletes her data or removes the site from her wallet. _([costs money](https://www.bitcoinsv.design/guide/rule/4740a3dd92/))_
- Request each permission when the user first uses the feature that needs it. _([costs trust](https://www.bitcoinsv.design/guide/rule/5d5c53b7cd/))_
- Show the app's name from its manifest beside its verified domain in every prompt, and the domain alone when the app has no manifest. _([costs trust](https://www.bitcoinsv.design/guide/rule/2dc3c0d133/))_
- Cap an allowance per payment, per hour and per day as well as per month, where the wallet supports it, and show every cap in the same prompt. _([costs trust](https://www.bitcoinsv.design/guide/rule/7b093f1075/))_
- Ask the user again when an amount is unusually high, the recipient is new, the payment pattern changes, an allowance that has ended would start again, or the app asks for a new protocol, basket, Pass field, the identity key or key linkage. _([costs trust](https://www.bitcoinsv.design/guide/rule/aad955fa0f/))_
- Make a revoke take effect at once, and say what stops working: "The Satoshi Vision can no longer charge you. It will ask again when you next open an article." _([costs trust](https://www.bitcoinsv.design/guide/rule/2ed9e55238/))_

## NEVER

- Show an amount taken from the app's description text. Show the amount from the request itself, and warn if the two disagree. _([costs money](https://www.bitcoinsv.design/guide/rule/b50f273390/))_
- Let an AI agent approve key linkage, share a Pass, or widen its own permissions. _([costs money](https://www.bitcoinsv.design/guide/rule/be5632560c/))_
- Let an installed app that claims a website's name inherit the permissions or allowances already granted to that website. _([costs money](https://www.bitcoinsv.design/guide/rule/62eac939c1/))_
- Offer an unlimited allowance. There is no amount of convenience that justifies it, and a product offering it will have users who accepted it without reading. _([costs money](https://www.bitcoinsv.design/guide/rule/7c371b8b5e/))_
- Bundle every permission into one approval screen during onboarding. _([costs trust](https://www.bitcoinsv.design/guide/rule/09052402ed/))_
- Preselect broad permissions, describe a permission as less than it is, or show a refused prompt again until the user gives in. All three teach people to tap Allow without reading. _([costs trust](https://www.bitcoinsv.design/guide/rule/a4593d9103/))_

## Patterns

_Design guidance in each pattern comes from the guide page it cites. Method names, arguments and code are implementation notes checked against `@bsv/sdk` 4.0.0._

### 1. Connect, asking for the minimum

**When:** The first time the app needs the wallet.

**How:**

1. Sort every capability the app could use into required, optional and not used. A payment-only app needs to create a payment and confirm receipt, and should never ask for the root identity key, Passes, transaction history or key linkage.
2. Construct a `WalletClient('auto', '<your domain>')` and check `isAuthenticated()`. The app does not need to know which wallet the user has.
3. Ask for nothing at connect time beyond connecting. Each permission is requested by the wallet when the app first calls the method that needs it, which is when the user can see why.
4. Label the control **Connect wallet**. Name a specific wallet only when helping somebody install one.

**Fallback:** No wallet answers: offer to help install one, naming BSV Desktop for desktop and BSV Browser for mobile, and keep the rest of the app usable without it.

**Error states:**

- **The user declines a permission:** Say what the app cannot do without it, and offer to ask again when they next use that feature. Never re-prompt in a loop.

_Source: [Connecting a wallet](https://www.bitcoinsv.design/guide/patterns/connecting-a-wallet/)_

### 2. Ask for a spending allowance

**When:** The app charges more than occasionally: per article, per request, per game.

**How:**

1. Describe the consequence, not the mechanism: "Let The Satoshi Vision charge you up to 500 sats a day for articles. You can stop this at any time."
2. Keep it small, short-lived and capped per payment as well as per hour, day and month. A monthly cap alone lets an app spend the month at once.
3. Expire it by default; indefinite access should be an unusual, explicit choice. Never offer an unlimited allowance.
4. Ask again when the amount is unusually high, the recipient is new, the pattern changes, the allowance renews, or the app wants a new protocol, basket, Pass or key linkage.

**Error states:**

- **The allowance is used up:** Show it in activity as an event, and ask before continuing rather than failing silently.

_Source: [Permissions and allowances](https://www.bitcoinsv.design/guide/patterns/permissions-and-allowances/)_

### 3. Sign in with an app-specific key

**When:** The app needs to recognise a returning user.

**How:**

1. Ask for a key derived for your app with `getPublicKey({ protocolID, keyID })`, not the wallet's root identity key. A leaked database of app keys cannot be matched to the same person elsewhere.
2. Only request the root identity key (`getPublicKey({ identityKey: true })`) when you can say why an app-specific key will not work.

```ts
import { WalletClient } from "@bsv/sdk";

const wallet = new WalletClient("auto", "example.com");
const { publicKey } = await wallet.getPublicKey({
  protocolID: [2, "example login"],
  keyID: "1",
});
```

_Source: [Signing in](https://www.bitcoinsv.design/guide/patterns/signing-in/)_

### 4. Ask for one fact with a Pass

**When:** The app needs proof of an attribute: over 18, a member, a verified business.

**How:**

1. Ask for the single field you need. A certificate (BRC-52, shown to users as a Pass) can be revealed selectively.
2. Call `proveCertificate({ certificate, fieldsToReveal, verifier })` with only that field. The prompt should read: "Send Example Bar proof that you are over 18. Your name and date of birth won't be shared."
3. Give the request its own confirmation, outside any bundle, naming who is asking and what they will see.

**Fallback:** The user has no suitable Pass: say where one can be obtained, and design so a missing Pass is the exception, not a wall.

_Source: [Signing in](https://www.bitcoinsv.design/guide/patterns/signing-in/)_

### 5. Let people see and take it back

**When:** You are building the wallet side, or a settings screen that shows connections.

**How:**

1. Give one place listing every connected app: verified name and domain, what it can do, limits and what has been used, expiry, last use, and a revoke button.
2. Make revoking immediate and say what it breaks: the app stops working until it asks again. Revoking one app must never affect access to funds.
3. Warn and ask again if an app's domain or certificate changes unexpectedly.

_Source: [Permissions and allowances](https://www.bitcoinsv.design/guide/patterns/permissions-and-allowances/)_

## All the rules

`references/rules.md`: 86 rules from 9 pages, 38 of them costly, most costly first.
Every rule in the guide, most costly first: https://www.bitcoinsv.design/api/rules.json

## Implementation resources

- **[@bsv/brc100-ui-react-components](https://github.com/bsv-blockchain/brc100-ui-react-components)**: React components the reference wallets use for permission prompts: ProtocolPermissionHandler, SpendingAuthorizationHandler, BasketAccessHandler, CertificateAccessHandler, GroupPermissionHandler and AccessAtAGlance.
- **[WalletPermissionsManager (Wallet Toolbox)](https://github.com/bsv-blockchain/wallet-toolbox)**: For wallet builders: per-app, per-protocol permission control with grouped approval flows. Limits enforced here are enforced by the wallet, outside anything an app or agent can change.
- **[@bsv/sdk](https://bsv-blockchain.github.io/ts-sdk/)**: The TypeScript SDK: `WalletClient` for every BRC-100 call, `AuthFetch` for HTTP 402, transactions, scripts and BEEF. Source at github.com/bsv-blockchain/ts-sdk.
- **[Wallet Toolbox](https://github.com/bsv-blockchain/wallet-toolbox)**: The wallet side of the interface: storage, signing and `WalletPermissionsManager`. Start here if you are building a wallet rather than an app.
- **[BRCs](https://github.com/bsv-blockchain/BRCs)**: Every proposal the skills cite, by number.

---

_Generated from https://www.bitcoinsv.design/, Open BSV License Version 6. Rules are extracted from the guide's pages and cannot be out of date about what it says; the patterns may still need updating._