# Indexers

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

Look up the indexers, query options and result types of @ensforge/sdk/indexer, the adapters that serve search, history and name listings.

Source: https://ensforge.com/docs/reference/sdk/indexers

Exports of `@ensforge/sdk/indexer`. See [Connect an indexer](/docs/sdk/connect-an-indexer).

## Indexers [#indexers]

### `bigname` [#bigname]

The bigname indexer (`api.bigname.sh`), the indexer the ENS app uses.

```ts
function bigname(options: RestIndexerOptions & { /** Revalidate repeated reads with ETags. @default false */ cache?: boolean | undefined; } = {}): Indexer
```

Use for ENS names on mainnet and Sepolia: ENSv1 and ENSv2 state, records, subnames, history,
permissions, and verified (on-chain) records and primary names.

- Public hosts: `https://api.bigname.sh` (mainnet) and `https://sepolia.api.bigname.sh`
  (Sepolia); other chains need `url`.
- Answers can be pinned to a snapshot (`at`) and read at `safe` or `finalized` finality.
- What it serves is read from its `/status` and `/namespaces` routes on first use: a client on
  another chain, or a namespace it does not index yet (Basenames, at the time of writing),
  fails with [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED), so `fallback` moves on.
- `cache: true` revalidates repeated reads with ETags.

```ts title="Mainnet or Sepolia"
import { Ensforge } from "@ensforge/sdk"
import { bigname, indexerActions } from "@ensforge/sdk/indexer"

const ens = Ensforge.create({ publicClient, indexer: bigname() }).extend(indexerActions())
```

```ts title="A self-hosted bigname"
import { bigname } from "@ensforge/sdk/indexer"

const indexer = bigname({ url: "https://bigname.internal", headers: { authorization } })
```

```ts title="With Goldsky for Basenames"
import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer"

const indexer = fallback([bigname(), goldsky()])
```

### `defineIndexer` [#defineindexer]

Builds an indexer from your own functions, e.g. for an in-house API or a test double.

```ts
function defineIndexer(adapter: Adapter): Indexer
```

Use when your data source does not speak bigname's REST API; for one that does (a self-hosted
bigname, a proxy), pass its URL to `bigname({ url })` instead.

- Implement only the queries you serve; the others fail with [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED), so
  `fallback` moves on to the next indexer.
- Queries arrive validated: names normalized, addresses checksummed, the namespace resolved.
- Return `null` from single-resource queries (`getName`, `getRecords`, …) when nothing exists.
- Throw an ensforge error (e.g. `Errors.IndexerError`) to control how a failure is reported;
  anything else becomes [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE).

```ts title="An adapter for an in-house API"
import { defineIndexer } from "@ensforge/sdk/indexer"

const inHouse = defineIndexer({
  id: "in-house",
  getSubnames: async ({ name, cursor }, { signal }) => {
    const page = await api.subnames(name, cursor, { signal })
    return { items: page.items, cursor: page.next, hasMore: page.next !== null, totalCount: null }
  },
})
```

```ts title="Trying it before bigname"
import { Ensforge } from "@ensforge/sdk"
import { bigname, fallback } from "@ensforge/sdk/indexer"

const ens = Ensforge.create({ publicClient, indexer: fallback([inHouse, bigname()]) })
```

```ts title="A test double"
import { defineIndexer } from "@ensforge/sdk/indexer"

const indexer = defineIndexer({
  id: "test",
  getName: async ({ name }) => (name === "nick.eth" ? fixture : null),
})
```

### `fallback` [#fallback]

Asks several indexers in order: each query goes to the first one that can answer it.

```ts
function fallback(indexers: readonly Indexer[], options: { readonly on?: readonly FallbackReason[] | undefined } = {}): Indexer
```

Use to combine indexers with different coverage (bigname for Sepolia and verified reads,
Goldsky for Basenames) or to keep reading when one is down.

- The next indexer is asked when one is unavailable, rate limiting, behind, or does not serve
  the query or its namespace (`on` narrows this). Not found is an answer: it is not retried.
- Every answer reports the indexer that gave it (`indexer`).
- Cursors and `asOfToken`s are tagged with the indexer that issued them; follow-up pages and
  snapshot reads go back to that indexer only.
- When every indexer fails, the last failure that was not [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) is reported.

```ts title="bigname first, Goldsky after"
import { Ensforge } from "@ensforge/sdk"
import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer"

const ens = Ensforge.create({ publicClient, indexer: fallback([bigname(), goldsky()]) })
```

```ts title="Only when the first is down"
import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer"

const indexer = fallback([bigname(), goldsky()], { on: ["unavailable", "rateLimited"] })
```

```ts title="A self-hosted indexer first"
import { bigname, fallback } from "@ensforge/sdk/indexer"

const indexer = fallback([bigname({ url: "https://bigname.internal" }), bigname()])
```

### `goldsky` [#goldsky]

Goldsky's ENS indexer (`ens-api.goldsky.com`), which serves bigname's API for ENS and
Basenames.

```ts
function goldsky(options: RestIndexerOptions = {}): Indexer
```

Use for Basenames (`*.base.eth`), or as a second indexer behind bigname on mainnet.

- Mainnet only (ENS on chain 1, Basenames on Base); other chains need `url`.
- Reads the latest state only: `at` and `finality: "safe" | "finalized"` fail with
  [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED), as does `getResolvers`.
- Answers carry fewer fields than bigname's (no verified records, subnames without expiry);
  missing fields are `null`.

```ts title="Basenames"
import { Ensforge } from "@ensforge/sdk"
import { goldsky, indexerActions } from "@ensforge/sdk/indexer"

const ens = Ensforge.create({ publicClient, indexer: goldsky() }).extend(indexerActions())
const name = await ens.indexer.getName({ name: "jesse.base.eth" })
```

```ts title="Behind bigname"
import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer"

const indexer = fallback([bigname(), goldsky()])
```

```ts title="With an API key header"
import { goldsky } from "@ensforge/sdk/indexer"

const indexer = goldsky({ headers: { "x-api-key": key } })
```

### `indexerActions` [#indexeractions]

Adds the `indexer` actions to a client.

```ts
function indexerActions()
```

### `paginate` [#paginate]

Iterates over every page of an indexer list, following `cursor` until the last page.

```ts
async function* paginate<options extends { cursor?: string | undefined }, item>( load: (options: options) => Promise<Page<item>>, options: options, ): AsyncGenerator<Page<item>, void, undefined>
```

Use to walk a whole list, such as a name's subnames or an address's names; `break` stops
requesting further pages.

```ts title="Every subname of a name"
import { paginate } from "@ensforge/sdk/indexer"

for await (const page of paginate(ens.indexer.getSubnames, { name: "ens.eth", limit: 200 })) {
  render(page.items)
}
```

```ts title="Collecting names, at most 1,000"
import { paginate } from "@ensforge/sdk/indexer"

const names: string[] = []
for await (const page of paginate(ens.indexer.getNamesForAddress, { address })) {
  names.push(...page.items.map((item) => item.name))
  if (names.length >= 1000) break
}
```

```ts title="With a standalone action"
import { Actions } from "@ensforge/sdk"
import { paginate } from "@ensforge/sdk/indexer"

const pages = paginate(
  (options: Actions.indexer.getSubnames.Options) => Actions.indexer.getSubnames(ens, options),
  { name: "ens.eth" },
)
```

## Queries [#queries]

### `Query.Contract` [#querycontract]

A contract on the client's chain unless `chainId` says otherwise.

```ts
type Contract
```

| Field | Type | Description |
| --- | --- | --- |
| `address` | `Address` |  |
| `chainId` | `number` |  |

### `Query.GetEvents` [#querygetevents]

The query of `getEvents`.

```ts
type GetEvents = HistoryFilters & { /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; name?: string | undefined; address?: Address | undefined; resolver?: { readonly chainId: number; readonly address: Address } | undefined; /** Emitting contract. */ contract?: Address | undefined; registrationId?: string | undefined; fromBlock?: bigint | undefined; toBlock?: bigint | undefined; };
```

| Field | Type | Description |
| --- | --- | --- |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |
| `types` (optional) | `readonly EventType[]` |  |
| `excludeTypes` (optional) | `readonly EventType[]` |  |
| `recordKey` (optional) | `string` | Record key, e.g. `avatar`, `text:url` or `addr:60`. |
| `from` (optional) | `bigint \| Date` | Inclusive time bounds (Unix seconds or dates). |
| `to` (optional) | `bigint \| Date` |  |
| `order` (optional) | `"asc" \| "desc"` | Sort direction. |
| `includeData` (optional) | `boolean` | Include each event's details (`data`, `action`). @default true |
| `namespace` (optional) | `Namespace` | Only this naming system; every namespace the indexer serves when omitted. |
| `name` (optional) | `string` |  |
| `address` (optional) | `Address` |  |
| `resolver` (optional) | `{ readonly chainId: number; readonly address: Address }` |  |
| `contract` (optional) | `Address` | Emitting contract. |
| `registrationId` (optional) | `string` |  |
| `fromBlock` (optional) | `bigint` |  |
| `toBlock` (optional) | `bigint` |  |

### `Query.GetHistory` [#querygethistory]

The query of `getHistory`.

```ts
type GetHistory = HistoryFilters & ( | { name: string; /** The naming system the name belongs to. */ namespace: Namespace; address?: undefined; /** Name events, registration events, or both. @default "both" */ scope?: "name" | "registration" | "both" | undefined; /** Also the registrations of its children. */ includeChildRegistrations?: boolean | undefined; } | { address: Address; /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; name?: undefined; scope?: "name" | "registration" | "both" | undefined; /** @default ["owner", "manager", "roleHolder"] */ relation?: readonly ("owner" | "manager" | "roleHolder")[] | undefined; } );
```

| Field | Type | Description |
| --- | --- | --- |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |
| `types` (optional) | `readonly EventType[]` |  |
| `excludeTypes` (optional) | `readonly EventType[]` |  |
| `recordKey` (optional) | `string` | Record key, e.g. `avatar`, `text:url` or `addr:60`. |
| `from` (optional) | `bigint \| Date` | Inclusive time bounds (Unix seconds or dates). |
| `to` (optional) | `bigint \| Date` |  |
| `order` (optional) | `"asc" \| "desc"` | Sort direction. |
| `includeData` (optional) | `boolean` | Include each event's details (`data`, `action`). @default true |
| `name` (optional) | `string` |  |
| `namespace` (optional) | `Namespace` | The naming system the name belongs to. |
| `address` (optional) | `undefined` |  |
| `scope` (optional) | `"name" \| "registration" \| "both"` | Name events, registration events, or both. @default "both" |

### `Query.GetName` [#querygetname]

The query of `getName`.

```ts
type GetName = Snapshot & { name: string; /** The naming system the name belongs to. */ namespace: Namespace; /** `verified` reads the answer on-chain through the indexer. @default "indexed" */ source?: "indexed" | "verified" | undefined; };
```

| Field | Type | Description |
| --- | --- | --- |
| `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. |
| `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. |
| `name` | `string` |  |
| `namespace` | `Namespace` | The naming system the name belongs to. |
| `source` (optional) | `"indexed" \| "verified"` | `verified` reads the answer on-chain through the indexer. @default "indexed" |

### `Query.GetNamesByExpiry` [#querygetnamesbyexpiry]

The query of `getNamesByExpiry`.

```ts
type GetNamesByExpiry = List & { /** The naming system the name belongs to. */ namespace: Namespace; expiresAfter?: bigint | Date | undefined; expiresBefore?: bigint | Date | undefined; /** Up to 32 disjoint expiry windows; results report the matching `windowIndex`. */ windows?: readonly Window[] | undefined; graceEndsAfter?: bigint | Date | undefined; graceEndsBefore?: bigint | Date | undefined; graceWindows?: readonly Window[] | undefined; authority?: Authority | readonly Authority[] | undefined; parent?: string | undefined; /** Field the rows are sorted by. */ sort?: "expiry" | "graceEnd" | undefined; /** Sort direction. */ order?: "asc" | "desc" | undefined; };
```

| Field | Type | Description |
| --- | --- | --- |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |
| `namespace` | `Namespace` | The naming system the name belongs to. |
| `expiresAfter` (optional) | `bigint \| Date` |  |
| `expiresBefore` (optional) | `bigint \| Date` |  |
| `windows` (optional) | `readonly Window[]` | Up to 32 disjoint expiry windows; results report the matching `windowIndex`. |
| `graceEndsAfter` (optional) | `bigint \| Date` |  |
| `graceEndsBefore` (optional) | `bigint \| Date` |  |
| `graceWindows` (optional) | `readonly Window[]` |  |
| `authority` (optional) | `Authority \| readonly Authority[]` |  |
| `parent` (optional) | `string` |  |
| `sort` (optional) | `"expiry" \| "graceEnd"` | Field the rows are sorted by. |
| `order` (optional) | `"asc" \| "desc"` | Sort direction. |

### `Query.GetNamesForAddress` [#querygetnamesforaddress]

The query of `getNamesForAddress`.

```ts
type GetNamesForAddress = List & { address: Address; /** Every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; /** * Relations to list; `any` is owner, manager and role holder. `resolvesTo` and `formerOwner` * stand alone. @default "any" */ relation?: Relation | "any" | readonly Relation[] | undefined; /** Coin type for `resolvesTo`, or `evm` for every EVM chain. @default 60 */ coinType?: bigint | "evm" | undefined; /** Only direct children of this name. */ parent?: string | undefined; authority?: Authority | readonly Authority[] | undefined; /** Only names migrated to ENSv2 (or only not migrated). */ migrated?: boolean | undefined; /** Expiry bounds (Unix seconds or dates), with `formerOwner` only. */ expiresAfter?: bigint | Date | undefined; expiresBefore?: bigint | Date | undefined; search?: string | undefined; /** * Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). * * @default "prefix" */ match?: "prefix" | "contains" | undefined; /** Field the rows are sorted by. */ sort?: "name" | "expiry" | "registered" | "created" | undefined; /** Sort direction. */ order?: "asc" | "desc" | undefined; /** One row per name, or per registration. @default "name" */ dedupe?: "name" | "registration" | undefined; };
```

| Field | Type | Description |
| --- | --- | --- |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |
| `address` | `Address` |  |
| `namespace` (optional) | `Namespace` | Every namespace the indexer serves when omitted. |
| `relation` (optional) | `Relation \| "any" \| readonly Relation[]` | Relations to list; `any` is owner, manager and role holder. `resolvesTo` and `formerOwner` stand alone. @default "any" |
| `coinType` (optional) | `bigint \| "evm"` | Coin type for `resolvesTo`, or `evm` for every EVM chain. @default 60 |
| `parent` (optional) | `string` | Only direct children of this name. |
| `authority` (optional) | `Authority \| readonly Authority[]` |  |
| `migrated` (optional) | `boolean` | Only names migrated to ENSv2 (or only not migrated). |
| `expiresAfter` (optional) | `bigint \| Date` | Expiry bounds (Unix seconds or dates), with `formerOwner` only. |
| `expiresBefore` (optional) | `bigint \| Date` |  |
| `search` (optional) | `string` |  |
| `match` (optional) | `"prefix" \| "contains"` | Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). |
| `sort` (optional) | `"name" \| "expiry" \| "registered" \| "created"` | Field the rows are sorted by. |
| `order` (optional) | `"asc" \| "desc"` | Sort direction. |
| `dedupe` (optional) | `"name" \| "registration"` | One row per name, or per registration. @default "name" |

### `Query.GetNamespace` [#querygetnamespace]

The query of `getNamespace`.

```ts
type GetNamespace
```

| Field | Type | Description |
| --- | --- | --- |
| `namespace` | `Namespace` |  |

### `Query.GetPermissions` [#querygetpermissions]

The query of `getPermissions`.

```ts
type GetPermissions = List & { /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; /** Include how each grant was obtained. */ includeLineage?: boolean | undefined; } & ( | { name: string; registrationId?: undefined; address?: undefined; registry?: undefined } | { registrationId: string; name?: undefined; address?: undefined; registry?: undefined } | { address: Address; name?: undefined; registrationId?: undefined; registry?: undefined } | { registry: { readonly chainId: number; readonly address: Address }; name?: undefined; registrationId?: undefined; address?: undefined; } );
```

| Field | Type | Description |
| --- | --- | --- |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |
| `namespace` (optional) | `Namespace` | Only this naming system; every namespace the indexer serves when omitted. |
| `includeLineage` (optional) | `boolean` | Include how each grant was obtained. |
| `name` (optional) | `string` |  |
| `registrationId` (optional) | `undefined` |  |
| `address` (optional) | `undefined` |  |
| `registry` (optional) | `undefined` |  |

### `Query.GetPrimaryName` [#querygetprimaryname]

The query of `getPrimaryName`.

```ts
type GetPrimaryName
```

| Field | Type | Description |
| --- | --- | --- |
| `address` | `Address` |  |
| `coinType` (optional) | `bigint` |  |
| `namespace` (optional) | `Namespace` | Only this naming system; every namespace the indexer serves when omitted. |
| `source` (optional) | `"indexed" \| "verified"` | Both, verified first, when omitted. |

### `Query.GetRecords` [#querygetrecords]

The query of `getRecords`.

```ts
type GetRecords = Snapshot & { name: string; /** The naming system the name belongs to. */ namespace: Namespace; /** Record keys (`avatar`, `text:url`, `addr:60`, `contenthash`); the inventory's when omitted. */ keys?: readonly string[] | undefined; /** `false` returns only the inventory, without values. @default true */ values?: boolean | undefined; /** @default "indexed" */ source?: "indexed" | "verified" | "auto" | undefined; /** Read the records the name has on this resolver instead of its current one. */ resolver?: { readonly chainId: number; readonly address: Address } | undefined; };
```

| Field | Type | Description |
| --- | --- | --- |
| `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. |
| `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. |
| `name` | `string` |  |
| `namespace` | `Namespace` | The naming system the name belongs to. |
| `keys` (optional) | `readonly string[]` | Record keys (`avatar`, `text:url`, `addr:60`, `contenthash`); the inventory's when omitted. |
| `values` (optional) | `boolean` | `false` returns only the inventory, without values. @default true |
| `source` (optional) | `"indexed" \| "verified" \| "auto"` |  |
| `resolver` (optional) | `{ readonly chainId: number; readonly address: Address }` | Read the records the name has on this resolver instead of its current one. |

### `Query.GetRegistry` [#querygetregistry]

The query of `getRegistry`.

```ts
type GetRegistry = Snapshot & Contract & { includeCounts?: boolean | undefined };
```

| Field | Type | Description |
| --- | --- | --- |
| `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. |
| `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. |
| `address` | `Address` |  |
| `chainId` | `number` |  |
| `includeCounts` (optional) | `boolean` |  |

### `Query.GetRegistryLabels` [#querygetregistrylabels]

The query of `getRegistryLabels`.

```ts
type GetRegistryLabels = List & Contract & { owner?: Address | undefined; excludeOwner?: Address | undefined };
```

| Field | Type | Description |
| --- | --- | --- |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |
| `address` | `Address` |  |
| `chainId` | `number` |  |
| `owner` (optional) | `Address` |  |
| `excludeOwner` (optional) | `Address` |  |

### `Query.GetResolver` [#querygetresolver]

The query of `getResolver`.

```ts
type GetResolver = Snapshot & Contract & List;
```

| Field | Type | Description |
| --- | --- | --- |
| `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. |
| `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. |
| `address` | `Address` |  |
| `chainId` | `number` |  |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |

### `Query.GetResolverLinks` [#querygetresolverlinks]

The query of `getResolverLinks`.

```ts
type GetResolverLinks = Snapshot & Contract & List;
```

| Field | Type | Description |
| --- | --- | --- |
| `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. |
| `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. |
| `address` | `Address` |  |
| `chainId` | `number` |  |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |

### `Query.GetResolverRoles` [#querygetresolverroles]

The query of `getResolverRoles`.

```ts
type GetResolverRoles = Snapshot & Contract & List;
```

| Field | Type | Description |
| --- | --- | --- |
| `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. |
| `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. |
| `address` | `Address` |  |
| `chainId` | `number` |  |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |

### `Query.GetResolvers` [#querygetresolvers]

The query of `getResolvers`.

```ts
type GetResolvers = List & { roleHolder: Address; chainId?: number | undefined };
```

| Field | Type | Description |
| --- | --- | --- |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |
| `roleHolder` | `Address` |  |
| `chainId` (optional) | `number` |  |

### `Query.GetStatus` [#querygetstatus]

The query of `getStatus`.

```ts
type GetStatus
```

### `Query.GetSubnames` [#querygetsubnames]

The query of `getSubnames`.

```ts
type GetSubnames = List & { name: string; /** The naming system the name belongs to. */ namespace: Namespace; search?: string | undefined; /** Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). */ match?: "prefix" | "contains" | undefined; /** * Field the rows are sorted by. * * @default "name" */ sort?: "name" | "expiry" | "registered" | undefined; /** Sort direction. */ order?: "asc" | "desc" | undefined; /** @default true */ includeExpired?: boolean | undefined; };
```

| Field | Type | Description |
| --- | --- | --- |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |
| `name` | `string` |  |
| `namespace` | `Namespace` | The naming system the name belongs to. |
| `search` (optional) | `string` |  |
| `match` (optional) | `"prefix" \| "contains"` | Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). |
| `sort` (optional) | `"name" \| "expiry" \| "registered"` | Field the rows are sorted by. |
| `order` (optional) | `"asc" \| "desc"` | Sort direction. |
| `includeExpired` (optional) | `boolean` |  |

### `Query.HistoryFilters` [#queryhistoryfilters]

History filters shared by `getHistory` and `getEvents`.

```ts
type HistoryFilters = List & { types?: readonly EventType[] | undefined; excludeTypes?: readonly EventType[] | undefined; /** Record key, e.g. `avatar`, `text:url` or `addr:60`. */ recordKey?: string | undefined; /** Inclusive time bounds (Unix seconds or dates). */ from?: bigint | Date | undefined; to?: bigint | Date | undefined; /** * Sort direction. * * @default "desc" */ order?: "asc" | "desc" | undefined; /** Include each event's details (`data`, `action`). @default true */ includeData?: boolean | undefined; };
```

| Field | Type | Description |
| --- | --- | --- |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |
| `types` (optional) | `readonly EventType[]` |  |
| `excludeTypes` (optional) | `readonly EventType[]` |  |
| `recordKey` (optional) | `string` | Record key, e.g. `avatar`, `text:url` or `addr:60`. |
| `from` (optional) | `bigint \| Date` | Inclusive time bounds (Unix seconds or dates). |
| `to` (optional) | `bigint \| Date` |  |
| `order` (optional) | `"asc" \| "desc"` | Sort direction. |
| `includeData` (optional) | `boolean` | Include each event's details (`data`, `action`). @default true |

### `Query.List` [#querylist]

Paging, on list routes.

```ts
type List
```

| Field | Type | Description |
| --- | --- | --- |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |

### `Query.Lookup` [#querylookup]

The query of `lookup`.

```ts
type Lookup
```

| Field | Type | Description |
| --- | --- | --- |
| `inputs` | `readonly string[]` | Names and addresses, up to 1,000. |
| `namespace` (optional) | `Namespace` | Only this naming system; every namespace the indexer serves when omitted. |
| `profile` (optional) | `"feed" \| "detail"` | `detail` adds records and resolution. @default "feed" |

### `Query.Search` [#querysearch]

The query of `search`.

```ts
type Search = List & { query: string; /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; /** * Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). * * @default "prefix" */ match?: "prefix" | "contains" | undefined; };
```

| Field | Type | Description |
| --- | --- | --- |
| `limit` (optional) | `number` | Rows per page, 1–200. @default 50 |
| `cursor` (optional) | `string` | The previous page's `cursor`. |
| `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. |
| `query` | `string` |  |
| `namespace` (optional) | `Namespace` | Only this naming system; every namespace the indexer serves when omitted. |
| `match` (optional) | `"prefix" \| "contains"` | Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). |

### `Query.Snapshot` [#querysnapshot]

Snapshot selection, on routes that read one snapshot (names, records, registries, resolvers).

```ts
type Snapshot
```

| Field | Type | Description |
| --- | --- | --- |
| `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. |
| `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. |

### `Query.Window` [#querywindow]

A half-open window `[after, before)`, Unix seconds or dates.

```ts
type Window
```

| Field | Type | Description |
| --- | --- | --- |
| `after` | `bigint \| Date` |  |
| `before` | `bigint \| Date` |  |

## Types [#types]

### `Adapter` [#adapter]

A custom adapter: an id and the queries it answers, as Promise functions.

```ts
type Adapter = { readonly id: string; /** What distinguishes this indexer from others with the same id (see `Indexer.key`). */ readonly key?: string | undefined; } & { readonly [method in Method]?: ( query: Parameters<Methods[method]>[0], context: Context, ) => Promise<Draft<ReturnType<Methods[method]>>>; };
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `key` (optional) | `string` | What distinguishes this indexer from others with the same id (see `Indexer.key`). |

### `AddressName` [#addressname]

A name an address is related to.

```ts
type AddressName = IndexedName & { readonly relations: readonly Relation[]; /** Whether it is the address's primary name. */ readonly isPrimary: boolean; readonly migratedAt: bigint | null; readonly recordCount: number | null; readonly subnameCount: number | null; };
```

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. |
| `displayName` | `string` |  |
| `namespace` | `string` |  |
| `node` | `Hex` |  |
| `status` | `NameStatus \| null` |  |
| `authority` | `Authority \| null` |  |
| `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. |
| `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. |
| `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. |
| `createdAt` | `bigint \| null` | Unix seconds the name first appeared. |
| `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. |
| `graceEndsAt` | `bigint \| null` |  |
| `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. |
| `ensV1` | `EnsV1Facts \| null` |  |
| `relations` | `readonly Relation[]` |  |
| `isPrimary` | `boolean` | Whether it is the address's primary name. |
| `migratedAt` | `bigint \| null` |  |
| `recordCount` | `number \| null` |  |
| `subnameCount` | `number \| null` |  |

### `AnswerStatus` [#answerstatus]

Outcome of one answer inside a result (a record, a primary name, a lookup input).

```ts
type AnswerStatus = | "ok" | "notFound" | "invalidName" | "mismatch" | "unsupported" | "stale" | "failed";
```

### `Authority` [#authority]

Which ENS protocol holds a name: `ensV0` is the pre-2020 registry, `ensV1` the current ENSv1
registry, `ensV2` an ENSv2 registry.

```ts
type Authority = "ensV0" | "ensV1" | "ensV2";
```

### `ChainStatus` [#chainstatus]

Indexing progress of one chain.

```ts
type ChainStatus
```

| Field | Type | Description |
| --- | --- | --- |
| `status` | `"ready" \| "degraded" \| "stale"` |  |
| `indexed` | `bigint \| null` |  |
| `latest` | `bigint \| null` |  |
| `safe` | `bigint \| null` |  |
| `finalized` | `bigint \| null` |  |
| `lagBlocks` | `number \| null` |  |
| `lagSeconds` | `number \| null` |  |

### `Completeness` [#completeness]

How much of an answer the indexer could give. `partial` and `unsupported` come with a reason;
a partial answer is never presented as complete.

```ts
type Completeness = "full" | "partial" | "unsupported";
```

### `Context` [#context]

What an adapter knows about the call besides its query.

```ts
type Context
```

| Field | Type | Description |
| --- | --- | --- |
| `chainId` | `number` | Chain of the ensforge client, e.g. 1 for mainnet. |
| `signal` | `AbortSignal` | Aborted when the call is cancelled. |

### `ContractRef` [#contractref]

A contract on a chain.

```ts
type ContractRef
```

| Field | Type | Description |
| --- | --- | --- |
| `chainId` | `number` |  |
| `address` | `Address` |  |

### `Draft` [#draft]

What an adapter returns for an answer type: the answer, with every [`Meta`](/docs/reference/sdk/indexers#meta) field optional.
ensforge fills the missing ones (`completeness: "full"`, no snapshot) and sets `indexer` to the
adapter id.

```ts
type Draft<answer> = answer extends null ? null : Omit<answer, keyof Meta> & Partial<Meta>;
```

### `EnsV1Facts` [#ensv1facts]

ENSv1 facts about a name: its ENSv1 resolver and NameWrapper state.

```ts
type EnsV1Facts
```

| Field | Type | Description |
| --- | --- | --- |
| `resolver` | `ContractRef \| null` |  |
| `expiresAt` | `bigint \| null` |  |
| `wrapperState` | `"wrapped" \| "emancipated" \| "locked" \| "lapsed" \| "unwrapped" \| "unknown" \| null` |  |
| `wrapperExpiresAt` | `bigint \| null` |  |
| `wrapperFuses` | `number \| null` | NameWrapper fuses as a bitmap; decode with `Fuse`. |

### `ExpiringName` [#expiringname]

A name from `getNamesByExpiry`, with the window it matched.

```ts
type ExpiringName = IndexedName & { /** Index into `windows` (or `graceWindows`) that matched. */ readonly windowIndex: number | null; };
```

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. |
| `displayName` | `string` |  |
| `namespace` | `string` |  |
| `node` | `Hex` |  |
| `status` | `NameStatus \| null` |  |
| `authority` | `Authority \| null` |  |
| `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. |
| `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. |
| `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. |
| `createdAt` | `bigint \| null` | Unix seconds the name first appeared. |
| `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. |
| `graceEndsAt` | `bigint \| null` |  |
| `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. |
| `ensV1` | `EnsV1Facts \| null` |  |
| `windowIndex` | `number \| null` | Index into `windows` (or `graceWindows`) that matched. |

### `FallbackReason` [#fallbackreason]

Failures after which `fallback` asks the next indexer.

```ts
type FallbackReason = "unavailable" | "rateLimited" | "unsupported" | "behind";
```

### `IndexedEvent` [#indexedevent]

One event from an indexer's history, in the same vocabulary as `event.*`.

```ts
type IndexedEvent
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `type` | `EventType` |  |
| `action` | `EventAction \| null` | What happened; present when the event data was requested (`includeData`). |
| `kind` | `string \| null` | Indexer event kind, e.g. `RegistrationGranted`. |
| `name` | `string \| null` | The name the event is about; `null` when the indexer does not say. |
| `namespace` | `string` |  |
| `subject` | `"name" \| "child" \| null` | Whether the event is about the name or one of its children. |
| `registrationId` | `string \| null` |  |
| `contract` | `Address \| null` |  |
| `blockNumber` | `bigint \| null` |  |
| `timestamp` | `bigint \| null` |  |
| `transactionHash` | `Hex \| null` |  |
| `logIndex` | `number \| null` |  |
| `data` | `Readonly<Record<string, unknown>> \| null` | Event details with camelCase keys, when requested with `includeData`. |

### `IndexedName` [#indexedname]

A name as lists return it.

```ts
type IndexedName
```

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. |
| `displayName` | `string` |  |
| `namespace` | `string` |  |
| `node` | `Hex` |  |
| `status` | `NameStatus \| null` |  |
| `authority` | `Authority \| null` |  |
| `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. |
| `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. |
| `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. |
| `createdAt` | `bigint \| null` | Unix seconds the name first appeared. |
| `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. |
| `graceEndsAt` | `bigint \| null` |  |
| `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. |
| `ensV1` | `EnsV1Facts \| null` |  |

### `IndexedNameDetail` [#indexednamedetail]

One name in full.

```ts
type IndexedNameDetail = IndexedName & { readonly chainId: number | null; /** Indexer handle for the current registration; opaque, differs between indexers. */ readonly registrationId: string | null; readonly tokenId: bigint | null; readonly resolver: ContractRef | null; /** ENSv2 registry for the name's children. */ readonly subregistry: ContractRef | null; /** The ETH address the name resolves to. */ readonly primaryAddress: Address | null; readonly migratedAt: bigint | null; readonly records: IndexedProfile | null; readonly recordCount: number | null; readonly subnameCount: number | null; };
```

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. |
| `displayName` | `string` |  |
| `namespace` | `string` |  |
| `node` | `Hex` |  |
| `status` | `NameStatus \| null` |  |
| `authority` | `Authority \| null` |  |
| `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. |
| `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. |
| `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. |
| `createdAt` | `bigint \| null` | Unix seconds the name first appeared. |
| `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. |
| `graceEndsAt` | `bigint \| null` |  |
| `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. |
| `ensV1` | `EnsV1Facts \| null` |  |
| `chainId` | `number \| null` |  |
| `registrationId` | `string \| null` | Indexer handle for the current registration; opaque, differs between indexers. |
| `tokenId` | `bigint \| null` |  |
| `resolver` | `ContractRef \| null` |  |
| `subregistry` | `ContractRef \| null` | ENSv2 registry for the name's children. |
| `primaryAddress` | `Address \| null` | The ETH address the name resolves to. |
| `migratedAt` | `bigint \| null` |  |
| `records` | `IndexedProfile \| null` |  |
| `recordCount` | `number \| null` |  |
| `subnameCount` | `number \| null` |  |

### `IndexedPrimaryName` [#indexedprimaryname]

An address's primary name from `getPrimaryName`.

```ts
type IndexedPrimaryName
```

| Field | Type | Description |
| --- | --- | --- |
| `address` | `Address` |  |
| `coinType` | `number` |  |
| `namespace` | `string` |  |
| `name` | `string \| null` | The primary name: verified when the indexer verified it, otherwise indexed. |
| `source` | `"indexed" \| "verified" \| null` | Which answer `name` came from. |
| `answers` | `readonly PrimaryNameAnswer[]` |  |

### `IndexedProfile` [#indexedprofile]

A name's records as `getName` and `lookup` return them: values the indexer has seen.

```ts
type IndexedProfile
```

| Field | Type | Description |
| --- | --- | --- |
| `texts` | `Readonly<Record<string, string>>` |  |
| `addresses` | `Readonly<Record<string, string>>` | Addresses by decimal coin type, encoded as the chain writes them. |
| `contentHash` | `Hex \| null` |  |
| `name` | `string \| null` | Name record (ENSIP-3) of reverse names. |
| `textKeys` | `readonly string[]` | Every text key ever set, including cleared ones. |
| `coinTypes` | `readonly string[]` | Every coin type ever set, including cleared ones. |

### `IndexedRecords` [#indexedrecords]

A name's records from `getRecords`.

```ts
type IndexedRecords
```

| Field | Type | Description |
| --- | --- | --- |
| `namespace` | `string` |  |
| `resolver` | `ContractRef \| null` |  |
| `texts` | `Readonly<Record<string, string>>` |  |
| `addresses` | `Readonly<Record<string, string>>` | Addresses by decimal coin type. |
| `contentHash` | `Hex \| null` |  |
| `answers` | `Readonly<Record<string, RecordAnswer>>` | Every answer by record key (`text:avatar`, `addr:60`, `contenthash`), including failures. |
| `inventory` | `{ readonly keys: readonly string[]; readonly unsetKeys: readonly string[]; readonly unsupportedKeys: readonly string[]; } \| null` | Every record key the resolver has seen for the name. `keys` are set; `unsetKeys` were cleared; `unsupportedKeys` cannot be read through the indexer. |

### `IndexedRegistry` [#indexedregistry]

An ENSv2 registry.

```ts
type IndexedRegistry
```

| Field | Type | Description |
| --- | --- | --- |
| `chainId` | `number` |  |
| `address` | `Address` |  |
| `name` | `string \| null` | The name whose children it holds, when known. |
| `parent` | `ContractRef \| null` |  |
| `createdAt` | `bigint \| null` |  |
| `createdBlockNumber` | `bigint \| null` |  |
| `createdTransactionHash` | `Hex \| null` |  |
| `counts` | `{ readonly labels: number \| null; readonly roles: number \| null; readonly events: number \| null; } \| null` |  |
| `referencedBy` | `readonly string[]` | Names whose subregistry pointer is this registry. |

### `IndexedResolver` [#indexedresolver]

A resolver and the names bound to it.

```ts
type IndexedResolver
```

| Field | Type | Description |
| --- | --- | --- |
| `chainId` | `number` |  |
| `address` | `Address` |  |
| `names` | `readonly string[]` | Names using this resolver, one page of them. |
| `cursor` | `string \| null` |  |
| `hasMore` | `boolean` |  |
| `mirrors` | `ContractRef \| null` | ENSv1 registry this resolver mirrors, for ENSv1 compatibility resolvers. |

### `Indexer` [#indexer]

An indexer ensforge reads through: `bigname()`, `goldsky()`, `fallback([...])` or
`defineIndexer({...})`. Pass it to `Ensforge.create({ indexer })`.

```ts
interface Indexer
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Adapter id, reported as `indexer` on every answer. |
| `key` | `string` | The adapter and where it reads from, e.g. `bigname:https://bigname.internal`: two indexers with the same key answer alike, so caches (React's) can share their answers. |
| `~ensforge/indexer` | `true` |  |

### `IndexerActions` [#indexeractions-1]

`indexer` actions bound to a client.

```ts
type IndexerActions
```

| Field | Type | Description |
| --- | --- | --- |
| `indexer` | `{ /** Searches indexed ENS events by name, address, resolver, contract or block range. */ readonly getEvents: Bound<typeof indexer.getEvents>; /** Reads the full history of a name, or of every name an address is related to. */ readonly getHistory: Bound<typeof indexer.getHistory>; /** Reads one name from the indexer: owner, manager, expiry, resolver, records and protocol. */ readonly getName: Bound<typeof indexer.getName>; /** Lists names by when they expire or leave their grace period. */ readonly getNamesByExpiry: Bound<typeof indexer.getNamesByExpiry>; /** Lists the names an address owns, manages, holds roles on, resolves to, or used to own. */ readonly getNamesForAddress: Bound<typeof indexer.getNamesForAddress>; /** Reads what the indexer serves for a namespace: its networks and which features are complete. */ readonly getNamespace: Bound<typeof indexer.getNamespace>; /** Lists who can do what over a name, a registration, an account or an ENSv2 registry. */ readonly getPermissions: Bound<typeof indexer.getPermissions>; /** Reads an address's primary name from the indexer, verified on-chain when the indexer can. */ readonly getPrimaryName: Bound<typeof indexer.getPrimaryName>; /** Reads a name's records and its record inventory from the indexer. */ readonly getRecords: Bound<typeof indexer.getRecords>; /** Reads an ENSv2 registry: the name it serves, its parent registry, when it was created and its counts. */ readonly getRegistry: Bound<typeof indexer.getRegistry>; /** Lists the labels of an ENSv2 registry, optionally only those an address holds or does not hold. */ readonly getRegistryLabels: Bound<typeof indexer.getRegistryLabels>; /** Reads a resolver and one page of the names bound to it. */ readonly getResolver: Bound<typeof indexer.getResolver>; /** Lists the names linked to record sets on an ENSv2 resolver. */ readonly getResolverLinks: Bound<typeof indexer.getResolverLinks>; /** Lists the role grants on an ENSv2 resolver. */ readonly getResolverRoles: Bound<typeof indexer.getResolverRoles>; /** Lists the ENSv2 resolvers on which an address holds roles. */ readonly getResolvers: Bound<typeof indexer.getResolvers>; /** Reads the indexer's health and how far each chain is indexed. */ readonly getStatus: Bound<typeof indexer.getStatus>; /** Lists the direct subnames of a name. */ readonly getSubnames: Bound<typeof indexer.getSubnames>; /** Reads up to 1,000 names and addresses in one request. */ readonly lookup: Bound<typeof indexer.lookup>; /** Searches names by text. */ readonly search: Bound<typeof indexer.search>; }` |  |

### `IndexerStatus` [#indexerstatus]

An indexer's health.

```ts
type IndexerStatus
```

| Field | Type | Description |
| --- | --- | --- |
| `status` | `"ready" \| "degraded" \| "stale"` |  |
| `chains` | `Readonly<Record<number, ChainStatus>>` |  |
| `indexer` | `string` |  |

### `LookupResult` [#lookupresult]

One input's answer from `lookup`.

```ts
type LookupResult
```

| Field | Type | Description |
| --- | --- | --- |
| `input` | `string` |  |
| `kind` | `"name" \| "address"` |  |
| `status` | `AnswerStatus` |  |
| `name` | `(IndexedNameDetail & { readonly isPrimary: boolean \| null }) \| null` | A name input, or an address's primary name. |
| `names` | `readonly (IndexedNameDetail & { readonly isPrimary: boolean \| null })[]` | An address input's related names. |
| `reason` | `string \| null` |  |

### `Meta` [#meta]

What every indexer answer carries besides its data.

```ts
type Meta
```

| Field | Type | Description |
| --- | --- | --- |
| `asOf` | `Snapshot \| null` | Snapshot of the answer's main chain, or `null` when the indexer reports none. |
| `snapshots` | `Readonly<Record<number, Snapshot>>` | Every chain the answer read, keyed by chain ID. |
| `asOfToken` | `string \| null` | Pass back as `at: { token }` to read the same snapshot again (snapshot routes only). `null` when the indexer does not support snapshots. |
| `completeness` | `Completeness` |  |
| `unsupportedReason` | `string \| null` | Why the answer is partial or unsupported. |
| `unsupportedFields` | `readonly string[]` | Fields the indexer could not fill. |
| `origin` | `"indexed" \| "verified" \| null` | Whether the indexer answered from its index or by an on-chain read. |
| `indexer` | `string` | Id of the adapter that answered, e.g. `bigname`. |

### `Method` [#method]

Name of an indexer query.

```ts
type Method = keyof Methods;
```

### `Methods` [#methods]

Every query an adapter can answer, with its query and answer types. `null` answers mean
"not found".

```ts
type Methods
```

| Field | Type | Description |
| --- | --- | --- |
| `getName` | `(query: Query.GetName) => Result<IndexedNameDetail> \| null` |  |
| `getNamesForAddress` | `(query: Query.GetNamesForAddress) => Page<AddressName>` |  |
| `getSubnames` | `(query: Query.GetSubnames) => Page<Subname>` |  |
| `getHistory` | `(query: Query.GetHistory) => Page<IndexedEvent>` |  |
| `getEvents` | `(query: Query.GetEvents) => Page<IndexedEvent>` |  |
| `search` | `(query: Query.Search) => Page<IndexedName>` |  |
| `lookup` | `(query: Query.Lookup) => Result<{ readonly results: readonly LookupResult[] }>` |  |
| `getNamesByExpiry` | `(query: Query.GetNamesByExpiry) => Page<ExpiringName>` |  |
| `getPrimaryName` | `(query: Query.GetPrimaryName) => Result<IndexedPrimaryName>` |  |
| `getRecords` | `(query: Query.GetRecords) => Result<IndexedRecords> \| null` |  |
| `getPermissions` | `(query: Query.GetPermissions) => Page<PermissionRow>` |  |
| `getRegistry` | `(query: Query.GetRegistry) => Result<IndexedRegistry> \| null` |  |
| `getRegistryLabels` | `(query: Query.GetRegistryLabels) => Page<RegistryLabel>` |  |
| `getResolver` | `(query: Query.GetResolver) => Result<IndexedResolver> \| null` |  |
| `getResolverLinks` | `(query: Query.GetResolverLinks) => Page<ResolverLink>` |  |
| `getResolverRoles` | `(query: Query.GetResolverRoles) => Page<ResolverRole>` |  |
| `getResolvers` | `(query: Query.GetResolvers) => Page<RoleHolderResolver>` |  |
| `getNamespace` | `(query: Query.GetNamespace) => Result<NamespaceInfo> \| null` |  |
| `getStatus` | `(query: Query.GetStatus) => IndexerStatus` |  |

### `NameStatus` [#namestatus]

A name's registration lifecycle.

```ts
type NameStatus = "active" | "expired" | "released" | "unregistered";
```

### `Namespace` [#namespace]

A naming system an indexer serves: ENS, or Basenames (`*.base.eth`, on Base).

```ts
type Namespace = "ens" | "basenames";
```

### `NamespaceInfo` [#namespaceinfo]

What an indexer serves for one namespace.

```ts
type NamespaceInfo
```

| Field | Type | Description |
| --- | --- | --- |
| `namespace` | `string` |  |
| `capabilities` | `Readonly<Record<string, Completeness>>` | Feature (e.g. `subnames`, `verified_records`) → completeness. |
| `networks` | `readonly { readonly network: string; readonly chainId: number \| null; /** ENS protocol resolving on that network, and since which block. */ readonly protocol: "ensV1" \| "ensV2" \| null; readonly sinceBlock: bigint \| null; }[]` |  |

### `Page` [#page]

One page of a list, with its [`Meta`](/docs/reference/sdk/indexers#meta).

```ts
type Page<item> = Meta & { readonly items: readonly item[]; /** Pass as `cursor` for the next page; `null` on the last page. */ readonly cursor: string | null; readonly hasMore: boolean; /** Total across pages, when requested with `includeTotal` and the indexer can count. */ readonly totalCount: number | null; };
```

| Field | Type | Description |
| --- | --- | --- |
| `asOf` | `Snapshot \| null` | Snapshot of the answer's main chain, or `null` when the indexer reports none. |
| `snapshots` | `Readonly<Record<number, Snapshot>>` | Every chain the answer read, keyed by chain ID. |
| `asOfToken` | `string \| null` | Pass back as `at: { token }` to read the same snapshot again (snapshot routes only). `null` when the indexer does not support snapshots. |
| `completeness` | `Completeness` |  |
| `unsupportedReason` | `string \| null` | Why the answer is partial or unsupported. |
| `unsupportedFields` | `readonly string[]` | Fields the indexer could not fill. |
| `origin` | `"indexed" \| "verified" \| null` | Whether the indexer answered from its index or by an on-chain read. |
| `indexer` | `string` | Id of the adapter that answered, e.g. `bigname`. |
| `items` | `readonly item[]` |  |
| `cursor` | `string \| null` | Pass as `cursor` for the next page; `null` on the last page. |
| `hasMore` | `boolean` |  |
| `totalCount` | `number \| null` | Total across pages, when requested with `includeTotal` and the indexer can count. |

### `PermissionRow` [#permissionrow]

A permission one address holds over a name, registry or resolver.

```ts
type PermissionRow
```

| Field | Type | Description |
| --- | --- | --- |
| `address` | `Address` |  |
| `name` | `string \| null` |  |
| `registrationId` | `string` |  |
| `powers` | `readonly string[]` | Powers in the indexer's vocabulary, e.g. `set_resolver`, `admin_renew`. |
| `scope` | `string` | Where the grant applies: `registry`, `registration`, `resolver`, … |
| `relation` | `"operator" \| "holder" \| null` |  |
| `wrapperState` | `"wrapped" \| "emancipated" \| "locked" \| null` | NameWrapper state the permission depends on. |
| `lineage` | `Readonly<Record<string, unknown>> \| null` |  |

### `PrimaryNameAnswer` [#primarynameanswer]

One primary name answer.

```ts
type PrimaryNameAnswer
```

| Field | Type | Description |
| --- | --- | --- |
| `source` | `"indexed" \| "verified"` |  |
| `status` | `AnswerStatus` |  |
| `name` | `string \| null` |  |
| `reason` | `string \| null` |  |

### `RecordAnswer` [#recordanswer]

One record answer from `getRecords`.

```ts
type RecordAnswer
```

| Field | Type | Description |
| --- | --- | --- |
| `status` | `AnswerStatus` |  |
| `value` | `string \| null` |  |
| `reason` | `string \| null` |  |

### `RegistryLabel` [#registrylabel]

A label in an ENSv2 registry.

```ts
type RegistryLabel = Subname & { readonly roleHolderCount: number | null; };
```

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. |
| `displayName` | `string` |  |
| `namespace` | `string` |  |
| `node` | `Hex` |  |
| `status` | `NameStatus \| null` |  |
| `authority` | `Authority \| null` |  |
| `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. |
| `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. |
| `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. |
| `createdAt` | `bigint \| null` | Unix seconds the name first appeared. |
| `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. |
| `graceEndsAt` | `bigint \| null` |  |
| `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. |
| `ensV1` | `EnsV1Facts \| null` |  |
| `labelhash` | `Hex \| null` |  |
| `subnameCount` | `number \| null` |  |
| `subregistry` | `ContractRef \| null` |  |
| `roleHolderCount` | `number \| null` |  |

### `Relation` [#relation]

How an address relates to a name.

```ts
type Relation = "owner" | "manager" | "roleHolder" | "resolvesTo" | "formerOwner";
```

### `ResolverLink` [#resolverlink]

A name linked to a record set on an ENSv2 resolver.

```ts
type ResolverLink
```

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` |  |
| `node` | `Hex` |  |
| `recordId` | `string` |  |
| `isDefault` | `boolean` | Whether it is the resolver's default record set. |
| `blockNumber` | `bigint \| null` |  |
| `transactionHash` | `Hex \| null` |  |

### `ResolverRole` [#resolverrole]

A role grant on an ENSv2 resolver.

```ts
type ResolverRole
```

| Field | Type | Description |
| --- | --- | --- |
| `address` | `Address` |  |
| `name` | `string \| null` |  |
| `registrationId` | `string` |  |
| `powers` | `readonly string[]` |  |
| `blockNumber` | `bigint \| null` |  |

### `RestIndexerOptions` [#restindexeroptions]

Connection options shared by the built-in REST indexers.

```ts
type RestIndexerOptions
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `url` | `string` | the public host for the client's chain | Base URL of a server with the same API (self-hosted, a proxy). A version path (`/v1`) is added unless the URL ends with one. |
| `headers` | `Readonly<Record<string, string>>` |  | Extra request headers, e.g. an API key. |
| `fetch` | `typeof fetch` |  | `fetch` to send requests with. @default globalThis.fetch |
| `timeout` | `number` |  | Milliseconds per request before it is retried or fails. @default 15_000 |
| `retryCount` | `number` | `2` | Retries of rate-limited, unavailable and timed-out requests; `Retry-After` is honoured. |

### `Result` [#result]

One answer with its [`Meta`](/docs/reference/sdk/indexers#meta).

```ts
type Result<data> = data & Meta;
```

| Field | Type | Description |
| --- | --- | --- |
| `asOf` | `Snapshot \| null` | Snapshot of the answer's main chain, or `null` when the indexer reports none. |
| `snapshots` | `Readonly<Record<number, Snapshot>>` | Every chain the answer read, keyed by chain ID. |
| `asOfToken` | `string \| null` | Pass back as `at: { token }` to read the same snapshot again (snapshot routes only). `null` when the indexer does not support snapshots. |
| `completeness` | `Completeness` |  |
| `unsupportedReason` | `string \| null` | Why the answer is partial or unsupported. |
| `unsupportedFields` | `readonly string[]` | Fields the indexer could not fill. |
| `origin` | `"indexed" \| "verified" \| null` | Whether the indexer answered from its index or by an on-chain read. |
| `indexer` | `string` | Id of the adapter that answered, e.g. `bigname`. |

### `RoleHolderResolver` [#roleholderresolver]

A resolver on which an address holds roles.

```ts
type RoleHolderResolver = ContractRef & { readonly grantCount: number; readonly powers: readonly string[]; };
```

| Field | Type | Description |
| --- | --- | --- |
| `chainId` | `number` |  |
| `address` | `Address` |  |
| `grantCount` | `number` |  |
| `powers` | `readonly string[]` |  |

### `Snapshot` [#snapshot]

The chain state an answer was read at.

```ts
type Snapshot
```

| Field | Type | Description |
| --- | --- | --- |
| `chainId` | `number` |  |
| `blockNumber` | `bigint` |  |
| `blockHash` | `Hex` |  |
| `timestamp` | `bigint` | Unix seconds. |

### `Subname` [#subname]

A direct child of a name.

```ts
type Subname = IndexedName & { readonly labelhash: Hex | null; readonly subnameCount: number | null; readonly subregistry: ContractRef | null; };
```

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. |
| `displayName` | `string` |  |
| `namespace` | `string` |  |
| `node` | `Hex` |  |
| `status` | `NameStatus \| null` |  |
| `authority` | `Authority \| null` |  |
| `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. |
| `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. |
| `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. |
| `createdAt` | `bigint \| null` | Unix seconds the name first appeared. |
| `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. |
| `graceEndsAt` | `bigint \| null` |  |
| `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. |
| `ensV1` | `EnsV1Facts \| null` |  |
| `labelhash` | `Hex \| null` |  |
| `subnameCount` | `number \| null` |  |
| `subregistry` | `ContractRef \| null` |  |