Quick Start

Let's do a quick query to find $web3.

The ADA Handle Standard makes querying a Handle's location (and by extension, the corresponding address) very simple. On Cardano, all NFTs are minted under a Policy ID. The Policy ID can only be generated by the policy's private key, and therefore acts as a guarantee for the NFT being minted that no other NFT under the same name will also have the same Policy ID.

With this in mind, it is completely safe and definitive to query a Handle's name as long as you have the correct Policy IDs in your query.

To demonstrate just how easy this concept is, let's look for the Handle $web3.

Querying A Handle

Converting a Handle to an address is as simple as checking for the location of that Handle. Rather than typical custom address NFTs that associate an address with metadata, the Handle Standard assumes an associated address by reference.

In our example, we will query the location of the $web3 Handle using a the Blockfrost REST API, but you could query your own Cardano node (equipped with the Wallet API) just as easily.

Node

const handleName = 'web3';
const policyID = 'f0ff48bbb7bbe9d59a40f1ce90e9e9d0ff5002ec48f232b49ca0fb9a';

// A blank Handle name should always be ignored.
if (handleName.length === 0) {
  // Handle error.
}

// Convert handleName to hex encoding.
const assetName = Buffer.from(handleName).toString('hex');

// Fetch matching address for the asset.
const data = await fetch(
  `https://cardano-mainnet.blockfrost.io/api/v0/assets/${policyID}${assetName}/addresses`,
  {
    headers: {
      // Your Blockfrost API key
      project_id: process.env.BLOCKFROST_API_KEY,
      'Content-Type': 'application/json'
    }
  }
).then(res => res.json());

if (data?.error) {
  // Handle error.
}

const [{ address }] = data;
console.log(address); // addr1qx3c9...

And that's it! You can be certain that the resulting address will be accurate at the time of the query. Depending on your dApp, you may want to query the Handle's location on an interval to account for possible movement between wallets.