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,
  // disable_v1 is optional and when true disables the resolution of v1 names
  "disable_v1": false
}

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.

As people migrate their old NNS name to the new contracts, we recommend to also integrate with the old NNS resolver as shown here. This is give one, with one simple integration:

• Resolution of NNS v2 names

• Resolution of NNS v1 names

• Fallback to .eth names

in this order of priority.

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 nnsV2ResolverABI = [
  {
    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;

export const nnsV1ResolverABI = [
  {
    stateMutability: "view",
    type: "function",
    inputs: [{ name: "addr", internalType: "address", type: "address" }],
    name: "resolve",
    outputs: [{ name: "", internalType: "string", type: "string" }],
  },
] as const;

function useNNSName(address: Address) {
  const v2Name = useReadContract({
    abi: nnsV2ResolverABI,
    functionName: "reverseNameOf",
    args: [address, [], true],
    address: NNS_RESOLVER_ADDRESS,
    chainId: base.id,
  });
  const v1Name = useReadContract({
    abi: nnsV1ResolverABI,
    address: "0x849F92178950f6254db5D16D1ba265E70521aC1B",
    functionName: "resolve",
    args: [address],
    chainId: mainnet.id,
    query: {
      enabled: v2Name.isSuccess && !v2Name.data,
    },
  });
  return useMemo(() => {
    if (v2Name.isSuccess && !v2Name.data) {
      return v1Name;
    }
    return v2Name;
  }, [v1Name, v2Name]);
}

In this example, you can simply return v2Name if you don't want to use the old resolver.