List names for an address
List the names an address owns, manages, holds roles on, resolves to or used to own, with filters, sorting and pagination.
By the end of this guide you can show an account's names, for a "my names" page or a name picker.
Prerequisites
- A client with an indexer and
indexerActions(). See 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
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)
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.itemsholds up tolimitnames. The default is 50 and the most is 200.- Each item is a name with
relations, the ways the address relates to it, andisPrimary, whether it is the address's primary name. page.hasMoreandpage.cursortell you whether there is another page. See Load more results.
The address can be all lowercase or checksummed. Without namespace, the list covers every namespace the indexer serves. See indexer.getNamesForAddress.
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)
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 for what owner, manager and role holder mean.
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
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.
Troubleshooting
INDEXER_NOT_CONFIGURED
The client has no indexer, or you forgot indexerActions(). See Connect an indexer and INDEXER_NOT_CONFIGURED.
INVALID_ADDRESS
The address is not a valid address. 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 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.
INDEXER_UNSUPPORTED
The indexer does not serve the query or the namespace. See INDEXER_UNSUPPORTED.
Was this page helpful?