# List names for an address

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

List the names an address owns, manages, holds roles on, resolves to or used to own, with filters, sorting and pagination.

Source: https://ensforge.com/docs/sdk/list-names-for-an-address

By the end of this guide you can show an account's names, for a "my names" page or a name picker.

## Prerequisites [#prerequisites]

- A client with an [indexer](/docs/reference/glossary#indexer) and `indexerActions()`. See [Connect an indexer](/docs/sdk/connect-an-indexer). The chain cannot list the names of an address, so this needs an indexer.

## List the names an address is related to [#list-the-names-an-address-is-related-to]

`indexer.getNamesForAddress` returns one page of names. By default it lists every name the address owns, manages or holds a role on.

**Example** (Listing an Account's Names)

```ts title="list-names.ts"
import { ensActions, Ensforge } from "@ensforge/sdk";
import { bigname, indexerActions } from "@ensforge/sdk/indexer";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
  indexer: bigname(),
})
  .extend(ensActions())
  .extend(indexerActions());

const page = await ens.indexer.getNamesForAddress({
  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
});

for (const item of page.items) {
  console.log(item.name, item.relations, item.isPrimary);
}
```

- `page.items` holds up to `limit` names. The default is 50 and the most is 200.
- Each item is a name with `relations`, the ways the address relates to it, and `isPrimary`, whether it is the address's primary name.
- `page.hasMore` and `page.cursor` tell you whether there is another page. See [Load more results](/docs/sdk/load-more-results).

The address can be all lowercase or checksummed. Without `namespace`, the list covers every namespace the indexer serves. See [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address).

## Choose how the address is related [#choose-how-the-address-is-related]

`relation` is one value or a list of these:

| Relation        | The address…                                            |
| --------------- | ------------------------------------------------------- |
| `"owner"`       | owns the name.                                          |
| `"manager"`     | manages the name.                                       |
| `"roleHolder"`  | holds a role on the name.                               |
| `"resolvesTo"`  | is the address the name points to. Pair it with `coin`. |
| `"formerOwner"` | used to own the name.                                   |

`"any"`, the default, means owner, manager and role holder. `"resolvesTo"` and `"formerOwner"` are listed on their own, never inside `"any"`.

**Example** (Listing Names that Point at an Address)

```ts title="list-resolves-to.ts"
import { ensActions, Ensforge } from "@ensforge/sdk";
import { bigname, indexerActions } from "@ensforge/sdk/indexer";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
  indexer: bigname(),
})
  .extend(ensActions())
  .extend(indexerActions());

const address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045";

const pointing = await ens.indexer.getNamesForAddress({ address, relation: "resolvesTo" });

const owned = await ens.indexer.getNamesForAddress({
  address,
  relation: "owner",
  sort: "expiry",
  order: "asc",
  limit: 20,
});
```

See [Who can change a name](/docs/sdk/who-can-change-a-name) for what owner, manager and role holder mean.

## Filter, search and sort [#filter-search-and-sort]

| Option                          | Type                                                | Default                            | Description                                                                |
| ------------------------------- | --------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------- |
| `address`                       | `string`                                            | required                           | The address to list names for.                                             |
| `namespace`                     | `"ens"` or `"basenames"`                            | every namespace the indexer serves | Limits the list to one naming system.                                      |
| `relation`                      | relation, list of relations, or `"any"`             | `"any"`                            | Which relations to list.                                                   |
| `coin`                          | symbol, `{ chainId }`, `bigint` or `"evm"`          | `60`                               | Coin type for `relation: "resolvesTo"`. `"evm"` means every EVM chain.     |
| `parent`                        | `string`                                            | none                               | Only direct children of this name.                                         |
| `authority`                     | `"ensV0"`, `"ensV1"`, `"ensV2"`, or a list          | none                               | Only names held by that protocol.                                          |
| `migrated`                      | `boolean`                                           | none                               | Only names that moved to ENSv2, or only those that did not.                |
| `search`                        | `string`                                            | none                               | Only names that match this text.                                           |
| `match`                         | `"prefix"` or `"contains"`                          | `"prefix"`                         | How `search` matches.                                                      |
| `sort`                          | `"name"`, `"expiry"`, `"registered"` or `"created"` | the indexer's default              | What to sort by. bigname sorts by name, and `formerOwner` lists by expiry. |
| `order`                         | `"asc"` or `"desc"`                                 | the indexer's default              | Sort direction. bigname sorts ascending.                                   |
| `dedupe`                        | `"name"` or `"registration"`                        | `"name"`                           | One row per name, or per registration.                                     |
| `expiresAfter`, `expiresBefore` | `bigint` or `Date`                                  | none                               | Expiry bounds. Only with `relation: "formerOwner"`.                        |
| `limit`                         | `number`                                            | `50`                               | Names per page, 1 to 200.                                                  |
| `cursor`                        | `string`                                            | none                               | The previous page's `cursor`.                                              |
| `includeTotal`                  | `boolean`                                           | `false`                            | Count every row into `totalCount`. Slower.                                 |
| `signal`                        | `AbortSignal`                                       | none                               | Cancels the call.                                                          |

## Read the result [#read-the-result]

Each item in `page.items` has:

| Field                         | Description                                                                    |
| ----------------------------- | ------------------------------------------------------------------------------ |
| `name`                        | The normalised name. Unknown labels appear as `[labelhash]`.                   |
| `relations`                   | How the address relates to the name.                                           |
| `isPrimary`                   | Whether it is the address's primary name.                                      |
| `owner`, `manager`            | Who holds the name.                                                            |
| `status`                      | `"active"`, `"expired"`, `"released"` or `"unregistered"`, or `null`.          |
| `expiresAt`, `graceEndsAt`    | Unix seconds as `bigint`, or `null`. A name that never expires has `2^64 - 1`. |
| `recordCount`, `subnameCount` | How many records and subnames the name has, when reported.                     |

The page also carries the indexer metadata (`asOf`, `completeness`, `indexer`) described in [Connect an indexer](/docs/sdk/connect-an-indexer#3-read-answers-with-care).

## Troubleshooting [#troubleshooting]

### `INDEXER_NOT_CONFIGURED` [#indexer_not_configured]

The client has no indexer, or you forgot `indexerActions()`. See [Connect an indexer](/docs/sdk/connect-an-indexer) and [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED).

### `INVALID_ADDRESS` [#invalid_address]

The `address` is not a valid address. [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) is thrown before any request is sent. `INVALID_COIN_TYPE` and `INVALID_NAME` are thrown the same way for a bad `coin` or `parent`.

### The list is missing a name you registered recently [#the-list-is-missing-a-name-you-registered-recently]

The indexer can lag the chain by a few blocks. Read `ens.indexer.getStatus()` to see how far it has indexed, or read the name on-chain with [`name.get`](/docs/reference/sdk/name/get).

### `INDEXER_UNSUPPORTED` [#indexer_unsupported]

The indexer does not serve the query or the namespace. See [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED).