Resolving NNS Names

There are 2 ways to resolve addresses to NNS Names: calling the NNSResolver or our API.

Make sure you understand how the NNSResolver works here.

Resolving via the API

You just need to make a POST request to https://api.nns.nyz/resolve with

{
  "address": "0x123...456",
  // clds is optional and defaults to []
  "clds": [
    "0x1",
    "0x2",
  ],
  // fallback is optional and defaults to true
  "fallback": true,
}

which will return

{
  "name": "hello.⌐◨-◨" // or null
}

Resolving by calling the contract

You just need to call

function reverseNameOf(
    address addr,
    uint256[] calldata cldIds,
    bool fallbackToDefault
) external view returns (string memory);

on the resolver. The inputs are the same as the API call.

Inputs

• address is the address that will be resolved

• clds is an array of cld ids to perform a lookup on

• fallback whether you want to fallback to the default cld in case no lookup is found in the given list

Common Scenario

The most common scenario is to let the owner choose where they want to be resolved and this can be done by simply omitting the clds and setting the fallback to true.

Code Samples

The code below assumes you are using wagmi and @tanstack/react-query.

API call

async function fetchNNSName(address: Address) {
  const res = await fetch(`https://api.nns.xyz/resolve`, {
    method: "POST",
    body: JSON.stringify({ address }),
  });
  if (!res.ok) {
    throw new Error("invalid response");
  }
  const body = await res.json();
  return body.name as string | null;
}

function useNNSName(address?: Address) {
  return useQuery({
    queryKey: [address, "nns-name"],
    queryFn: () => fetchNNSName(address || zeroAddress),
    enabled: Boolean(address),
  });
}

As an example, if you only want to resolve .nouns names you can pass:

async function fetchNNSName(address: Address) {
  const res = await fetch(`https://api.nns.xyz/resolve`, {
    method: "POST",
    body: JSON.stringify({ 
        address,
        // only resolve in .nouns
        clds: [
            // namehash("nouns")
           "0x84917c06116ee3d3a59b0b08f1c872deae04baecba033ea58cc455c7ca79c62c"
        ],
        // don't fallback to the default cld
        // we recommend setting this to true, see comment below.
        fallback: false, 
    }),
  });
  if (!res.ok) {
    throw new Error("invalid response");
  }
  const body = await res.json();
  return body.name as string | null;
}

Note however that this is going to return null if the account has no .nouns. We recommend to set fallback: true to ensure you get one resolution back.

Contract call

const abi = [
  {
    inputs: [
      {
        internalType: "address",
        name: "addr",
        type: "address",
      },
      {
        internalType: "uint256[]",
        name: "cldIds",
        type: "uint256[]",
      },
      {
        internalType: "bool",
        name: "fallbackToDefault",
        type: "bool",
      },
    ],
    name: "reverseNameOf",
    outputs: [
      {
        internalType: "string",
        name: "",
        type: "string",
      },
    ],
    stateMutability: "view",
    type: "function",
  },
] as const;

function useNNSName(address: Address) {
  return useReadContract({
    abi,
    functionName: "reverseNameOf",
    args: [address, [], true],
    address: NNS_RESOLVER_ADDRESS,
  });
}