The Ethereum Name Service (ENS) is a decentralized domain name system built on the Ethereum blockchain. ENS converts machine‐readable identifiers like wallet addresses and content hashes into human‐readable names (e.g., “alice.eth”). To efficiently query this distributed data, developers and users have turned to ENS GraphQL—a query language and runtime that sits atop the ENS subgraph. This article explains the core mechanisms, data schema, query patterns, and integration possibilities of ENS GraphQL, providing a neutral, technically grounded overview of everything you need to know.
What Is ENS GraphQL and Why Was It Built?
ENS GraphQL is a specialized GraphQL interface that exposes data from the ENS smart contracts on Ethereum, as indexed and stored by a decentralized indexing protocol known as The Graph. Instead of reading raw blockchain logs or calling contract functions directly—which can be slow and expensive—developers can use ENS GraphQL to run sophisticated queries on ENS registrations, resolutions, subdomains, and expirations with single requests.
The need for ENS GraphQL arose from blockchain data complexity. ENS contracts generate numerous events (e.g., Transfer, NewOwner, NewResolver) that must be decoded and aggregated to answer questions such as “Which .eth names does address X own?” or “What records does domain Y have?” Prior to the subgraph, developers had to parse hundreds of historical logs or maintain their own off‑chain indexers. ENS GraphQL standardizes this process. The subgraph continuously listens for ENS contract events, applies transformation logic, and writes processed data to an underlying SQL‑like store. GraphQL then acts as the query layer, letting applications request exactly the fields they need.
A practical benefit is speed. Queries that would require dozens of web3 calls to traverse ENS’s hierarchical structure (e.g., resolving a name through its resolver contract) can be answered in a single HTTP request to the ENS GraphQL endpoint. For an example of how to combine ENS resolution with wallet interaction, readers can refer to a step‑by‑step ens coinbase wallet tutorial that demonstrates graphical integration.
Core Architecture: How the ENS Subgraph and GraphQL Work Together
The ENS GraphQL ecosystem comprises three layers: the ENS smart contracts on Ethereum (mainnet and testnets), the ENS subgraph on The Graph’s decentralized network (or hosted service), and the GraphQL endpoint. The subgraph is defined by a manifest file (subgraph.yaml) that specifies data sources, event handlers, and schema entities. Mapping functions in AssemblyScript/Asc parse events such as “NameRegistered” and update entity fields like Domain, Registration, Resolver, and Account.
Key entities in the ENS GraphQL schema include:
- Domain: Represents an ENS node (name). Fields include name, labelName, labelhash, owner, resolver, and expiryDate.
- Registration: Tracks the registration life cycle. Contains registrationDate, expiryDate, and relation to the Domain entity.
- Resolver: Stores resolved addresses, content hashes, texts, and other records linked to a resolver contract.
- Account: Represents an Ethereum address that owns domains. Provides reverse lookups.
The GraphQL schema mirrors these entities with rich relationships. A typical query requests a domain’s owner and resolver address, then fetches the resolved ETH address or other records. The subgraph indexes all historical events, so historical data—for auditing or analytics—is equally accessible.
To query live data, the user sends a POST request to the ENS subgraph endpoint (e.g., https://api.thegraph.com/subgraphs/name/ensdomains/ens). The response is JSON. Because the subgraph runs on a decentralized network of indexers (for the main ENS subgraph), queries are censorship‑resistant and verifiable. For advanced integrations such as resolving reverse records (e.g., mapping an address back to a .eth name), the eip 181 standard defines the on‑chain reverse resolution logic—a complementary specification that GraphQL can consume via its own subgraph mappings.
How to Write Queries: Common Patterns and Examples
ENS GraphQL uses the standard GraphQL query syntax. Below are three common query patterns developers use.
1. Look up a domain’s owner and resolved address
{
domains(where: {name: "vitalik.eth"}) {
owner {
id
}
resolver {
addr {
id
}
}
}
}
This returns the owner (wallet) of vitalik.eth and the Ethereum address to which it resolves. The response is flat and fast.
2. List all domains owned by an address
{
accounts(where: {id: "0x123..."}) {
domains(first: 50) {
name
expiryDate
resolver {
addr {
id
}
}
}
}
}
Using the Account entity, you can paginate through domains. This replaces walking through ERC‑721 transfer events manually.
3. Fetch domains expiring soon
{
registrations(
where: {expiryDate_lt: "1700000000"}
orderBy: expiryDate
orderDirection: asc
) {
domain {
name
}
expiryDate
}
}
This pattern is useful for renewal alerts. GraphQL’s filtering and ordering standards make it straightforward.
Queries can nest multiple levels—fetching subdomains, text records (e.g., email, avatar URL), or content hashes (IPFS). Because the subgraph indexes all events, no separate API call is needed for each record type. The GraphQL server resolves the relational data in a single round trip.
Advanced Queries and Real‑World Use Cases
Beyond basic lookups, ENS GraphQL powers production applications in decentralized identity, analytics, and wallet integrations. Three prominent use cases are considered here.
Analytics dashboards: Teams like Dune Analytics or Glassnode can build dashboards that show domain registration rates, renewal activity, and top registrars—all via GraphQL queries aggregating multiple domains. For example, fetching all registrations over the last 30 days grouped by registration date.
{
registrations(
where: {registrationDate_gte: "1690000000"}
orderBy: registrationDate
orderDirection: desc
) {
registrationDate
domain {
name
}
}
}
Wallet and dApp name resolution: Many Web3 wallets (e.g., MetaMask, Rainbow) use ENS GraphQL endpoints to display human‑readable names alongside addresses. When a user inputs “vitalik.eth,” the wallet sends a query to the ENS subgraph for the resolved address, then a second query (if needed) for reverse resolution. The speed of GraphQL allows near‑instant UI updates. For a practical integration guide that includes wallet interaction flows, the aforementioned ens coinbase wallet tutorial provides a concrete implementation path.
Subdomain management platforms: Services like ENS Subdomains allow users to create and manage subdomains without paying new Ethereum gas fees for each record change. These platforms use ENS GraphQL to list all subdomains owned by a parent domain (e.g., all *.mydomain.eth subdomains) in a paginated UI. CRUD operations are then sent as on‑chain transactions, while the subgraph reflects updates within minutes.
Each of these use cases benefits from GraphQL’s ability to reduce over‑fetching—the application receives only the exact fields required for display or processing, saving bandwidth and parsing overhead.
Limitations, Security, and Best Practices
While ENS GraphQL is powerful, developers should be aware of four limitations.
Data latency: The subgraph lags behind the Ethereum chain by roughly 5–120 seconds depending on network traffic and indexing topology. For applications that require real‑time data (e.g., auction systems), you must fall back to event listeners or direct contract queries.
Historical reorgs: The Graph may contain orphaned data if a blockchain reorganization occurs. The hosted service handles small reorgs automatically, but developers building on the decentralized network should ensure their application tolerates transient state differences by verifying critical data via an archive node.
Query depth and complexity: GraphQL endpoints cap query depth (typically 10–20 levels) and complexity to prevent abuse. Applications traversing deep ENS hierarchies (e.g., all subdomains of a subdomain) should design queries recursively but stay within endpoint rate limits.
Authentication and cost: The public ENS subgraph endpoint is free but rate‑limited. For production apps, request an API key from The Graph’s hosted service or run your own dedicated subgraph. No authentication is required for basic queries; the endpoint is read‑only.
Security best practices include sanitizing any user‑supplied name fragments in query variables, using GraphQL variables (not string interpolation) to avoid injection, and validating that returned resolver addresses match known ENS resolver contracts (to prevent fake resolution records). The ENS subgraph only indexes conforming contracts, but caution is prudent.
For reverse resolution, always verify that the reverse record’s forward resolution matches the original address. This double‑check leverages the standard defined in eip 181 and can be automated in your GraphQL query workflow. Also, monitor the subgraph’s health status via The Graph’s network explorer; an unhealthy subgraph may produce incomplete results.
The Future of ENS GraphQL and Decentralized Data Indexing
The ENS GraphQL endpoint will continue to evolve with the ENS protocol itself. Upcoming ENSIPs may add new record types (e.g., L2 addresses) that the subgraph will index. The Graph’s move to a decentralized network (ARBITRUM‑based for settlement) means query results will be validated by multiple indexers—supporting trustlessness. For developers, tooling like graphql‑code‑generator can produce TypeScript types directly from the ENS schema, reducing boilerplate. ENS GraphQL remains the de facto standard for reading ENS state off‑chain, and its integration with wallet software, analytics, and identity platforms solidifies its role as an essential layer in the Web3 stack.