Permissions

Whenever a WalletClient call might reveal keys, move funds, or touch user-private data, the user's BRC-100 wallet pauses and asks the user to grant a permission.

A permission is a one-time or persistent approval that lets your application continue a narrowly defined operation. There are four distinct permission types and knowing what each one does can allow you to request only what you really need.

---

Permission Types

1. Protocol

Grants your app the ability to read or create data under a protocol ID and obtain the public keys required for that protocol.
Appears any time you request getPublicKey(), encrypt(), or any other call that specifies that protocol.

Protocol-ID security levels 0 — does not prompt the user for any permissions anytime this protocol is requested 1 — prompts the user the first time this specific protocol is requested 2 — prompts the user every time this specific protocol is requested for a new counterparty

2. Spending

Allows a single payment or allows the user to set an allowance for future spending permissions.
Appears when a call needs more satoshis than the current allowance.

3. Basket

Lets the app list, read, or write UTXOs in a named basket. First pops up when you run listOutputs() or relinquishOutput() on that basket name.

4. Certificate

Authorises the app to acquire, prove, or revoke a certificate via a certifier server.
Triggered by acquireCertificate(), proveCertificate(), or relinquishCertificate().

---

How the Wallet Identifies Your App

When making an application that utilizes the wallet, you should check that you have these set to something the user would easily recognize as being your application.

• Icon – pulled from your highest-resolution favicon (<link rel="icon"> or /favicon.ico).

• Name – taken from manifest.json → name.

• Origin – displayed as scheme://host[:port] so the user sees exactly which site is asking.

Keep both the favicon and manifest name accurate because users will see them in every prompt!

---

Typical Triggers For Each Permission

• Protocol: A chat page asks for the chats protocol.

• Spending: A tip button tries to spend 3000 sats but has not set an allowance high enough.

• Basket: An inventory screen loads the tokens basket for the first time.

• Certificate: A badge page calls acquireCertificate() to claim a Premium Badge.

Prompts appear in the sequence your code triggers them; there is no enforced order.

---

Developer Checklist

• Requesting permissions in time with the actual usage of it is preferred as it gives the user more context to what the permissions are accessing.

• Showing a quick “why we need this” note in your UI before the wallet dialog could be useful if the reason why the request is ambiguous to the user.

• Use unique protocol IDs and basket names to avoid collisions with other apps.

• Keep your favicon and manifest name updated and clear. Good branding builds trust!

By utilizing minimal permission requests, users remain in control while your application receives only the access it truly needs.