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

name.get

Reads the full state of a name across ENSv1 and ENSv2: where it lives, who owns it, its resolver, expiry and whether it can be registered or renewed.

ReadBatchablestable
Since v1.0.0View source

Reads the full state of a name across ENSv1 and ENSv2: where it lives, who owns it, its resolver, expiry and whether it can be registered or renewed.

When to use

Use when a UI needs to know about a name: owner, expiry, grace period, availability, or which protocol to send writes to.

Details

  • kind tells where the name lives (v1-unwrapped, v1-wrapped, v2-native, v2-migrated, v2-reserved, available); protocol is v1 or v2.
  • Times come from the block the read runs at, not the local clock.
  • inheritedResolver is the resolver serving a name that has none of its own: a parent's wildcard or off-chain resolver, or the ENSv1 resolver behind the ENSv1 bridge.
  • Costs two batched RPC calls, whatever the name kind. A name without a resolver of its own that a parent's resolver serves costs one more (two behind the ENSv1 bridge).

Gotchas

  • resolver is the resolver set on the name itself. A name served only by a parent's wildcard or off-chain resolver (such as jesse.base.eth) has resolver: null and is in no registry, so it is available although it resolves: check inheritedResolver.

Signature

function get(client: Like, options: get.Options): Promise<get.ReturnType>

Call it as ens.name.get(options) on a client, or Actions.name.get(client, options).

name.get.request(options) builds a deferred read for Actions.batch. See Look up many at once.

In React, use useName.

Parameters

OptionTypeDefaultDescription
name (required)stringENS name to read. Normalized automatically.

Also takes the read options.

Returns

Resolves to NameState. The name's full state.

FieldTypeDescription
namestringThe normalized name.
kindNameKind
protocol"v1" | "v2"Protocol that controls the name.
statusNameStatus
ownerAddress | nullWho ultimately controls the name: the ENSv2 token holder; on ENSv1 the NameWrapper token holder, the .eth registrant, or otherwise the registry owner.
managerAddress | nullENSv1 registry owner of an unwrapped name (the ENS app's "manager").
registrantAddress | nullENSv1 .eth registrar token holder of an unwrapped second-level name.
registryAddress | nullRegistry that holds the name: ENSv1 ENSRegistry, or the ENSv2 parent registry.
subregistryAddress | nullENSv2 registry for the name's children.
resolverAddress | nullResolver set on the name itself (not inherited from a parent).
inheritedResolverAddress | nullFor a name without a resolver of its own, the resolver that serves it from an ancestor: a parent's ENSIP-10 wildcard or off-chain resolver, or, for an ENSv1 name ENSv2 serves through the ENSv1 bridge, the ENSv1 resolver behind it. null when the name has its own resolver or nothing serves it. A name only an inherited resolver serves is in no registry, so it can be available and still resolve.
expirybigint | nullUnix seconds when the registration ends, grace period excluded. null when it never expires.
gracePeriodEndbigint | nullUnix seconds when the .eth grace period ends.
tokenIdbigint | nullToken ID: ENSv2 registry token (changes on some role updates), NameWrapper or .eth registrar token.
resourcebigint | nullENSv2 resource ID, stable across token changes.
ttlbigint | nullENSv1 registry TTL in seconds.
wrappedbooleanWhether the name is wrapped in the ENSv1 NameWrapper.
migratedbooleanWhether the name was migrated from ENSv1 to ENSv2.
reachablebooleanWhether ENSv2 resolution reaches the name. An ENSv1 name is reachable when the resolver ENSv2 resolution finds for it reads ENSv1: the ENSv1 bridge (a reservation, a migrated parent that kept it as resolver, an emancipated child of a locked parent) or a DNS TLD resolver. false when ENSv2 answers from elsewhere, e.g. a parent that migrated without the name or a .eth name without a reservation: its ENSv1 records no longer resolve, nor do its children's. Always true for ENSv2 names and on deployments without ENSv2.
availablebooleanWhether the name can be registered now.
renewablebooleanWhether the name can be renewed now (.eth second-level names when registered or in grace).

Errors

ErrorCodesWhen
InvalidInputErrorINVALID_NAMEthe name is invalid or the root.
NetworkErrorRPC_REQUEST_FAILED, RPC_TIMEOUT, RATE_LIMITEDthe RPC request fails.

It can also fail with the errors every read can (Errors.CommonError: ConfigError, ContractRevertError, InternalError, NetworkError).

See How errors work.

Examples

Showing a renewal banner
const state = await ens.name.get({ name: "alice.eth" })
if (state.status === "grace") showRenewBanner(state.gracePeriodEnd)

Example response

Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does.

await ens.name.get({ name: "nick.eth" })
{
  "name": "nick.eth",
  "kind": "v2-migrated",
  "protocol": "v2",
  "status": "registered",
  "owner": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
  "manager": null,
  "registrant": null,
  "registry": "0xf60aba43E1f7F3DAB1186Ff03B561401C9Df85E2",
  "subregistry": "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753",
  "resolver": "0xF4f1007EA430848F2fAd60e405A54Fc100fEc341",
  "expiry": "2051983306n",
  "gracePeriodEnd": "2054402506n",
  "tokenId": "42219085255511335250589442208301538195142221433306354426240614732610656010240n",
  "resource": "42219085255511335250589442208301538195142221433306354426240614732610656010240n",
  "ttl": null,
  "wrapped": false,
  "migrated": true,
  "available": false,
  "renewable": true,
  "reachable": true,
  "inheritedResolver": null
}

See also

Was this page helpful?