What is ENS Bulk Lookup? A Complete Beginner’s Guide

The Ethereum Name Service (ENS) ecosystem has grown far beyond simple single-name resolution. As portfolios expand—whether you hold tens, hundreds, or even thousands of .eth names—managing them one by one becomes impractical. Enter ENS bulk lookup: a method to query multiple ENS domains simultaneously, retrieving their associated addresses, records, and metadata in a single operation. This guide explains the concept, the underlying mechanics, practical use cases, and the tools you need to perform bulk lookups efficiently.

ENS bulk lookup is not a single official feature of the ENS protocol; rather, it is an operational pattern built on top of ENS smart contracts and off-chain indexers. It allows you to issue one request—or a batched set of requests—to resolve many .eth names at once. This drastically reduces the number of RPC calls and processing time compared to resolving each name individually.

How ENS Resolution Works (Single vs. Bulk)

To understand bulk lookup, you must first grasp the single-name resolution flow. ENS uses two core contracts: the Registry (which maps a namehash to the resolver contract address) and the Resolver (which stores records like the owner’s address, content hash, or text records). A single lookup typically follows these steps:

1. Compute the namehash of the dot-eth name (e.g., “vitalik.eth” hash: 0x123…).
2. Query the Registry contract to get the resolver address for that namehash.
3. Call the resolver’s addr() function to retrieve the associated Ethereum address.
4. Optionally query additional records (text records, subdomains, etc.).

With bulk lookup, you batch steps 2–4 across multiple names. The most efficient approach uses a custom multicall contract (often the Multicall3 contract) that aggregates many static calls into one transaction. Alternatively, you can rely on off-chain indexers like the ENS Subgraph (hosted by The Graph) which returns results from a pre-indexed database.

Key tradeoff: On-chain multicall gives you verified real-time data but costs gas and requires a provider. Off-chain subgraph queries are faster and free but lag by a few blocks (eventual consistency). For most bulk lookup use cases, the subgraph is the preferred tool.

When to Use ENS Bulk Lookup

Bulk lookup is not a daily necessity for a casual user holding a single name. It becomes indispensable when you encounter one of these scenarios:

• Portfolio auditing: You own 50+ ENS names and want to verify their attached addresses and expiration dates in one go.
• Domain flipping / secondary market analysis: You need to scan a list of short or valuable names to check which ones have the most popular records (e.g., wallet addresses with high transaction counts).
• DApp or wallet integration: Your application displays ENS names for user contacts or recent transactions; you must resolve a batch of names at page load.
• Subdomain management: You are an ENS parent-domain owner (e.g., “company.eth”) with hundreds of subdomains (e.g., “alice.company.eth”, “bob.company.eth”). Bulk lookups let you quickly see which subdomains have active records.

Methods to Perform an ENS Bulk Lookup

There are three primary approaches, each suited to different technical skill levels.

1. Using the ENS Subgraph (GraphQL API)

The ENS Subgraph is maintained by the ENS team and indexes all domains, registrations, and resolver records. You can query it using any GraphQL client. A typical query for bulk lookup looks like this:

{
  domains(where: {name_in: ["vitalik.eth", "nick.eth", "brantly.eth"]}) {
    name
    owner { id }
    resolvedAddress { id }
    registrar { registrationDate }
    expiryDate
  }
}

This returns owner addresses, resolved addresses, and expiration dates for all three names in a single HTTP request. Advantage: Zero gas cost, instant results. Disadvantage: Data is ~5 minutes behind the main chain.

2. On-Chain Multicall

For real-time verification, use a multicall contract (commonly deployed at 0xcA11bde05977b3631167028862bE2a1733DdCA77 on Ethereum and most L2s). You construct an array of encoded resolver calls using abi.encodeWithSelector, then pass them to the multicall contract. Example pseudocode:

const calls = names.map(name => ({
  target: resolverAddress,
  callData: web3.eth.abi.encodeFunctionCall(addrAbi, [namehash(name)])
}));
const result = await multicall.aggregate(calls);

Advantage: Data is canonical and current. Disadvantage: You must know the resolver address for each name beforehand; otherwise you include an extra Registry call per name, increasing complexity.

3. Specialized Tools and Utilities

Several web-based tools wrap these APIs into a user-friendly interface. For example, you can paste a list of .eth names and retrieve their addresses in a CSV. One such utility is the Ens Generator, which can generate bulk queries and also provides a streamlined way to look up multiple domains at once. This tool handles low-level RPC calls and data formatting so you don’t need to write GraphQL or Solidity code.

Additionally, if you need to verify historical changes—such as which domains changed hands last week—you can leverage the ENS transfer history feature, which aggregates all transfer events for a given list of domains. This is especially useful when you suspect domain theft or want to analyze market movements.

A Complete Step-by-Step Walkthrough (Using the Subgraph)

Let’s do a concrete example using the subgraph. You will need a GraphQL client (like Apollo) or a simple HTTP client (like cURL or Postman). The endpoint for Ethereum mainnet is https://api.thegraph.com/subgraphs/name/ensdomains/ens.

1. Prepare your domain list: e.g., ["protagonist.eth", "antagonist.eth", "deuteragonist.eth"]. Note that names must be lowercased and contain the “.eth” suffix.
2. Write the query: Use the domains query with the name_in filter. Include fields name, owner, resolvedAddress, and expiryDate.
3. Execute the query: Send a POST request with JSON { "query": "..." } to the subgraph endpoint. The response will contain an array of matching domain objects.
4. Parse results: If a domain from your input list is not returned, it either has no ownership records or it is not registered. The subgraph only returns domains that exist in its index.
5. Handle pagination: The subgraph limits results to 1000 per query. For larger bulk lookups (10k+ domains), you must use pagination with first and skip parameters.

That’s it. You now have a programmatic way to resolve hundreds or thousands of ENS names in seconds.

Common Pitfalls and Performance Considerations

Bulk lookup is powerful, but it is not magic. Here are the main pitfalls to avoid:

• Gas cost for on-chain multicall: Each call in the batch costs a small amount of gas. A batch of 100 resolver calls might cost ~200,000 gas (roughly $5–10 at 2024 average prices). Use the subgraph for non-critical data.
• Stale subgraph data: The ENS subgraph indexes new blocks every ~30 seconds. If a domain changes owner or record 5 seconds ago, your bulk lookup will show the old state. For auditing where seconds matter, combine a subgraph query with a spot-check via RPC.
• Unregistered or invalid names: The subgraph returns null for missing names. Your code must gracefully handle cases where a name is not found (e.g., it was never registered or the namehash calculation was wrong).
• Rate limiting: Public subgraph endpoints often throttle requests. For production systems, either host your own subgraph instance or use a dedicated API key from The Graph’s decentralized network.
• Namehash differences: ENS uses Namehash, a recursive hashing algorithm. If you manually compute namehashes in your code, ensure you follow the EIP-137 spec exactly—especially for subdomains.

Real-World Use Case: Portfolio Audit

Imagine you hold 200 ENS names from a 2021 bulk registration. You want to know which names have expired, which have different owner wallets now, and which have text records. A manual single-by-single inspection would take hours. Using the subgraph bulk query, you can retrieve the entire dataset in under 5 seconds:

{
  domains(
    where: {name_in: ["domain1.eth", "domain2.eth", ...]}  // 200 names
  ) {
    name
    owner { id }
    resolvedAddress { id }
    expiryDate
    texts  // returns array of text record keys like 'email', 'url'
  }
}

Then export to a CSV. The bulk lookup tells you instantly: 12 names expired, 3 have changed owners, and 45 have a URL text record. This information is actionable—you can renew expiring domains, check ownership transfers, or update missing records.

Conclusion

ENS bulk lookup is an essential technique for anyone managing multiple .eth domains. Whether you are a power user, a market analyst, or a developer building an ENS-aware application, mastering bulk resolution saves massive time and resources. The two primary methods—off-chain subgraph queries and on-chain multicalls—cover most needs. Specialized tools like the Ens Generator simplify the process further, while the ENS transfer history feature allows you to trace domain movements at scale.

Start with the subgraph for its speed and simplicity. As your requirements grow, integrate multicall for critical real-time verifications. With bulk lookup, you turn a fragmented, manual chore into a scalable, automated operation. Begin your exploration today by testing a small batch of names against the ENS subgraph—your wallet (and your patience) will thank you.