# Name history

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

Read everything that happened to a name or an account, from its first event to the latest, as a list of ownership and record events.

Source: https://ensforge.com/docs/sdk/name-history

By the end of this guide you can show an activity feed for a name or an account: registrations, renewals, transfers, resolver and record changes.

## Prerequisites [#prerequisites]

- For full history, a client with an [indexer](/docs/reference/glossary#indexer) and `indexerActions()`. See [Connect an indexer](/docs/sdk/connect-an-indexer).
- For recent events only, a plain client is enough. See [Read recent events from the chain](#read-recent-events-from-the-chain).

## Read the full history of a name [#read-the-full-history-of-a-name]

`indexer.getHistory` returns one page of events, newest first.

**Example** (Reading a Name's History)

```ts title="name-history.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.getHistory({ name: "nick.eth", limit: 25 });

for (const event of page.items) {
  console.log(event.type, event.action, event.timestamp, event.transactionHash);
}
```

- Events carry the same `type` and `action` vocabulary as the on-chain `event.get`.
- `order: "asc"` returns the oldest first.
- Each event includes its details in `data`, unless you pass `includeData: false`.
- `scope` picks the name's own events, its registrations' events, or `"both"` (the default).

See [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) and [Load more results](/docs/sdk/load-more-results).

## Filter the history [#filter-the-history]

**Example** (Reading Transfers and Avatar Changes)

```ts title="history-filters.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 transfers = await ens.indexer.getHistory({ name: "nick.eth", types: ["transfer"] });

const avatarChanges = await ens.indexer.getHistory({
  name: "nick.eth",
  recordKey: "avatar",
  order: "asc",
});
```

## Read the history of an account [#read-the-history-of-an-account]

Pass an `address` instead of a `name` to read the events of every name the address is related to. By default `relation` follows owner, manager and role holder.

**Example** (Reading an Account's Activity)

```ts title="account-history.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.getHistory({
  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  types: ["registration", "renewal", "transfer"],
});
```

## Read recent events from the chain [#read-recent-events-from-the-chain]

`event.get` reads a name's events straight from the chain over a block range. It needs no indexer, and shows the same kinds of events. Use it for recent activity, or to see the effect of a write.

**Example** (Reading Recent Events)

```ts title="recent-events.ts"
import { ensActions, Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

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

const head = await publicClient.getBlockNumber();
const events = await ens.event.get({ name: "nick.eth", fromBlock: head - 50_000n });

for (const event of events) {
  console.log(event.type, event.action, event.blockNumber);
}
```

- `fromBlock` is required. `toBlock` defaults to `"latest"`.
- Events come back in chain order.
- Ranges the RPC provider rejects are split. After `maxRequests` `eth_getLogs` requests (default 500), the read fails with [`LOG_RANGE_TOO_LARGE`](/docs/reference/errors/LOG_RANGE_TOO_LARGE) instead of sending more.
- `event.get` covers one name. Address-wide and full history needs an indexer.

See [`event.get`](/docs/reference/sdk/event/get).

## Options [#options]

`indexer.getHistory` takes a `name` or an `address`, plus:

| Option                            | Type                                           | Default                                                | Description                                                             |
| --------------------------------- | ---------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- |
| `name`                            | `string`                                       | required without `address`                             | The name whose history to read.                                         |
| `address`                         | `string`                                       | required without `name`                                | The account whose names' history to read.                               |
| `namespace`                       | `"ens"` or `"basenames"`                       | inferred from the name, every namespace for an address | Naming system to read.                                                  |
| `scope`                           | `"name"`, `"registration"` or `"both"`         | `"both"`                                               | Name events, registration events, or both.                              |
| `types`                           | list of event types                            | none                                                   | Only these types.                                                       |
| `excludeTypes`                    | list of event types                            | none                                                   | Leave these types out.                                                  |
| `recordKey`                       | `string`                                       | none                                                   | Only changes to this record, such as `avatar`, `text:url` or `addr:60`. |
| `from`, `to`                      | `bigint` or `Date`                             | none                                                   | Inclusive time bounds, in Unix seconds or dates.                        |
| `order`                           | `"asc"` or `"desc"`                            | `"desc"`                                               | Newest first by default.                                                |
| `includeData`                     | `boolean`                                      | `true`                                                 | Include each event's `data` and `action`.                               |
| `includeChildRegistrations`       | `boolean`                                      | none                                                   | With `name`: also the registrations of its children.                    |
| `relation`                        | list of `"owner"`, `"manager"`, `"roleHolder"` | all three                                              | With `address`: which relations to follow.                              |
| `limit`, `cursor`, `includeTotal` |                                                |                                                        | Paging. See [Load more results](/docs/sdk/load-more-results).           |

Event types are `registration`, `renewal`, `release`, `expiry`, `transfer`, `authority`, `resolver`, `record`, `primary_name`, `permission`, `subregistry`, `migration`, `reservation`, `token` and `contract`.

## Troubleshooting [#troubleshooting]

### `INDEXER_NOT_FOUND` [#indexer_not_found]

The indexer has no such name. [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) is thrown for a name that has never been indexed. Check the spelling, or read the name on-chain.

### `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).

### `LOG_RANGE_TOO_LARGE` [#log_range_too_large]

The block range for `event.get` is too large for your RPC provider's log limits. Use a smaller range, or read the history from an indexer.

### A recent change is missing [#a-recent-change-is-missing]

The indexer can lag the chain by a few blocks. Read `ens.indexer.getStatus()`, or use `event.get` for the latest blocks. See [Watch for changes](/docs/sdk/watch-for-changes).