Overview of Legacy Subgraph API

The ENS Subgraph predates ENSv2 and cannot carry your app into it. If you’re integrating ENS today, start with the ENS Omnigraph API or ENS Unigraph SQL instead. Three reasons the Subgraph falls short:

ENSv1 only — instantly out of date. The Subgraph data model has no concept of ENSv2. The moment ENSv2 launches (Summer 2026), apps still reading the Subgraph are looking at a stale, partial view of ENS.
Single-chain only — misses most names. The Subgraph indexes a single chain, so it never sees Basenames (.base.eth), Lineanames (.linea.eth), or 3DNS names (.box). The Unigraph indexes all of them into one unified model.
No resolution — and slow when you bolt it on. The Subgraph doesn’t resolve names; you’re left making your own RPC calls, which are slow. ENS Protocol Acceleration resolves names against the indexed Unigraph up to 100× faster, with no RPC round-trips in your app.

ENS Omnigraph API ENSv2-ready unified GraphQL API over both ENSv1 and ENSv2 — start here for new integrations.

The Graph & Graph Node

The Graph leads development of Graph Node, an open source software application for indexing blockchain data.

Subgraphs

Each Graph Node server can run any number of “subgraphs”. Each subgraph is essentially a plugin describing:

A strategy for how the Graph Node should index blockchain data.
A schema for a GraphQL API providing access to the indexed data.

ENS Subgraph

ENS Labs has led development of the ENS Subgraph. In the past, this was the “official” strategy for indexing ENS data. Additional background info is available in official ENS docs.

Graph Network

Operating your own Graph Node server instance can be complex, expensive, and time consuming. An alternative is to use The Graph’s semi-decentralized network of indexers operating Graph Node instances.

This network provides access to a semi-decentralized ENS Subgraph. Developers are welcome to use this rate limited API endpoint above for testing, but are highly encouraged to sign up for an account with The Graph to get their own (paid) API key.

ENSNode’s Backwards Compatibility with the ENS Subgraph

To support the ENS ecosystem’s transition away from legacy ENS indexing strategies to ENSNode, ENSNode provides a verified backwards compatible ENS Subgraph GraphQL endpoint. This therefore also provides backwards compatibility with ensjs.

For those that wish to host their own ENS indexer, it is faster and easier to deploy ENSNode than to run an ENS Subgraph instance.
For those building an app that simply want to query the legacy ENS Subgraph API in the easiest way possible, we make this freely available through our hosted ENSNode instances.

Self-hosted ENSNode instance configuration for ENS Subgraph compatibility

To enable full ENS Subgraph compatibility on a self-hosted ENSNode instance, configure ENSIndexer with SUBGRAPH_COMPAT=true. This single flag:

Applies Subgraph Indexing Behavior: Uses Subgraph Interpreted Labels and Names, allowing unnormalized labels to be returned as they appear in the original ENS Subgraph
Sets Default Plugins & Label Set: Defaults to PLUGINS=subgraph, LABEL_SET_ID=subgraph and LABEL_SET_VERSION=0 to match subgraph indexing logic and label healing behavior

When SUBGRAPH_COMPAT=false (default), ENSIndexer operates in enhanced mode with:

Enhanced Indexing Behavior: Uses Interpreted Labels and Names with improved security by encoding unnormalized labels as labelhashes
Expanded Plugin Support: Defaults to PLUGINS=subgraph,basenames,lineanames,threedns,protocol-acceleration,registrars,tokenscope for multichain ENS indexing
Reverse Address Healing: Attempts to heal subnames of addr.reverse for enhanced reverse resolution support

Compatibility Tooling

ENSNode has developed tooling to verify subgraph compatibility and ease migration from the ENS Subgraph. The tools in the ens-subgraph-transition-tools repository help users verify ENSNode’s subgraph-compatibility.

snapshot-eq — verify subgraph-equivalent data via snapshots at specific blockheights
🚧 proxy-eq — verify live query compatibility & easing migrations from the Subgraph to ENSNode by identifying any response discrepancies while using an app in real-time

See the ens-subgraph-transition-tools README for additional context and usage instructions.

ens-subgraph-transition-tools Tools for verifying ENSNode's subgraph compatibility

Subgraph-Compatible GraphQL API Reference

Well-Known Queries

These are some of the popular queries we’ve seen in the wild (namely via ENSjs and the ENSv1 Manager App)—the Subgraph-compatible GraphQL API includes full compatibility with these use-cases (and all other possible queries with the only exception of unplanned features listed below).

from ensjs

getDecodedName — Gets the full name for a name with unknown labels from the subgraph
- Heals encoded labels using the subgraph
- Returns if name is fully decoded
- Splits name into labels
- Finds domains by id for encoded labels
- Queries domain by namehash
getNameHistory
- Retrieves all events associated with a name
getNamesForAddress
- Gets all names related to an address via registrant, owner, wrappedOwner, resolvedAddress
- Supports searchString
- Supports filtering by expiry, reverse records, empty domains
- Supports ordering by expiry date, name, labelName, createdAt
- Supports pagination by excluding previous results
getSubgraphRecords — Gets the records for a name from the subgraph
- Allows querying by specific resolver id
getSubgraphRegistrant — Gets the name registrant from the subgraph
- Supports .eth second-level domains only
getSubnames — Gets the subnames for a name
- Supports searchString
- Supports filtering by expiry, empty domains
- Supports ordering by expiry date, name, labelName, createdAt
- Supports pagination by excluding previous results

from ENSv1 Manager App

useResolverExists — Checks if a resolver exists
useRegistrationData — Gets registration by id and nameRegistered events

Unplanned Features

The following features of the subgraph graphql api are explicitly unsupported and are not planned.