Find Domains

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

omnigraphenssdkenskitcurl

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

GraphQL

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

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

Variables

{
  "name": {
    "starts_with": "sf"
  },
  "order": {
    "by": "NAME",
    "dir": "DESC"
  }
}

Output

{
  "data": {
    "domains": {
      "edges": [
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-49509597771493908415463190501045916291230588437784211605615168713991762477056",
            "label": {
              "interpreted": "sfmpfvtoicv2ok",
              "hash": "0x6d757075b889ecac34ee231b86f1d6dd54544aa24ade226b398204cbd771cbc7"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfvtoicv2ok.eth",
                "beautified": "sfmpfvtoicv2ok.eth"
              }
            },
            "registration": {
              "expiry": "1781810940",
              "event": {
                "timestamp": "1779391740"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-37259562946248504018379781627254217478007643438678910837598068740925220192256",
            "label": {
              "interpreted": "sfmpfv44d0res",
              "hash": "0x52602a50858115661619fb28cf543ee766c182e0be6743c72d5bd674b3d12686"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0res.eth",
                "beautified": "sfmpfv44d0res.eth"
              }
            },
            "registration": {
              "expiry": "1816283593",
              "event": {
                "timestamp": "1779390804"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "11155111-0xb6fb46e1458915dd828633d91e1df8e4c3f2d4dd-0x9b365136312d7ee6e232e3c98e459bc8667ec818c47fbbc55bb5e23d0a21e8cc",
            "label": {
              "interpreted": "sfmpfv44d0mig",
              "hash": "0x427ff8f9f4fd0a505202d30de02a518dccf3124efeffec27a25430835b3f309e"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0mig.eth",
                "beautified": "sfmpfv44d0mig.eth"
              }
            },
            "registration": {
              "expiry": "1810926648",
              "event": {
                "timestamp": "1779390648"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-30078755955643454526763071980293195785165410039216352470119925106082295316480",
            "label": {
              "interpreted": "sfmpfv44d0mig",
              "hash": "0x427ff8f9f4fd0a505202d30de02a518dccf3124efeffec27a25430835b3f309e"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0mig.eth",
                "beautified": "sfmpfv44d0mig.eth"
              }
            },
            "registration": {
              "expiry": "1816283449",
              "event": {
                "timestamp": "1779390984"
              }
            }
          }
        }
      ]
    }
  }
}

Output matches a GraphQL Response snapshot; live output depends on your ENSNode instance.

Run in StackBlitz Opens an editable StackBlitz project with this snippet.

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: DomainsNameFilter!
    $order: DomainsOrderInput
  ) {
    domains(
      where: { name: $name }
      order: $order
      first: 20
    ) {
      edges {
        node {
          __typename
          id
          label { interpreted hash }
          canonical { name { interpreted beautified } }

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

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

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

Output

{
  "data": {
    "domains": {
      "edges": [
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-49509597771493908415463190501045916291230588437784211605615168713991762477056",
            "label": {
              "interpreted": "sfmpfvtoicv2ok",
              "hash": "0x6d757075b889ecac34ee231b86f1d6dd54544aa24ade226b398204cbd771cbc7"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfvtoicv2ok.eth",
                "beautified": "sfmpfvtoicv2ok.eth"
              }
            },
            "registration": {
              "expiry": "1781810940",
              "event": {
                "timestamp": "1779391740"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-37259562946248504018379781627254217478007643438678910837598068740925220192256",
            "label": {
              "interpreted": "sfmpfv44d0res",
              "hash": "0x52602a50858115661619fb28cf543ee766c182e0be6743c72d5bd674b3d12686"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0res.eth",
                "beautified": "sfmpfv44d0res.eth"
              }
            },
            "registration": {
              "expiry": "1816283593",
              "event": {
                "timestamp": "1779390804"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "11155111-0xb6fb46e1458915dd828633d91e1df8e4c3f2d4dd-0x9b365136312d7ee6e232e3c98e459bc8667ec818c47fbbc55bb5e23d0a21e8cc",
            "label": {
              "interpreted": "sfmpfv44d0mig",
              "hash": "0x427ff8f9f4fd0a505202d30de02a518dccf3124efeffec27a25430835b3f309e"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0mig.eth",
                "beautified": "sfmpfv44d0mig.eth"
              }
            },
            "registration": {
              "expiry": "1810926648",
              "event": {
                "timestamp": "1779390648"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-30078755955643454526763071980293195785165410039216352470119925106082295316480",
            "label": {
              "interpreted": "sfmpfv44d0mig",
              "hash": "0x427ff8f9f4fd0a505202d30de02a518dccf3124efeffec27a25430835b3f309e"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0mig.eth",
                "beautified": "sfmpfv44d0mig.eth"
              }
            },
            "registration": {
              "expiry": "1816283449",
              "event": {
                "timestamp": "1779390984"
              }
            }
          }
        }
      ]
    }
  }
}

Output matches a GraphQL Response snapshot; live output depends on your ENSNode instance.

enssdk package manager setup

npm pnpm

# 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.15.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.15.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

See the enssdk docs for gql.tada plugin and tsconfig setup.

Run in StackBlitz Opens an editable StackBlitz project with this snippet.

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: DomainsNameFilter!
    $order: DomainsOrderInput
  ) {
    domains(
      where: { name: $name }
      order: $order
      first: 20
    ) {
      edges {
        node {
          __typename
          id
          label { interpreted hash }
          canonical { name { interpreted beautified } }

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

function FindDomainsResult() {
  const [result] = useOmnigraphQuery({
    query: FindDomainsQuery,
    variables:     {
      name: {
        "starts_with": "sf"
      },
      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>
  );
}

Output

{
  "data": {
    "domains": {
      "edges": [
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-49509597771493908415463190501045916291230588437784211605615168713991762477056",
            "label": {
              "interpreted": "sfmpfvtoicv2ok",
              "hash": "0x6d757075b889ecac34ee231b86f1d6dd54544aa24ade226b398204cbd771cbc7"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfvtoicv2ok.eth",
                "beautified": "sfmpfvtoicv2ok.eth"
              }
            },
            "registration": {
              "expiry": "1781810940",
              "event": {
                "timestamp": "1779391740"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-37259562946248504018379781627254217478007643438678910837598068740925220192256",
            "label": {
              "interpreted": "sfmpfv44d0res",
              "hash": "0x52602a50858115661619fb28cf543ee766c182e0be6743c72d5bd674b3d12686"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0res.eth",
                "beautified": "sfmpfv44d0res.eth"
              }
            },
            "registration": {
              "expiry": "1816283593",
              "event": {
                "timestamp": "1779390804"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "11155111-0xb6fb46e1458915dd828633d91e1df8e4c3f2d4dd-0x9b365136312d7ee6e232e3c98e459bc8667ec818c47fbbc55bb5e23d0a21e8cc",
            "label": {
              "interpreted": "sfmpfv44d0mig",
              "hash": "0x427ff8f9f4fd0a505202d30de02a518dccf3124efeffec27a25430835b3f309e"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0mig.eth",
                "beautified": "sfmpfv44d0mig.eth"
              }
            },
            "registration": {
              "expiry": "1810926648",
              "event": {
                "timestamp": "1779390648"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-30078755955643454526763071980293195785165410039216352470119925106082295316480",
            "label": {
              "interpreted": "sfmpfv44d0mig",
              "hash": "0x427ff8f9f4fd0a505202d30de02a518dccf3124efeffec27a25430835b3f309e"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0mig.eth",
                "beautified": "sfmpfv44d0mig.eth"
              }
            },
            "registration": {
              "expiry": "1816283449",
              "event": {
                "timestamp": "1779390984"
              }
            }
          }
        }
      ]
    }
  }
}

Output matches a GraphQL Response snapshot; live output depends on your ENSNode instance.

enskit package manager setup

npm pnpm

# 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.15.1 enssdk@1.15.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.15.1 enssdk@1.15.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

See the enskit docs for gql.tada plugin and provider setup.

cURL

# 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: DomainsNameFilter! $order: DomainsOrderInput ) { domains( where: { name: $name } order: $order first: 20 ) { edges { node { __typename id label { interpreted hash } canonical { name { interpreted beautified } } registration { expiry event { timestamp } } } } } }",
  "variables": {
    "name": {
      "starts_with": "sf"
    },
    "order": {
      "by": "NAME",
      "dir": "DESC"
    }
  }
}
EOF

Response

{
  "data": {
    "domains": {
      "edges": [
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-49509597771493908415463190501045916291230588437784211605615168713991762477056",
            "label": {
              "interpreted": "sfmpfvtoicv2ok",
              "hash": "0x6d757075b889ecac34ee231b86f1d6dd54544aa24ade226b398204cbd771cbc7"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfvtoicv2ok.eth",
                "beautified": "sfmpfvtoicv2ok.eth"
              }
            },
            "registration": {
              "expiry": "1781810940",
              "event": {
                "timestamp": "1779391740"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-37259562946248504018379781627254217478007643438678910837598068740925220192256",
            "label": {
              "interpreted": "sfmpfv44d0res",
              "hash": "0x52602a50858115661619fb28cf543ee766c182e0be6743c72d5bd674b3d12686"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0res.eth",
                "beautified": "sfmpfv44d0res.eth"
              }
            },
            "registration": {
              "expiry": "1816283593",
              "event": {
                "timestamp": "1779390804"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv1Domain",
            "id": "11155111-0xb6fb46e1458915dd828633d91e1df8e4c3f2d4dd-0x9b365136312d7ee6e232e3c98e459bc8667ec818c47fbbc55bb5e23d0a21e8cc",
            "label": {
              "interpreted": "sfmpfv44d0mig",
              "hash": "0x427ff8f9f4fd0a505202d30de02a518dccf3124efeffec27a25430835b3f309e"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0mig.eth",
                "beautified": "sfmpfv44d0mig.eth"
              }
            },
            "registration": {
              "expiry": "1810926648",
              "event": {
                "timestamp": "1779390648"
              }
            }
          }
        },
        {
          "node": {
            "__typename": "ENSv2Domain",
            "id": "11155111-0x64c81210d0e580cfc7746f3fb910bf0e8f6378e1-30078755955643454526763071980293195785165410039216352470119925106082295316480",
            "label": {
              "interpreted": "sfmpfv44d0mig",
              "hash": "0x427ff8f9f4fd0a505202d30de02a518dccf3124efeffec27a25430835b3f309e"
            },
            "canonical": {
              "name": {
                "interpreted": "sfmpfv44d0mig.eth",
                "beautified": "sfmpfv44d0mig.eth"
              }
            },
            "registration": {
              "expiry": "1816283449",
              "event": {
                "timestamp": "1779390984"
              }
            }
          }
        }
      ]
    }
  }
}

Output matches a GraphQL Response snapshot; live output depends on your ENSNode instance.

Back to Examples