# Resolving NNS Names

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

{% hint style="info" %}
Make sure you understand how the `NNSResolver` works [here](/for-devs/nns-protocol.md#nnsresolver).
{% endhint %}

### Resolving via the API

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

```json5
{
  "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

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

### Resolving by calling the contract

You just need to call

```solidity
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.

{% hint style="success" %}
As people migrate their old NNS name to the new contracts, we recommend to also integrate with the [old NNS resolver](https://etherscan.io/address/0x849F92178950f6254db5D16D1ba265E70521aC1B) 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.
{% endhint %}

### Code Samples

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

#### API call

```ts
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:

```typescript
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

```ts
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nns.xyz/for-devs/resolving-nns-names.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.