Sign in with bitcoin
Identity is at the core of bitcoin, as it is a requirement to create what we refer to as ownership. Bitcoin is assigned to addresses. Addresses are generated from public-private key pairs. Owning bitcoin means being solely in control of these private keys. See public-key cryptography) for more information on this topic.
The cryptography involved in this can also be used to generate public keys for other purposes, like a unique identifier that websites and applications can use for their account systems. This is similar to approaches like Passkeys, which also look at replacing email & password combos with unique identifiers. Decentralized identities (DID) are another emerging approach.
In the context of bitcoin, this allows users to sign in to services with their wallets and also use this connection to make low-friction payments.
All eyes on lightning
On this page, we only focus on lightning wallets, as they lend themselves much better to this type of user experience.
Support
“Sign in with bitcoin” is not widely supported. It uses new technologies like WebLN and LNURL-auth that are still maturing and looking for broader adoption. To try this out, you can use the Alby browser extension wallet with a service like Stacker News that allows you to spend satoshi to upvote news stories (more lightning apps can be found in the bolt.fun maker directory).
Wallet-service communication
Your service and the user’s wallet need to be able to communicate with each other to exchange information. There are two basic ways to handle this—direct and bridged.
Direct communication
The smoothest user experience is when the wallet and the service can directly communicate with each other. For example, a browser wallet and a website can send messages back and forth (see WebLN). This allows for convenient features like allowances for automatic approval of payments for services the user trusts.
The wallet and service can directly communicate.
Bridged communication
There is more friction if the user needs to be involved in this communication. However, this extra friction provides more user control and better security. In the visualization below, the service and user wallet cannot directly communicate with each other. Instead, the web application presents instructions as QR codes that the user needs to scan with their (mobile) wallet. The wallet then sends instructions to the application server, which updates the web application.
Manual user action is required to bridge communication between the wallet and the service.
This does not necessarily have to be done via a QR code. The most basic method could even involve manually copying and pasting messages and identifiers back and forth.
Signing in
The biggest hurdle at this stage is that most users will not be familiar with this authentication method and are not likely to have a wallet they can readily use. Ensure that there are concise explanations and tips to get users started.
Provide clear information and tips as users are likely not to be familiar with these interactions.
Authentication is a simple process in which the service sends a message to the wallet. The wallet then uses cryptography to generate a unique identifier from the message, which it sends back to the service. This identifier can then be used to establish an account.
Confirmation modal to approve sign-in via a browser-extension wallet.
Keep in mind that your service will not be able to retrieve user names, emails, balances, transactions, or other information from the wallet. Only the minimal information to identify the user is communicated. If you need to communicate with users about their accounts or activity, make sure you request an email or other contact point.
Signing out
Ensuring users are signed out (manually or via session time-outs) is important. The account may have payment allowances, or other problematic permissions, that could otherwise be abused by third parties.
Making payments
Typically, your service will prompt the user for a payment when the user tries to interact with the service. Show the most appropriate option right away based on how the user has previously used your service (direct or bridged, see above.
Approval modal to approve a payment via a browser-extension wallet.
Allowances (requiring a direct connection) allow for automatic approval of payments by wallets up to certain amounts. This reduces friction for users that frequently transact. With an allowance, the modal window in the visualization above would not be needed. Ensure your interface provides user feedback when payments are confirmed.
Making payments via a bridged connection has more friction.
An alternative to reducing friction for frequent payments is to let users deposit satoshi into their accounts (and later withdraw them). This puts the service into a custodial position for the benefit of smoother payments (since they only involve database updates and not actual lightning payments).
Connecting multiple wallets
Users may migrate wallets and want to link their existing account to a new wallet. They may also want to connect multiple wallets to the same account. This could be for convenience, like signing in with both a desktop and a mobile wallet. Or it could be for security, like logging in with one wallet but making payments with another. It may also be necessary in order to accommodate different implementations and lack of interoperability.
Account screen showing multiple wallets linked to an account.
Recovery
If a user loses their wallet, they also lose their access to your service. Ensure you have a recovery mechanism in place. This could be a single-use recovery code (as is a common pattern with multi-factor authentication) or a traditional email that you can also use for other communication with the user.
Next, view our case studies to see examples of design applied to real bitcoin software.