# Connect an app to a BSV wallet: every rule
Every do and don't the guide states on the pages behind this skill. The costly ones come first; the full list follows, grouped by page. Quote them; do not paraphrase them.
86 rules: 5 that can cost money, 33 that can cost trust, 48 standard.
## Start here
- **DON'T** _(Costs money)_ Show an amount taken from the app's description text. Show the amount from the request itself, and warn if the two disagree.
- **DON'T** _(Costs money)_ Let an AI agent approve key linkage, share a Pass, or widen its own permissions.
- **DON'T** _(Costs money)_ Let an installed app that claims a website's name inherit the permissions or allowances already granted to that website.
- **DO** _(Costs money)_ 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.
- **DON'T** _(Costs money)_ 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.
- **DO** _(Costs trust)_ Request each permission when the user first uses the feature that needs it.
- **DON'T** _(Costs trust)_ Bundle every permission into one approval screen during onboarding.
- **DON'T** _(Costs trust)_ 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.
- **DO** _(Costs trust)_ 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.
- **DON'T** _(Costs trust)_ Cancel a wallet request because the user has not answered yet. A timeout turns a user who was reading into an error.
- **DO** _(Costs trust)_ 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.
- **DO** _(Costs trust)_ 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.
- **DO** _(Costs trust)_ 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."
- **DO** _(Costs trust)_ Ask for key linkage fresh each time, name who receives it and what they learn, and keep a local record of what was revealed to whom.
- **DO** _(Costs trust)_ If you build a wallet, show a domain checked by the browser and a name an app gave itself differently, and say plainly when the name has not been checked.
- **DO** _(Costs trust)_ If you build a desktop or phone app, ask for less on the first connection than the website would: no standing allowance until the person has used the app and come back to it.
- **DON'T** _(Costs trust)_ Ask for an email address or a password as part of signing in. If you need an email for receipts, ask for it afterwards, as its own optional step.
- **DO** _(Costs trust)_ Sign users in with a key derived for your app. If your database leaks, the leaked keys can't be matched to the same person's activity elsewhere.
- **DON'T** _(Costs trust)_ Use the root identity key as the account ID for a social network, game, shop or payment service. One breach then becomes a cross-app tracking event.
- **DON'T** _(Costs trust)_ Request the wallet's root identity key without a reason you can state in the prompt. Approving a sign-in or a payment must never include it.
- **DO** _(Costs trust)_ Say on sign-out that the app is still connected in the wallet, and where to disconnect it: "Signed out. Pixel Arcade is still listed in your wallet. Remove it there to stop it asking."
- **DON'T** _(Costs trust)_ Call sign-out "Disconnect wallet". It does not touch the wallet's permissions, and the user will think it did.
- **DO** _(Costs trust)_ Ask only for the sign-in key at this step. Payment, the age check and the ticket basket each wait for the screen where Anna first needs them.
- **DON'T** _(Costs trust)_ Ask for a name or email straight after sign-in to make the header friendlier. "Your account" is enough until Anna chooses to add something.
- **DON'T** _(Costs trust)_ Offer to "find" Anna's account when a different wallet connects. The site cannot tell it is her, and guessing from anything else would link identities she kept apart.
- **DO** _(Costs trust)_ List on the site, before the wallet prompt opens, the one thing the site will receive and the things it will not, in the same words the wallet is about to use.
- **DON'T** _(Costs trust)_ Ask for a date of birth and work out the age on the site. The site then holds a fact it never needed, and the wallet's field-level choice is wasted.
- **DO** _(Costs trust)_ Ask for the same single field, "over 18", at every age-restricted checkout, and never widen a later request because an earlier one was granted.
- **DON'T** _(Costs trust)_ Put a "Disconnect" button on the site that only clears the session. Anna would believe the site lost its access when the wallet still lists it.
- **DO** _(Costs trust)_ Store the result of an age check, the gig and the date, and never the Pass or any field beyond the one asked for, and say so on the site's data page.
- **DON'T** _(Costs trust)_ Keep anything about Anna that this page does not list. If the site starts storing something new, the page changes the same day.
- **DO** _(Costs trust)_ Let the user set a threshold above which authentication is required per payment, and default it to something sensible rather than to every payment or to none. We suggest an amount around the price of a coffee.
- **DO** _(Costs trust)_ Make revoking immediate and obvious, and say what it will break: the app stops working until it asks again.
- **DO** _(Costs trust)_ Expire spending and sensitive permissions by default, and tell the user when one is about to lapse rather than renewing it silently.
- **DON'T** _(Costs trust)_ Bury this in settings. It is the control panel for everything that can spend the user's money without asking each time.
- **DO** _(Costs trust)_ Set allowances per app, with a per-payment cap as well as a total. A thousand payments of a satoshi and one payment of a thousand satoshis are different risks.
- **DO** _(Costs trust)_ Give it its own confirmation, outside any bundle, naming who is asking and what they will be able to see.
- **DON'T** _(Costs trust)_ Include it in a connect-time grant. Nothing legitimate needs it at connect time.
## Every rule, by page
### Connecting a wallet
https://www.bitcoinsv.design/guide/patterns/connecting-a-wallet/
- **DO** Write the connect flow around "your wallet". Name a specific wallet only when helping somebody install one.
- **DO** _(Costs trust)_ Request each permission when the user first uses the feature that needs it.
- **DON'T** _(Costs trust)_ Bundle every permission into one approval screen during onboarding.
- **DO** Warn the user and ask for approval again when an app's domain or certificate changes unexpectedly.
- **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.
### Permissions and allowances
https://www.bitcoinsv.design/guide/patterns/permissions-and-allowances/
- **DON'T** _(Costs trust)_ 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.
- **DO** _(Costs trust)_ 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.
- **DO** Write the description for each permission your app declares as what the user gets from it: "To save your reading position", not "Protocol access".
- **DO** Let the user approve some items in a grouped prompt and decline others, and let the app carry on with what was approved.
- **DON'T** _(Costs money)_ Show an amount taken from the app's description text. Show the amount from the request itself, and warn if the two disagree.
- **DO** Show a waiting state in the app that tells the user their wallet is asking them something, and keep it until the wallet answers.
- **DON'T** _(Costs trust)_ Cancel a wallet request because the user has not answered yet. A timeout turns a user who was reading into an error.
- **DO** Set an allowance to expire by default, and make a lasting allowance an explicit choice the user picks.
- **DO** _(Costs trust)_ 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.
- **DO** _(Costs trust)_ 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.
- **DO** Show the date a monthly allowance starts again beside what is left of it: "1,200 of 5,000 sats left, resets 1 December".
- **DO** After a refusal, say in one sentence what the app cannot do without the permission, and keep everything else working.
- **DO** Ask again only when the user next uses the feature that needs the permission, not on the next screen.
- **DO** _(Costs trust)_ 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."
- **DO** _(Costs trust)_ Ask for key linkage fresh each time, name who receives it and what they learn, and keep a local record of what was revealed to whom.
- **DON'T** _(Costs money)_ Let an AI agent approve key linkage, share a Pass, or widen its own permissions.
### Web apps and native apps
https://www.bitcoinsv.design/guide/patterns/web-and-native-apps/
- **DO** _(Costs trust)_ If you build a wallet, show a domain checked by the browser and a name an app gave itself differently, and say plainly when the name has not been checked.
- **DON'T** _(Costs money)_ Let an installed app that claims a website's name inherit the permissions or allowances already granted to that website.
- **DO** _(Costs trust)_ If you build a desktop or phone app, ask for less on the first connection than the website would: no standing allowance until the person has used the app and come back to it.
- **DO** When no wallet answers, say that the wallet may be closed as well as missing: "Open your BSV wallet, or install one, then try again."
- **DO** Detect the ordinary phone browser and say so before the person presses anything: "To pay here, open this page in your BSV wallet's browser." Offer to copy the link, and a way to install a wallet.
- **DON'T** Show a Connect button on a phone browser that cannot connect, or an error only after it is pressed.
- **DO** Show what the person is waiting for while the approval is in another app or on another device, and bring them back to the exact step they left.
- **DON'T** Treat leaving for the wallet as cancelling. A person who switches to approve and comes back should find the request still waiting, not a reset form.
### Signing in
https://www.bitcoinsv.design/guide/patterns/signing-in/
- **DO** Use one button for a first visit and a return visit. There is no separate sign-up, because there is no account to create.
- **DON'T** _(Costs trust)_ Ask for an email address or a password as part of signing in. If you need an email for receipts, ask for it afterwards, as its own optional step.
- **DO** _(Costs trust)_ Sign users in with a key derived for your app. If your database leaks, the leaked keys can't be matched to the same person's activity elsewhere.
- **DON'T** _(Costs trust)_ Use the root identity key as the account ID for a social network, game, shop or payment service. One breach then becomes a cross-app tracking event.
- **DON'T** _(Costs trust)_ Request the wallet's root identity key without a reason you can state in the prompt. Approving a sign-in or a payment must never include it.
- **DO** Recognise a returning user without a wallet prompt where the wallet already holds your app's permission.
- **DON'T** Show a public key as the user's name. Use the name they gave you, or a plain label such as "Your account".
- **DO** Tell people before their first sign-in that the account belongs to their wallet: "Restore this wallet and your account comes back with it. A different wallet is a new account."
- **DO** _(Costs trust)_ Say on sign-out that the app is still connected in the wallet, and where to disconnect it: "Signed out. Pixel Arcade is still listed in your wallet. Remove it there to stop it asking."
- **DON'T** _(Costs trust)_ Call sign-out "Disconnect wallet". It does not touch the wallet's permissions, and the user will think it did.
- **DO** Ask for the narrowest field that answers the question: "over 18", not a date of birth.
- **DO** Say which Pass issuers you accept, and offer another way to qualify where the law allows.
- **DON'T** Make a Pass a condition of signing in when only one feature needs it. Ask at that feature.
- **DO** After the first sign-in, say in one line what your app received and what it cannot see: "Pixel Arcade can recognise you next time. It can't see your balance or your other apps."
### Signing in
https://www.bitcoinsv.design/guide/connected-web-app/signing-in/
- **DO** Let people browse every gig, date and price without connecting. Connecting is for buying and for seeing tickets already bought, not for looking.
- **DON'T** Name a wallet brand on the site's connect button or its explanation. The site works with any compatible wallet, and naming one tells everyone else they are in the wrong place.
- **DO** _(Costs trust)_ Ask only for the sign-in key at this step. Payment, the age check and the ticket basket each wait for the screen where Anna first needs them.
- **DON'T** Treat "Not now" at this prompt as a failure. Put the Connect wallet button back, keep the gig page as it was, and say nothing louder than the button.
- **DO** Show the "what we can and can't see" line once, after the first sign-in only, on the page Anna was already on rather than a separate welcome screen.
- **DON'T** _(Costs trust)_ Ask for a name or email straight after sign-in to make the header friendlier. "Your account" is enough until Anna chooses to add something.
- **DO** Try a silent sign-in on load when the site has seen this browser before, and fall back to the Connect wallet button only if the wallet does not answer without a prompt.
- **DO** Under the connect button, say in one line that the account follows the wallet, not the device: "Use the same wallet on any device to see your tickets. A different wallet starts a new account."
- **DON'T** _(Costs trust)_ Offer to "find" Anna's account when a different wallet connects. The site cannot tell it is her, and guessing from anything else would link identities she kept apart.
### Proving an age
https://www.bitcoinsv.design/guide/connected-web-app/proving-an-age/
- **DO** Show the age step only for gigs that have an age limit, and name the venue's rule as the reason: "The Corner Room is over 18 only", not "Verification required".
- **DO** _(Costs trust)_ List on the site, before the wallet prompt opens, the one thing the site will receive and the things it will not, in the same words the wallet is about to use.
- **DON'T** _(Costs trust)_ Ask for a date of birth and work out the age on the site. The site then holds a fact it never needed, and the wallet's field-level choice is wasted.
- **DO** Request the field with Example Tickets named as the verifier, and if the venue itself will receive the answer, name the venue in the request too, so the wallet's "Sent to" line is true.
- **DO** _(Costs trust)_ Ask for the same single field, "over 18", at every age-restricted checkout, and never widen a later request because an earlier one was granted.
- **DO** Name the issuers the site accepts, and who chose them, on the screen that tells somebody they have no suitable Pass.
- **DO** Offer a way to buy that does not depend on a Pass where the venue allows one, so missing a Pass costs Anna a step at the door rather than the ticket.
- **DON'T** Send Anna to an issuer and empty her basket behind her. Keep the gig and the ticket she chose waiting for when she comes back.
- **DO** Word a refusal as Anna's decision and its one consequence for this gig, and leave every other part of the site, including other gigs, working as before.
- **DON'T** Reopen the wallet's Pass prompt automatically after a refusal, or on the next page load. The next request waits for Anna to press Ask my wallet again.
### Coming back and leaving
https://www.bitcoinsv.design/guide/connected-web-app/coming-back-and-leaving/
- **DO** Label the site's own control Sign out, and put the one-line pointer to the wallet directly beneath it, so the two actions are read together.
- **DON'T** _(Costs trust)_ Put a "Disconnect" button on the site that only clears the session. Anna would believe the site lost its access when the wallet still lists it.
- **DO** Say on sign-out that it applies to this device only, and that the ticket is unaffected, in one line on the page she lands on.
- **DON'T** Sign Anna straight back in on the next page load after she pressed Sign out. Wait until she presses Connect wallet again on this device.
- **DO** Treat a sign-in that suddenly prompts again as a returning user whose wallet was cleared or who removed the site, and show the ordinary connect flow without asking why.
- **DO** _(Costs trust)_ Store the result of an age check, the gig and the date, and never the Pass or any field beyond the one asked for, and say so on the site's data page.
- **DO** _(Costs money)_ 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.
- **DON'T** _(Costs trust)_ Keep anything about Anna that this page does not list. If the site starts storing something new, the page changes the same day.
### Identity
https://www.bitcoinsv.design/guide/how-it-works/identity/
- **DO** Say "Pass" in the interface. Keep "certificate" for developer documentation.
- **DO** Use identity discovery only when being found is central to your product, and say so where the user agrees to it.
- **DO** Show a wallet message beside the contact or payment it belongs to, not in a separate technical inbox.
### Security
https://www.bitcoinsv.design/guide/daily-spending-wallet/security/
- **DO** Use the platform's authentication rather than inventing a second one. It is what people already use, already trust, and already have recovery for.
- **DO** _(Costs trust)_ Let the user set a threshold above which authentication is required per payment, and default it to something sensible rather than to every payment or to none. We suggest an amount around the price of a coffee.
- **DON'T** Require authentication to open the app and again for every payment under a pound. People turn off what gets in their way, including the parts that were protecting them.
- **DO** Show spending against the allowance as a number and a proportion, per app. "The Satoshi Vision: 1,240 of 5,000 sats this month" is what a user needs to judge whether to keep it.
- **DO** _(Costs trust)_ Make revoking immediate and obvious, and say what it will break: the app stops working until it asks again.
- **DO** _(Costs trust)_ Expire spending and sensitive permissions by default, and tell the user when one is about to lapse rather than renewing it silently.
- **DON'T** _(Costs trust)_ Bury this in settings. It is the control panel for everything that can spend the user's money without asking each time.
- **DO** _(Costs trust)_ Set allowances per app, with a per-payment cap as well as a total. A thousand payments of a satoshi and one payment of a thousand satoshis are different risks.
- **DON'T** _(Costs money)_ 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.
- **DO** _(Costs trust)_ Give it its own confirmation, outside any bundle, naming who is asking and what they will be able to see.
- **DON'T** _(Costs trust)_ Include it in a connect-time grant. Nothing legitimate needs it at connect time.
- **DON'T** Show a modal on launch. It is the most ignored component in software, and it trains people to dismiss your warnings as a reflex.