Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeSDK

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.

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)

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.

The address can be all lowercase or checksummed. Without namespace, the list covers every namespace the indexer serves. See indexer.getNamesForAddress.

relation is one value or a list of these:

RelationThe 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)

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 for what owner, manager and role holder mean.

Filter, search and sort

OptionTypeDefaultDescription
addressstringrequiredThe address to list names for.
namespace"ens" or "basenames"every namespace the indexer servesLimits the list to one naming system.
relationrelation, list of relations, or "any""any"Which relations to list.
coinsymbol, { chainId }, bigint or "evm"60Coin type for relation: "resolvesTo". "evm" means every EVM chain.
parentstringnoneOnly direct children of this name.
authority"ensV0", "ensV1", "ensV2", or a listnoneOnly names held by that protocol.
migratedbooleannoneOnly names that moved to ENSv2, or only those that did not.
searchstringnoneOnly names that match this text.
match"prefix" or "contains""prefix"How search matches.
sort"name", "expiry", "registered" or "created"the indexer's defaultWhat to sort by. bigname sorts by name, and formerOwner lists by expiry.
order"asc" or "desc"the indexer's defaultSort direction. bigname sorts ascending.
dedupe"name" or "registration""name"One row per name, or per registration.
expiresAfter, expiresBeforebigint or DatenoneExpiry bounds. Only with relation: "formerOwner".
limitnumber50Names per page, 1 to 200.
cursorstringnoneThe previous page's cursor.
includeTotalbooleanfalseCount every row into totalCount. Slower.
signalAbortSignalnoneCancels the call.

Read the result

Each item in page.items has:

FieldDescription
nameThe normalised name. Unknown labels appear as [labelhash].
relationsHow the address relates to the name.
isPrimaryWhether it is the address's primary name.
owner, managerWho holds the name.
status"active", "expired", "released" or "unregistered", or null.
expiresAt, graceEndsAtUnix seconds as bigint, or null. A name that never expires has 2^64 - 1.
recordCount, subnameCountHow 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?