# getNamesForAddress

Lists ENS names related to an Ethereum address.

## Import

```ts
import { getNamesForAddress } from "@ensforge/core/indexer";
```

## Usage

:::code-group
```ts [index.ts]
import { getNamesForAddress } from "@ensforge/core/indexer";
import { config } from "./config";

const result = await getNamesForAddress(config, {
  address: "0x0000000000000000000000000000000000000000",
  relations: ["owner", "resolved-address"],
  pageSize: 20,
});
```

```ts [config.ts]
// [!include ~/snippets/core/config.ts]
```
:::

## Parameters

```ts
import type { GetNamesForAddressParametersType } from "@ensforge/core/indexer";
```

### address

`0x${string}`

Address used for relation matching.

### relations

`readonly NameRelation[] | undefined`

Relations such as `"owner"`, `"registrant"`, `"wrapped-owner"`, or `"resolved-address"`. Defaults to effective ownership.

### filter

`NameFilter | undefined`

Narrows names by exact `name` or `label`, structured `search`, `owner`, `resolvedAddress`,
`resolver`, `protocol`, migration state, reachability, or expiry bounds. Conditions are combined with
AND semantics. Support is validated against the selected protocol sources before a request is sent.

`migrated` means migrated from ENSv1 to ENSv2. `true` selects migrated names from the V2
indexer; `false` includes V1 names and native V2 names. The V1 subgraph's historical registry
migration flag is not used. The returned `isMigrated` field follows the same meaning; a V1-only
source cannot establish whether a name has migrated to ENSv2.

`expiryAfter` is an exclusive lower bound and also includes names with no recorded expiry.
`expiryBefore` is an exclusive upper bound and requires a recorded expiry. When both are set,
only names with an expiry strictly between the bounds match. A missing expiry does not guarantee
that a name will remain usable: parent-name expiry or registry permissions may still affect it.

V2 queries with `expiryAfter` apply that bound locally and may fetch additional pages because the
indexer does not expose a null-expiry filter.

### order

`NameOrder | undefined`

Orders by `createdAt`, `name`, or `expiry` in `asc` or `desc` direction. The default is
`{ field: "createdAt", direction: "desc" }`. The same order must be retained when continuing from a
cursor.

### pageSize

`number | undefined`

Maximum number of items to return. It must be greater than zero and cannot exceed the
`maximumPageSize` configured for the indexer. The default is the smaller of `20` and the configured
maximum.

### cursor

`IndexerCursor | undefined`

Opaque cursor returned by the previous page. Pass it unchanged to continue the same query. A cursor
is tied to its filters, ordering, network, and enabled indexer sources; changing any of them requires
starting again without a cursor.

## Return Type

```ts
import type { GetNamesForAddressResultType } from "@ensforge/core/indexer";
```

Each item contains its normalized indexed name and the address `relation` that matched.

The result is an `IndexerPage`:

| Property               | Type                                 | Description                                                         |
| ---------------------- | ------------------------------------ | ------------------------------------------------------------------- |
| `items`                | `readonly Item[]`                    | Normalized results in deterministic cross-protocol order.           |
| `pageInfo.cursor`      | `IndexerCursor \| null`              | Cursor for the next page, or `null` when no continuation is needed. |
| `pageInfo.hasNextPage` | `boolean`                            | Whether another page is available.                                  |
| `sources`              | `readonly IndexerSourcePageStatus[]` | Per-protocol participation, block metadata, and partial failures.   |

Do not inspect or construct cursors. Persist and pass the returned value as-is.

## Protocol Sources

Enabled ENSv1 and ENSv2 sources are queried concurrently. Results are normalized, deduplicated, and merged into one stable page; partial mode records source failures in the result.

## Effect

Use `.effect` when composing the action in an Effect program. The success and error channels remain
fully typed.

```ts
import { Effect } from "effect";

const program = getNamesForAddress.effect(config, parameters);

type Success = Effect.Effect.Success<typeof program>;
type Failure = Effect.Effect.Error<typeof program>;

const result = await Effect.runPromise(program);
```

## Error

```ts
import type { GetNamesForAddressError } from "@ensforge/core/indexer";
```

The Promise API rejects with the same typed failures exposed by the Effect error channel. Errors
have a stable `_tag`, `code`, and `message`; boundary errors retain their original `cause`.

See [Error Handling](/core/guides/error-handling).

## Related

* [`sdk.indexer.getNamesForAddress`](/sdk/api/indexer/names/get-names-for-address)
* [`useNamesForAddress`](/react/api/hooks/indexer/names/use-names-for-address)