Find Domains

List domains matching a name prefix with ordering and registration metadata.

OmnigraphEnssdkEnskit

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

GraphQL

query FindDomains(
  $name: String!
  $order: DomainsOrderInput
) {
  domains(
    where: { name: $name }
    order: $order
    first: 20
  ) {
    edges {
      node {
        __typename
        id
        label { interpreted hash }
        name

        registration { expiry event { timestamp } }
      }
    }
  }
}

Payload and transport examples

Variables Response Curl

{
  "name": "test-na",
  "order": {
    "by": "NAME",
    "dir": "DESC"
  }
}

{
  "data": {
    "domains": {
      "edges": [
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "99911155111-0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e-0xfef70852da2a0a32225b513391c3dcf0f3b5cccf343bde23fa1f8464cbe5a2c2",
            "label": {
              "interpreted": "test-names",
              "hash": "0xf8899b8332fc898c86bfe588219b29362bb1335ce9738d7a34508d817ab31133"
            },
            "registration": {
              "expiry": "1751190612",
              "event": {
                "timestamp": "1747216212"
              }
            },
            "name": "test-names.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "99911155111-0x31a2bb5d933557cce1b3129993193896d074db92-14580361689616036777059995592070852680799975896349261373821065539059361775616",
            "label": {
              "interpreted": "test-namers",
              "hash": "0x203c3138956e0cab1c57684ba6b9cf550db4e624055a6b0e30caee16609eac9d"
            },
            "registration": {
              "expiry": "1793279532",
              "event": {
                "timestamp": "1777667178"
              }
            },
            "name": "test-namers.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "99911155111-0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e-0x598e24a25300d326443e87af828c71764964f2e318850c2a517e9dc0115b43c9",
            "label": {
              "interpreted": "test-namers",
              "hash": "0x203c3138956e0cab1c57684ba6b9cf550db4e624055a6b0e30caee16609eac9d"
            },
            "registration": {
              "expiry": "1793279532",
              "event": {
                "timestamp": "1761743532"
              }
            },
            "name": "test-namers.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "99911155111-0x31a2bb5d933557cce1b3129993193896d074db92-18650549467948381174706470291653511222307197070371999253038345217664991887360",
            "label": {
              "interpreted": "test-name",
              "hash": "0x293bd640008c5863fbe17a08ae5df5b2484357f5dc95e0fdd089f85e7edbfe5a"
            },
            "registration": {
              "expiry": "1785702972",
              "event": {
                "timestamp": "1777667203"
              }
            },
            "name": "test-name.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "99911155111-0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e-0x527f8d39fa87ac23b6431913e880aa29425dc0450651a22d9a3b881a29661a0b",
            "label": {
              "interpreted": "test-name",
              "hash": "0x293bd640008c5863fbe17a08ae5df5b2484357f5dc95e0fdd089f85e7edbfe5a"
            },
            "registration": {
              "expiry": "1785702972",
              "event": {
                "timestamp": "1754166972"
              }
            },
            "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 FindDomains( $name: String! $order: DomainsOrderInput ) { domains( where: { name: $name } order: $order first: 20 ) { edges { node { __typename id label { interpreted hash } name registration { expiry event { timestamp } } } } } }",
  "variables": {
    "name": "test-na",
    "order": {
      "by": "NAME",
      "dir": "DESC"
    }
  }
}
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 { graphql, omnigraph } from "enssdk/omnigraph";

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

const FindDomainsQuery = graphql(`
  query FindDomains(
    $name: String!
    $order: DomainsOrderInput
  ) {
    domains(
      where: { name: $name }
      order: $order
      first: 20
    ) {
      edges {
        node {
          __typename
          id
          label { interpreted hash }
          name

          registration { expiry event { timestamp } }
        }
      }
    }
  }
`);

const result = await client.omnigraph.query({
  query: FindDomainsQuery,
  variables: {
    name: "test-na",
    order: {
      "by": "NAME",
      "dir": "DESC"
    },
  },
});

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": {
    "domains": {
      "edges": [
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "99911155111-0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e-0xfef70852da2a0a32225b513391c3dcf0f3b5cccf343bde23fa1f8464cbe5a2c2",
            "label": {
              "interpreted": "test-names",
              "hash": "0xf8899b8332fc898c86bfe588219b29362bb1335ce9738d7a34508d817ab31133"
            },
            "registration": {
              "expiry": "1751190612",
              "event": {
                "timestamp": "1747216212"
              }
            },
            "name": "test-names.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "99911155111-0x31a2bb5d933557cce1b3129993193896d074db92-14580361689616036777059995592070852680799975896349261373821065539059361775616",
            "label": {
              "interpreted": "test-namers",
              "hash": "0x203c3138956e0cab1c57684ba6b9cf550db4e624055a6b0e30caee16609eac9d"
            },
            "registration": {
              "expiry": "1793279532",
              "event": {
                "timestamp": "1777667178"
              }
            },
            "name": "test-namers.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "99911155111-0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e-0x598e24a25300d326443e87af828c71764964f2e318850c2a517e9dc0115b43c9",
            "label": {
              "interpreted": "test-namers",
              "hash": "0x203c3138956e0cab1c57684ba6b9cf550db4e624055a6b0e30caee16609eac9d"
            },
            "registration": {
              "expiry": "1793279532",
              "event": {
                "timestamp": "1761743532"
              }
            },
            "name": "test-namers.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "99911155111-0x31a2bb5d933557cce1b3129993193896d074db92-18650549467948381174706470291653511222307197070371999253038345217664991887360",
            "label": {
              "interpreted": "test-name",
              "hash": "0x293bd640008c5863fbe17a08ae5df5b2484357f5dc95e0fdd089f85e7edbfe5a"
            },
            "registration": {
              "expiry": "1785702972",
              "event": {
                "timestamp": "1777667203"
              }
            },
            "name": "test-name.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "99911155111-0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e-0x527f8d39fa87ac23b6431913e880aa29425dc0450651a22d9a3b881a29661a0b",
            "label": {
              "interpreted": "test-name",
              "hash": "0x293bd640008c5863fbe17a08ae5df5b2484357f5dc95e0fdd089f85e7edbfe5a"
            },
            "registration": {
              "expiry": "1785702972",
              "event": {
                "timestamp": "1754166972"
              }
            },
            "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 { omnigraph } from "enssdk/omnigraph";

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

const FindDomainsQuery = graphql(`
  query FindDomains(
    $name: String!
    $order: DomainsOrderInput
  ) {
    domains(
      where: { name: $name }
      order: $order
      first: 20
    ) {
      edges {
        node {
          __typename
          id
          label { interpreted hash }
          name

          registration { expiry event { timestamp } }
        }
      }
    }
  }
`);

function FindDomainsResult() {
  const [result] = useOmnigraphQuery({
    query: FindDomainsQuery,
    variables: {
      name: "test-na",
      order: {
        "by": "NAME",
        "dir": "DESC"
      },
    },
  });
  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}>
      <FindDomainsResult />
    </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": {
    "domains": {
      "edges": [
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "99911155111-0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e-0xfef70852da2a0a32225b513391c3dcf0f3b5cccf343bde23fa1f8464cbe5a2c2",
            "label": {
              "interpreted": "test-names",
              "hash": "0xf8899b8332fc898c86bfe588219b29362bb1335ce9738d7a34508d817ab31133"
            },
            "registration": {
              "expiry": "1751190612",
              "event": {
                "timestamp": "1747216212"
              }
            },
            "name": "test-names.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "99911155111-0x31a2bb5d933557cce1b3129993193896d074db92-14580361689616036777059995592070852680799975896349261373821065539059361775616",
            "label": {
              "interpreted": "test-namers",
              "hash": "0x203c3138956e0cab1c57684ba6b9cf550db4e624055a6b0e30caee16609eac9d"
            },
            "registration": {
              "expiry": "1793279532",
              "event": {
                "timestamp": "1777667178"
              }
            },
            "name": "test-namers.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "99911155111-0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e-0x598e24a25300d326443e87af828c71764964f2e318850c2a517e9dc0115b43c9",
            "label": {
              "interpreted": "test-namers",
              "hash": "0x203c3138956e0cab1c57684ba6b9cf550db4e624055a6b0e30caee16609eac9d"
            },
            "registration": {
              "expiry": "1793279532",
              "event": {
                "timestamp": "1761743532"
              }
            },
            "name": "test-namers.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "99911155111-0x31a2bb5d933557cce1b3129993193896d074db92-18650549467948381174706470291653511222307197070371999253038345217664991887360",
            "label": {
              "interpreted": "test-name",
              "hash": "0x293bd640008c5863fbe17a08ae5df5b2484357f5dc95e0fdd089f85e7edbfe5a"
            },
            "registration": {
              "expiry": "1785702972",
              "event": {
                "timestamp": "1777667203"
              }
            },
            "name": "test-name.eth"
          }
        },
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "99911155111-0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e-0x527f8d39fa87ac23b6431913e880aa29425dc0450651a22d9a3b881a29661a0b",
            "label": {
              "interpreted": "test-name",
              "hash": "0x293bd640008c5863fbe17a08ae5df5b2484357f5dc95e0fdd089f85e7edbfe5a"
            },
            "registration": {
              "expiry": "1785702972",
              "event": {
                "timestamp": "1754166972"
              }
            },
            "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