Handshake logo

HIP-0002: Well Known directory for wallets address


This HIP describes how to publish a wallet address in a domain.


Wallet address are not human friendly. Sending an address normally involves “copy & paste” and is nearly impossible to do via voice channels.

Since Handshake is all about owning domains, we could use them as aliases to our wallet addresses.


The basics of this protocol consists of serving the address in an HTTPS request to the .well-known directory. For security reasons, should be done over HTTPS.

The address should be located at https://<domain>/.well-known/wallets/SYMBOL.

For instance, https://example/.well-known/wallets/HNS.

Dynamic or Static

This proposal doesn’t define if the content served should be static (file in the disk) or dynamic (unique address per request).

Security Concerns

Requests should be made using only HTTPS. Handshake’s HTTPS requests are secured by DANE & PoW.

In implementations that allow sending to both addresses and domain aliases, measures must be taken to disambiguate between addresses and domains of the same length. If sharing an entry field, aliases should be prefixed with an @ symbol.

For example, hs1qshuyulxra3pqpwr40303t8pn79232zztuk4qgz should be interpreted as a wallet address, while @hs1qshuyulxra3pqpwr40303t8pn79232zztuk4qgz should be interpreted as a domain alias with wallet address located at hs1qshuyulxra3pqpwr40303t8pn79232zztuk4qgz/.well-known/wallets/HNS.

Non-HNS domain

This protocol can also be used with non-HNS domains (aka ICANN).

In this case, the security would rely on CA. It should be a consumer choice to accept it or not.

Non-cryptocurrency address

It’s also possible to define a non-crypto symbol, such as /.well-known/wallets/USD, which should return an IBAN.



SLIP-0044 can be used as a symbol reference.

Wed, 07 Oct 2020
Last commit:
Mon, 13 Mar 2023
  • Fernando Falci <http://iamfernando/>
  • Mark Tyneway <@tynes>

Edit on GitHub