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 address

Read the address a name points to, for Ethereum or for any other coin or chain, using coin types from ENSIP-9 and ENSIP-11.

By the end of this guide you can turn a name such as nick.eth into the address it points to (forward resolution), on Ethereum or on any other chain.

Prerequisites

Get the Ethereum address

record.getAddress reads the address record of a name: the address its owner chose to receive funds at. Without a coin, it reads the Ethereum address.

Example (Reading an Ethereum Address)

get-address.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 address = await ens.record.getAddress({ name: "nick.eth" });
console.log(address);
Output
0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5

ensforge normalises the name before it reads, so Nick.ETH and nick.eth give the same answer. It finds the name's resolver, including parent, wildcard and off-chain resolvers, and returns a checksummed address. See How a lookup works and record.getAddress.

To read with a plain viem public client instead, call the action directly.

get-address.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 address = await ens.record.getAddress({ name: "ens.eth" });

The standalone form imports only the action you call, which keeps bundles small. See Ways to call actions.

Get an address on another chain

A name can hold one address per coin. Set coin to pick which one to read. It takes a symbol, an EVM chain or a numeric coin type.

Example (Reading Bitcoin, Base and a Raw Coin Type)

get-other-coins.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 btc = await ens.record.getAddress({ name: "nick.eth", coin: "btc" });
const base = await ens.record.getAddress({ name: "nick.eth", coin: { chainId: 8453 } });
const sameBtc = await ens.record.getAddress({ name: "nick.eth", coin: 0n });
  • A symbol such as "btc" or "eth" names the coin.
  • { chainId: 8453 } names an EVM chain (here Base). EVM chains get a checksummed Address; other coins return their native format as a string.
  • A bigint is the raw coin type (0n is Bitcoin).
  • An EVM chain with no address of its own falls back to the name's default EVM address (ENSIP-19).

Options

OptionTypeDefaultDescription
namestringrequiredThe name to read. Normalised for you.
coinsymbol, { chainId } or bigint"eth"Which coin's address to read.

The action also takes the options every read takes: signal to cancel, strict to throw instead of returning null, gatewayUrls for off-chain lookups, and blockNumber or blockTag to read at one block. See record.getAddress.

Result

The result is Address | null for Ethereum and EVM chains, and string | null for other coins. It is null when the name has no address for that coin. Pass strict: true to fail instead, as in Troubleshooting.

To read an address together with other records, use record.get. See Get text records.

Troubleshooting

The result is null

The name has no address record for that coin, no resolver, or a resolver that does not store addresses. Pass strict: true to find out which one: it fails with RECORD_NOT_FOUND, RESOLVER_NOT_FOUND or RESOLVER_PROFILE_UNSUPPORTED.

INVALID_NAME

The name cannot be normalised, for example because it contains a character ENS does not allow. INVALID_NAME is thrown before any request is sent.

INVALID_COIN_TYPE

The coin is an unknown symbol or a negative value. Some defunct coins, such as EOS (coin type 194), are no longer supported and fail with INVALID_COIN_TYPE or INVALID_ADDRESS.

GATEWAY_REQUEST_FAILED or OFFCHAIN_LOOKUP_INVALID

The name resolves off-chain and the gateway failed or answered wrongly. See Look up off-chain names and GATEWAY_REQUEST_FAILED.

DNSSEC_PROOF_FAILED

The name is a DNS name that resolves through a DNSSEC proof, such as ens.domains, and the proof does not verify. At the time of writing, no DNSSEC proof verifies on Ethereum mainnet or Sepolia, so these names fail this way until ENS updates its DNSSEC trust anchor. See DNSSEC_PROOF_FAILED.

Was this page helpful?