Need help understanding Bitcoin DeFi?
Need help understanding Bitcoin DeFi?
Need help understanding Bitcoin DeFi?
Need help understanding Bitcoin DeFi?
Need help understanding Bitcoin DeFi?

Getting Started With On-Chain Usernames on Stacks

The Blockchain Naming System (“BNS”) was introduced with Stacks 1.0, making it possible to create Stacks usernames without relying on any central points of control. For app developers and users alike, this means that Stacks accounts can be referenced with unique, user-owned, and human-readable usernames. This blog posts shed light on the current status of the BNS support in Hiro tooling, like stacks.js packages and the Stacks Wallet. Read on to learn more and understand how to get started with BNS on Stacks 2.0.

Deep dive
July 14, 2021
Getting Started With On-Chain Usernames on Stacks

BNS on Clarity

BNS support was added to the Stacks blockchain with the release of Stacks 2.0. Just like Stacking, BNS is implemented through the Clarity smart contracting language itself. The BNS contract provides a set of public and read-only methods to interact with the naming system.

Users can register usernames

Stacks users can interact with the BNS contract to register usernames (e.g. for any number of available namespaces such as .id.stx. Name registrars can also interact with the contract to add new namespaces, which are similar to top-level domains in the traditional Domain Name System (DNS).

For instance, the recently launched service enables users to create .btc usernames such as muneeb.btc. Users have to pay with STX for username operations, as defined by the rules of the namespace owner.

Unlike with other authenticators previously released by Hiro (such as Blockstack Connect or the Blockstack Browser), users cannot register usernames for free using the newer Stacks Web Wallet browser extension. They will need to pay a registration and transaction fee using STX, and use an app that integrates registration via BNS smart contract calls like

However, the extension does show free usernames that were registered previously, and we’re considering the reintroduction of free username registration to the Stacks Wallet as a future enhancement.

To access your previously registered usernames, simply sign into the browser extension with the same underlying Secret Key (previously known as “Secret Recovery Key”) that you used before to manage them.

Developers can use a BNS package and the API to integrate name operations

Developers can leverage the BNS package and the API to:

  • Fetch or register namespaces (for instance .id)
  • Fetch or register usernames for a specific namespace (for instance
  • Fetch all username details (for instance Stacks address or expiration date)
  • Fetch the history of name operations for a specific username
  • Fetch all available subdomains (for instance

With BNS tooling, developers can build full-featured naming capabilities inside their apps. For example, apps could enable interaction with other users by username - sending tokens from one account to another with human-readable addresses. Apps could also display the username instead of the account address in their app - this will help users recognize that they are using the right account for. These are only a few examples! We cannot wait to see developers using the naming system to build better user experiences on the user-owned internet.

Getting started

We are currently working on more advanced documentation for BNS. In the meantime, there are several resources to help you get started today:

Copy link
Hiro news & product updates straight to your inbox
Only relevant communications. We promise we won’t spam.

Related stories