Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeSDK

Get a name's owner, expiry and status

Read who owns a name, when it expires, which resolver it uses, and whether it can be registered or renewed, in a single call.

By the end of this guide you can read the full state of a name in one call: who owns it, when it expires, which resolver it uses, and whether anyone can register or renew it.

Prerequisites

Get the state of a name

name.get returns everything ensforge knows about a name's registration. ensforge finds out where the name lives and reads it there, so you do not choose a contract.

Example (Showing a Renewal Banner)

get-name-details.ts
import { ensActions, Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
}).extend(ensActions());

const state = await ens.name.get({ name: "ens.eth" });
if (state.status === "grace") {
  console.log("In the grace period until", new Date(Number(state.gracePeriodEnd) * 1000));
} else if (state.expiry !== null) {
  console.log("Expires", new Date(Number(state.expiry) * 1000));
}
  • status tells where the name is in its life. See the table below.
  • expiry and gracePeriodEnd are Unix seconds as bigint, or null when they do not apply. Multiply by 1000 for a JavaScript Date.
  • Times come from the block the read runs at, not from your local clock.

See name.get.

Read the result

FieldDescription
nameThe normalised name.
status"available", "registered", "grace", "expired" or "reserved".
ownerWho ultimately controls the name (owner).
managerThe registry owner of an unwrapped name (the "manager" in the ENS app), or null.
registrantThe holder of an unwrapped .eth name's registration token, or null.
resolverThe resolver set on the name itself, or null.
inheritedResolverThe resolver serving a name that has none of its own, such as a parent's wildcard or off-chain resolver. null otherwise.
expiryUnix seconds when the registration ends, grace period excluded. null when it never expires.
gracePeriodEndUnix seconds when the .eth grace period ends.
availableWhether the name can be registered now.
renewableWhether the name can be renewed now: .eth names that are registered or in grace.
kind and protocolWhere the name lives. Most apps never need them. See ENS versions under the hood.

status: "grace" applies to .eth names after they expire: during the grace period anyone can still renew the name, but nobody can register it. "expired" names can be registered again. For who may change a name, see Who can change a name.

Check availability

available and renewable answer the two questions a registration page asks. For prices and the full flow, see Check if a name is available.

Example (Checking Availability)

is-available.ts
import { ensActions, Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
}).extend(ensActions());

const { available, renewable } = await ens.name.get({ name: "nick.eth" });

name.get costs two batched RPC calls whatever the name kind. A name with no resolver of its own that a parent's resolver serves costs one more.

Options

OptionTypeDefaultDescription
namestringrequiredThe name to read. Normalised for you.
signalAbortSignalnoneCancels the call.
blockNumber or blockTagbigint or a block tagthe client's block tagReads at one block, never both.

Troubleshooting

A name that resolves is reported as available

A name served only by a parent's wildcard or off-chain resolver, such as jesse.base.eth, is in no registry. Its resolver is null and its status is "available", although it resolves. Check inheritedResolver: when it is not null, something serves the name. See Look up off-chain names.

INVALID_NAME

The name is invalid, or it is the root. INVALID_NAME is thrown before any request is sent.

RPC_REQUEST_FAILED or RPC_TIMEOUT

The RPC request failed or timed out, with RPC_REQUEST_FAILED or RPC_TIMEOUT. Check your RPC endpoint. See Configure RPC and gateways.

Was this page helpful?