Paying by handle
Paying somebody by a readable name: how a handle becomes a payment, what to show before the confirm button, and the risk a readable name brings.
Paying by handle means the user types a readable name, such as anna@example.com, and the wallet looks up who it belongs to before anything is paid. We recommend showing the name and picture the handle resolved to before the confirm button, then saving it as a contact so nobody types it twice.
A plain bitcoin address is 26 to 35 characters of base58 that nobody can read, check or remember. Asking people to compare one character by character was never realistic. In practice they compare the first four and the last four and trust the middle.
How a name becomes a payment
Paymail
Paymail (BRC-28) is the established scheme. A handle looks like an email address, anna@example.com, and the domain is the authority. A wallet asks example.com what anna supports, and gets back the owner's public key, a profile name and avatar, and where to send a payment.
That lookup is what makes a peer-to-peer payment possible. Without it the sender has no public key for the recipient, and the derivation needs one. See Payments.
The newer scheme
The newer handle scheme (BRC-169) keeps Paymail's idea and adds what a modern wallet needs. A handle is @anna@example.com, with a second @ in front. It adds three things:
- An optional tag.
@anna+shop@example.comresolves to the same person as@anna@example.com. Somebody can give out a different form for each context and still be one identity, for example a public donation handle and a personal one. - A certificate, not just an answer. The lookup returns an identity certificate (BRC-52) signed by the domain's certifier. The wallet checks the signature, that the certifier matches the domain's published key, that the handle and domain match, and that the revocation outpoint is still unspent. A compromised lookup cannot quietly substitute a different key.
- A message box. Somewhere to deliver the payment. This matters because the peer-to-peer flow is an exchange, not a broadcast.
The domain part can also be a short alias, and within your own ecosystem it can be dropped entirely. Everything is case-insensitive and normalised to lower case. Paymail-style input is accepted and normalised into the same form.
Do
Accept both forms in any field that takes a handle. A user pasting anna@example.com into a wallet using the newer scheme should simply work.
What to show before a payment
The lookup returns more than an address, so that the user can see who they are paying.
Do
Show the profile name and avatar the handle resolved to, before the confirm button. Paying "Anna Keller" is checkable; paying anna@examplebank.com is only spellable.
Do
Say when the key behind a saved contact has changed since last time, and make the user acknowledge it. A silently rotated key is how a handle gets hijacked.
Do
Make saving a resolved handle as a contact the obvious next step. The second payment to someone should never involve typing.
Don't
Show the derived address anywhere in the main flow. It is a one-time internal value and putting it on screen invites comparison nobody can perform.
The risk a readable name introduces
A readable name is easier to read, and so easier to fake. anna@examplebank.com and anna@examplebanks.com are one character apart and look identical at a glance.
Why this matters
The protections against this are the profile name shown before confirming, the certificate check, and a saved contact that needs no typing. Lean on all three.
Do
Offer matches from saved contacts as the user types a handle, before accepting free text.
Don't
Show a handle on the review screen without the profile name it resolved to. On its own, a one-character difference is invisible.
Do
Warn plainly when a handle does not resolve, naming what failed: no such handle, domain unreachable, certificate invalid. "Couldn't find that" sends people to try again rather than to look harder at what they typed.
Don't
Fall back silently to a plain-address payment when a handle resolves but does not support the peer-to-peer flow. Say so, because the confirmation the user gets is weaker. See Legacy compatibility.
Falling back when a handle cannot take a peer-to-peer payment
- OK: say the confirmation will be weaker, and let the user choose whether to continue.
- Grey area: fall back automatically and tell the user afterwards, on the receipt.
- Not OK: fall back silently, so the user believes they got the stronger confirmation.
Open questions
- Do people look at the resolved name and avatar before confirming, or does it become one more thing they tap past?
- How should a key-change warning read so that ordinary key rotations do not teach people to dismiss it?
- What protects the payer when the domain itself is compromised, since the certificate check trusts the domain's own published key?
- What should a handle be called on screen? "Handle", "Paymail" and "address" each suggest something different, and none has been tested with people new to it.
- Should a tag such as
+shopbe shown to the payer, or treated as the recipient's private bookkeeping?
Related
- Sending: the send flow this sits inside, in the daily spending wallet
- Contacts: saving a resolved handle so nobody types it twice
- Wrong-network payments: why a handle beats an address
- Errors and failed payments: a handle that does not resolve
- Payments: what a handle makes possible
- Identity: certificates and Passes
- Legacy compatibility: paying a handle that only accepts a plain address
Written from: BRC-28, BRC-29, BRC-42, BRC-52, BRC-169.
Checklist
The rules on this page, in a form you can work through.
9 rules