Edit this page

Retrieve Domain Metadata Using Smart Contracts Guide

This guide covers retrieving the metadata of UD domains using smart contracts. This process requires using the ABIs built into the Unstoppable Domains UNS smart contract.

Step 1: Select a UNS Registry Smart Contract

The UNS Registry smart contract is where domain owners store their data and is a map of domain namehashes to key-value dictionaries of records. Choose one of the Unstoppable Registry smart contracts to interact with (either mainnet or testnet).

polygon registry contract

polygon registry contract

Step 2: Open the “Read as Proxy” Tab for the Registry Contract

Navigate to the Contract tab in either the Etherscan or Polygonscan page of the Registry contract and click on the Read as Proxy tab:

polygonscan read as proxy tab

polygonscan read as proxy tab

Step 3: Generate the Namehash of the Domain

You can generate the namehash of a domain using any of the Resolution Libraries or Resolution CLI. You can also use online tools to calculate the namehash of the domain.

JavaScriptJavaSwiftGolangResolution CLI
const {default: Resolution} = require('@unstoppabledomains/resolution');
const resolution = new Resolution();
let namehash = resolution.namehash("brad.crypto", "UNS");
import com.unstoppabledomains.resolution.Resolution;
DomainResolution resolution = new Resolution();
String namehash = resolution.getNamehash("brad.crypto", "UNS");
import UnstoppableDomainsResolution

guard let resolution = try? Resolution() else {
  print ("Init of Resolution instance with default parameters failed...")

let namehash = try resolution.namehash(domain: "brad.crypto")
package main

import (

func main() {
    uns, _ := resolution.NewUnsBuilder().Build()
    namehash, _ := uns.Namehash("brad.crypto")
    fmt.Println("The namehash for brad.crypto is", namehash)
$ resolution namehash -d brad.crypto

The JavaScript and Java Resolution Libraries require a Naming Service parameter to generate namehashes. This specifies the name service that manages the domain name, and the value must either be "UNS" or "ZNS".

Step 4: Retrieve the TokenURI

The UNS contract has a tokenURI() method that takes in the namehash of a domain and returns an HTTP URL to fetch the domain's metadata. Unstoppable Domains implements the metadata extension defined in the EIP-721 token standard.

polygonscan tokenURI method

polygonscan tokenURI method

Add the namehash of the domain you want to retrieve its metadata in the tokenId field of the tokenURI() method and click the Query button.

polygonscan tokenURI response

polygonscan tokenURI response

Step 5: Get the Domain Metadata

Send a GET request to the URL returned from the tokenURI() method call to retrieve the metadata of the domain:


The metadata endpoint returns a JSON response in the following format:

  "name": string,
  "description": string,
  "properties": object,
  "external_url": string,
  "image": string,
  "image_url": string,
  "attributes": [
  "background_color": string

Smart Contract Considerations

Retrieving domain metadata with smart contracts involves using the tokenURI() method to get the metadata source URL, then making a GET request to the URL to fetch the metadata information.

You can also integrate domain metadata retrieval into your application using libraries that allow you to call smart contracts ABIs like ethers.js and web3.js.

An example in JavaScript of integrating domain metadata retrieval (using the ethers.js library):

const proxyReaderAddress = "0x423F2531bd5d3C3D4EF7C318c2D1d9BEDE67c680";

// partial ABI, just for the tokenURI method
const proxyReaderAbi = [
  "function tokenURI(uint256 tokenId) external view returns (string memory)",

const proxyReaderContract = new ethers.Contract(

// generate the namehash of the domain name
const domainName = "jim-unstoppable.x";
const namehash = resolution.namehash(domainName, "UNS");

// call the tokenURI method
const tokenURI = await proxyReaderContract.tokenURI(namehash);
  .then(response => response.json())
  .then(data => console.log(data));

You have successfully retrieved the metadata of a domain name using smart contracts. Happy Hacking!

Asking For Help

If you are experiencing difficulties using our services, please know that we are here to help. You can join our Discord Community for real-time support from UD and the community, where you can receive assistance with integrating your app