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.
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 #
For example, clicking a link or button with the following URI is opened in the default bitcoin wallet (if there is one installed):
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:
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 #
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 #
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.
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.
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.