Domain By Name

Load a domain by interpreted name, including v1/v2 discriminated fields and subregistry on ENSv2.

OmnigraphEnssdkEnskit

Run in ENSAdmin Open an interactive playground to execute this example on our sepolia-v2 ENSNode instance.

GraphQL

query DomainByName($name: InterpretedName!) {
  domain(by: {name: $name}) {
    __typename
    id
    label { interpreted hash }
    name
    owner { address }

    ... on ENSv1Domain {
      rootRegistryOwner { address }
    }

    ... on ENSv2Domain {
      subregistry {
        contract { chainId address }
      }
    }
  }
}

Payload and transport examples

Variables Response Curl

{
  "name": "test-name.eth"
}

{
  "data": {
    "domain": {
      "__typename": "ENSv2Domain",
      "id": "99911155111-0x31a2bb5d933557cce1b3129993193896d074db92-18650549467948381174706470291653511222307197070371999253038345217664991887360",
      "label": {
        "interpreted": "test-name",
        "hash": "0x293bd640008c5863fbe17a08ae5df5b2484357f5dc95e0fdd089f85e7edbfe5a"
      },
      "owner": null,
      "subregistry": null,
      "name": "test-name.eth"
    }
  }
}

# POST JSON to your ENSNode Omnigraph endpoint (same path enssdk uses).
curl -sS -X POST "https://api.v2-sepolia.ensnode.io/api/omnigraph" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{
  "query": "query DomainByName($name: InterpretedName!) { domain(by: {name: $name}) { __typename id label { interpreted hash } name owner { address } ... on ENSv1Domain { rootRegistryOwner { address } } ... on ENSv2Domain { subregistry { contract { chainId address } } } } }",
  "variables": {
    "name": "test-name.eth"
  }
}
EOF

Response is an illustrative snapshot; live data depends on your ENSNode instance. The curl tab shows a POST to https://api.v2-sepolia.ensnode.io/api/omnigraph

Run in StackBlitz Open an interactive playground to execute this example on our sepolia-v2 ENSNode instance.

TypeScript

import { createEnsNodeClient } from "enssdk/core";
import { asInterpretedName } from "enssdk";
import { graphql, omnigraph } from "enssdk/omnigraph";

const client = createEnsNodeClient({
  url: process.env.ENSNODE_URL || "https://api.v2-sepolia.ensnode.io"
}).extend(omnigraph);

const DomainByNameQuery = graphql(`
  query DomainByName($name: InterpretedName!) {
    domain(by: {name: $name}) {
      __typename
      id
      label { interpreted hash }
      name
      owner { address }

      ... on ENSv1Domain {
        rootRegistryOwner { address }
      }

      ... on ENSv2Domain {
        subregistry {
          contract { chainId address }
        }
      }
    }
  }
`);

const result = await client.omnigraph.query({
  query: DomainByNameQuery,
  variables: {
    name: asInterpretedName("test-name.eth"),
  },
});

if (result.errors) throw new Error(JSON.stringify(result.errors));
console.log(JSON.stringify(result.data, null, 2));

enssdk setup and output

Setup with NPM Setup with PNPM Output

# 1. Create project
mkdir -p my-ens-script/src && cd my-ens-script
npm init -y && touch src/index.ts
npm pkg set type=module scripts.start="tsx src/index.ts"
# 2. Install dependencies
npm install enssdk@1.13.1 && npm install -D tsx typescript @types/node
# 3. Paste the TypeScript snippet above into src/index.ts
# 4. Run
ENSNODE_URL=https://api.v2-sepolia.ensnode.io npm start

# 1. Create project
mkdir -p my-ens-script/src && cd my-ens-script
pnpm init && touch src/index.ts
pnpm pkg set type=module scripts.start="tsx src/index.ts"
# 2. Install dependencies
pnpm add enssdk@1.13.1 && pnpm add -D tsx typescript @types/node
# 3. Paste the TypeScript snippet above into src/index.ts
# 4. Run
ENSNODE_URL=https://api.v2-sepolia.ensnode.io pnpm start

{
  "data": {
    "domain": {
      "__typename": "ENSv2Domain",
      "id": "99911155111-0x31a2bb5d933557cce1b3129993193896d074db92-18650549467948381174706470291653511222307197070371999253038345217664991887360",
      "label": {
        "interpreted": "test-name",
        "hash": "0x293bd640008c5863fbe17a08ae5df5b2484357f5dc95e0fdd089f85e7edbfe5a"
      },
      "owner": null,
      "subregistry": null,
      "name": "test-name.eth"
    }
  }
}

Output matches the GraphQL Response snapshot; live output depends on your ENSNode instance. See the enssdk docs for gql.tada plugin and tsconfig setup.

Run in StackBlitz Open an interactive playground to execute this example on our sepolia-v2 ENSNode instance.

TSX (React)

import { OmnigraphProvider, useOmnigraphQuery, graphql } from "enskit/react/omnigraph";
import { createEnsNodeClient } from "enssdk/core";
import { asInterpretedName } from "enssdk";
import { omnigraph } from "enssdk/omnigraph";

const client = createEnsNodeClient({
  url: import.meta.env.VITE_ENSNODE_URL || "https://api.v2-sepolia.ensnode.io"
}).extend(omnigraph);

const DomainByNameQuery = graphql(`
  query DomainByName($name: InterpretedName!) {
    domain(by: {name: $name}) {
      __typename
      id
      label { interpreted hash }
      name
      owner { address }

      ... on ENSv1Domain {
        rootRegistryOwner { address }
      }

      ... on ENSv2Domain {
        subregistry {
          contract { chainId address }
        }
      }
    }
  }
`);

function DomainByNameResult() {
  const [result] = useOmnigraphQuery({
    query: DomainByNameQuery,
    variables: {
      name: asInterpretedName("test-name.eth"),
    },
  });
  const { data, fetching, error } = result;
  if (!data && fetching) return <p>Loading…</p>;
  if (error) return <p>Error: {error.message}</p>;
  if (!data) return <p>No data returned.</p>;
  const formatted = JSON.stringify(
    data,
    (_, value) => (typeof value === "bigint" ? value.toString() : value),
    2,
  );
  return <code>{formatted}</code>;
}

export default function App() {
  return (
    <OmnigraphProvider client={client}>
      <DomainByNameResult />
    </OmnigraphProvider>
  );
}

enskit setup and output

Setup with NPM Setup with PNPM Output

# 1. Create project
npm create vite@latest my-ens-app -- --template react-ts --no-interactive --no-immediate
cd my-ens-app
# 2. Install dependencies
npm install
npm install enskit@1.13.1 enssdk@1.13.1
# 3. Copy the TSX snippet above into src/App.tsx
# 4. Run
VITE_ENSNODE_URL=https://api.v2-sepolia.ensnode.io npm run dev

# 1. Create project
pnpm create vite@latest my-ens-app --template react-ts --no-interactive --no-immediate
cd my-ens-app
# 2. Install dependencies
pnpm install
pnpm add enskit@1.13.1 enssdk@1.13.1
# 3. Copy the TSX snippet above into src/App.tsx
# 4. Run
VITE_ENSNODE_URL=https://api.v2-sepolia.ensnode.io pnpm run dev

{
  "data": {
    "domain": {
      "__typename": "ENSv2Domain",
      "id": "99911155111-0x31a2bb5d933557cce1b3129993193896d074db92-18650549467948381174706470291653511222307197070371999253038345217664991887360",
      "label": {
        "interpreted": "test-name",
        "hash": "0x293bd640008c5863fbe17a08ae5df5b2484357f5dc95e0fdd089f85e7edbfe5a"
      },
      "owner": null,
      "subregistry": null,
      "name": "test-name.eth"
    }
  }
}

Output matches the GraphQL Response snapshot; live output depends on your ENSNode instance. See the enskit docs for gql.tada plugin and provider setup.

Back to Examples