Wallet selector
It’s a common scenario that a user wants to transfer bitcoin between apps and websites. This requires a way for those clients to communicate with each other. Two things are essential to this process:
- Having a method to communicate
- Speaking the same language
The first is provided by the environment (typically the operating system), and the second is about protocols and interoperability in the bitcoin application ecosystem.
Let’s say a user has won satoshis in a mobile gaming app and wants to transfer them to their wallet on the same device. The ideal user flow is that when a user presses a withdraw button, their wallet automatically becomes active and shows a screen to confirm the withdrawal. The user approves, and the funds are transferred. It’s a simple two-tap process.
Common issues are:
- The gaming app and wallet use different payment request formats. For example, the gaming app relies on LNURL, which the wallet does not support.
- The user has multiple wallets installed. The gaming app uses functionality provided by the operating system to open the default wallet, but the default is not what the user wants.
The wallet selector
A solution various applications have adopted is that of a wallet selector. It is an additional step in the user flow when sending or receiving. It prompts the user to select the wallet to use in the current interaction.
Withdrawing sats in a THNDR Games app.
Choosing a wallet for payment in The Bitcoin Company app.
Choosing a wallet for invoice payment in Damus.
This allows the application to specifically communicate which wallets are supported, and then format the information transfer accordingly. If the user’s wallet is not listed, they can still use the “default wallet” option in the hope that it works.
How wallet selection is made
URI schemes are how operating systems determine which applications to pass information to when a link is activated. There are 2 types of URI schemes:
- General-purpose ones
- Application-specific ones
We’ll outline each of those below.
1. Opening the default wallet
A widely supported standard is BIP 21 (also see Payment request formats), which defines a URI scheme for passing bitcoin payment information to other applications.
For example, clicking a link or button with the following URI is opened in the default bitcoin wallet (if there is one installed):
bitcoin:16AgmhoCVSJoGeEkERPdrsdvJG3RWmum6T
If you have a bitcoin wallet installed on your device, you can try it here:
2. Opening a specific wallet
Wallets can also define their own unique URI schemes (like walletname:, see the documentation for Apple devices). On installation, the operating system registers the new URI scheme, and any links that follow this scheme will be opened in the respective wallet.
For example, the following URI would be opened in an imaginary “Design Wallet” since it would have registered the designwallet: URI scheme upon installation:
designwallet:bitcoin:16AgmhoCVSJoGeEkERPdrsdvJG3RWmum6T
While this is practical for users, there is no automated discovery process. Developers are required to manually track and implement custom schemes.
Detecting installed wallets
Highlighting of installed wallets in the Simple Bitcoin app.
Some operating systems (see iOS documentation) provide a way to detect if the device can handle specific URI schemes. This allows for detection of whether specific wallets are installed. You can use this feature to highlight installed wallets to the user and deprioritize others (or even offer installation links for those). On the technical side, you can pass on customized payment information for each one based on supported features.
Only ask once
Default wallet setting in the Plebstr app.
When a user has chosen their preferred wallet to use for a specific action, you can set it as the default option for future actions. Make sure to provide the option to change this default.
Beyond URI schemes
There are several other techniques for websites and applications to communicate with each other. Each has its own use cases, benefits, and limitations.
Web Share API
The Web Share API allows websites to prompt a share mechanism provided by the operating system. It supports the sharing of URLs, text, and files. The benefit is that the operating system can show an array of applications for the user to choose from, based on what is installed and prior usage.
Share sheets
As described above, operating systems provide UIs to let users choose which applications to send shared information to.
- Activity views (Apple operating systems)
- Android sharesheet
Browser extensions
Browser extensions can inject code into websites to simplify sharing. This mechanism is also generally described in the Sign in with bitcoin page.
Next, view the case studies that can help you build better bitcoin products.