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

indexer.lookup

Reads up to 1,000 names and addresses in one request. Parameters, return value, errors and examples for indexer.lookup in @ensforge/sdk.

ReadBatchablestable
Since v1.0.0View source

Reads up to 1,000 names and addresses in one request.

When to use

Use to render lists of names or accounts at once, e.g. a feed or a table of holders.

Details

  • Each input answers on its own: names with their state, addresses with their primary name and related names.
  • An input that fails (an invalid name) reports status instead of failing the whole lookup.
  • profile: "detail" adds records and resolution to each answer.

Signature

function lookup(client: Like, options: lookup.Options): Promise<lookup.ReturnType>

Call it as ens.indexer.lookup(options) on a client, or Actions.indexer.lookup(client, options).

indexer.lookup.request(options) builds a deferred read for Actions.batch. See Look up many at once.

Parameters

OptionTypeDefaultDescription
inputs (required)readonly string[]Names and addresses, up to 1,000.
namespaceNamespaceOnly this naming system; every namespace the indexer serves when omitted.
profile"feed" | "detail"detail adds records and resolution. @default "feed"

Also takes the read options.

Returns

Resolves to Result<{ readonly results: readonly LookupResult[] }>. One answer per input, in input order.

Errors

ErrorCodesWhen
InvalidInputErrorINVALID_RECORD_VALUEmore than 1,000 inputs or none.
ConfigErrorINDEXER_NOT_CONFIGUREDthe client has no indexer.
IndexerErrorINDEXER_UNSUPPORTEDthe indexer does not serve the query or its namespace.
IndexerErrorINDEXER_UNAVAILABLE, INDEXER_RATE_LIMITED, INDEXER_BEHIND, INDEXER_REQUEST_REJECTED, INDEXER_RESPONSE_INVALIDthe indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly.

It can also fail with the errors every read can (Errors.CommonError: ConfigError, ContractRevertError, InternalError, NetworkError).

See How errors work.

Examples

Reading names and addresses together
const { results } = await ens.indexer.lookup({ inputs: ["nick.eth", "0xd8dA…"] })

Example response

Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does.

await ens.indexer.lookup({ inputs: ["nick.eth", "vitalik.eth"] })
{
  "results": [
    {
      "input": "nick.eth",
      "kind": "name",
      "status": "ok",
      "name": {
        "name": "nick.eth",
        "displayName": "nick.eth",
        "namespace": "ens",
        "node": "0x05a67c0ee82964c4f7394cdd47fee7f4d9503a23c09c38341779ea012afe6e00",
        "status": "active",
        "authority": "ensV2",
        "owner": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
        "manager": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
        "registeredAt": "1600896646n",
        "createdAt": "1571924851n",
        "expiresAt": "2051983306n",
        "graceEndsAt": "2054402506n",
        "expiryReason": null,
        "ensV1": null,
        "chainId": 1,
        "registrationId": "0cf467d0-e851-5285-bf04-bcab99cab4da",
        "tokenId": "42219085255511335250589442208301538195142221433306354426240614732610656010240n",
        "resolver": {
          "chainId": 1,
          "address": "0xF4f1007EA430848F2fAd60e405A54Fc100fEc341"
        },
        "subregistry": {
          "chainId": 1,
          "address": "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753"
        },
        "primaryAddress": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
        "migratedAt": "1793114183n",
        "records": {
          "texts": {
            "avatar": "https://euc.li/nick.eth",
            "com.discord": "nickjohnson",
            "com.github": "arachnid",
            "com.reddit": "nickjohnson",
            "com.twitter": "nicksdjohnson",
            "description": "Lead developer of ENS & Ethereum Foundation alum. Certified rat tickler. he/him.",
            "email": "arachnid@notdot.net",
            "eth.ens.delegate": "https://discuss.ens.domains/t/ens-dao-delegate-applications/815/716",
            "org.telegram": "nicksdjohnson",
            "snapshot": "ipns://storage.snapshot.page/registry/0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5/nick.eth",
            "url": "https://ens.domains/"
          },
          "addresses": {
            "60": "0xb8c2c29ee19d8307cb7255e1cd9cbde883a267d5"
          },
          "contentHash": "0xe5010172002408011220066e20f72cc583d769bc8df5fedff24942b3b8941e827f023d306bdc7aecf5ac",
          "name": null,
          "textKeys": [
            "avatar",
            "com.discord",
            "com.github",
            "com.reddit",
            "com.twitter",
            "description",
            "email",
            "eth.ens.delegate",
            "org.telegram",
            "snapshot",
            "url"
          ],
          "coinTypes": [
            "60"
          ]
        },
        "recordCount": null,
        "subnameCount": null,
        "isPrimary": null
      },
      "names": [],
      "reason": null
    },
    {
      "input": "vitalik.eth",
      "kind": "name",
      "status": "ok",
      "name": {
        "name": "vitalik.eth",
        "displayName": "vitalik.eth",
        "namespace": "ens",
        "node": "0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835",
        "status": "active",
        "authority": "ensV1",
        "owner": "0x220866B1A2219f40e72f5c628B65D54268cA3A9D",
        "manager": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "registeredAt": "1581013420n",
        "createdAt": "1497775154n",
        "expiresAt": "2469399224n",
        "graceEndsAt": "2471818424n",
        "expiryReason": null,
        "ensV1": {
          "resolver": {
            "chainId": 1,
            "address": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63"
          },
          "expiresAt": "2464042424n",
          "wrapperState": "unwrapped",
          "wrapperExpiresAt": null,
          "wrapperFuses": null
        },
        "chainId": 1,
        "registrationId": "1e452d59-7d47-54a4-adfa-80a8ed0c09d2",
        "tokenId": "79233663829379634837589865448569342784712482819484549289560981379859480642508n",
        "resolver": {
          "chainId": 1,
          "address": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63"
        },
        "subregistry": null,
        "primaryAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "migratedAt": null,
        "records": {
          "texts": {
            "avatar": "https://euc.li/vitalik.eth",
            "com.github": "vbuterin",
            "com.twitter": "VitalikButerin",
            "description": "mi pinxe lo crino tcati",
            "header": "https://pbs.twimg.com/profile_banners/295218901/1638557376/1500x500",
            "pgp": "527E406252E06A11416D7487698FEAC70F922A21",
            "url": "https://vitalik.ca"
          },
          "addresses": {
            "60": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
          },
          "contentHash": "0xe301017012201d261cc098861d9952e6c8954801800e56aa34aabd8a9651b04b4e2498a45c53",
          "name": null,
          "textKeys": [
            "avatar",
            "com.github",
            "com.twitter",
            "description",
            "header",
            "pgp",
            "url"
          ],
          "coinTypes": [
            "60"
          ]
        },
        "recordCount": null,
        "subnameCount": null,
        "isPrimary": null
      },
      "names": [],
      "reason": null
    }
  ],
  "asOf": {
    "chainId": 1,
    "blockNumber": "26443965n",
    "blockHash": "0xc9de37cc3c9ec10dde4ac1f9abcd65d3dca66f5c50f248ff60d142bb09e0e52a",
    "timestamp": "1795029155n"
  },
  "snapshots": {
    "1": {
      "chainId": 1,
      "blockNumber": "26443965n",
      "blockHash": "0xc9de37cc3c9ec10dde4ac1f9abcd65d3dca66f5c50f248ff60d142bb09e0e52a",
      "timestamp": "1795029155n"
    }
  },
  "asOfToken": "7b22657468657265756d223a7b22626c6f636b5f68617368223a22307863396465333763633363396563313064646534616331663961626364363564336463613636663563353066323438666636306431343262623039653065353261222c22626c6f636b5f6e756d626572223a32363434333936352c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c2274696d657374616d70223a22323032362d31312d31385431393a31323a33355a227d7d",
  "completeness": "full",
  "unsupportedReason": null,
  "unsupportedFields": [],
  "origin": null,
  "indexer": "bigname"
}

See also

  • Actions.batch for on-chain reads together

Was this page helpful?