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 text records

Read text records such as a URL, a description or a social handle from a name, one key at a time or many keys in one call.

By the end of this guide you can read one text record (a key and a string value that a name's owner stores, such as url or com.twitter), or load several at once.

Prerequisites

Read one record

record.getText reads a single text record. Pass the name and the record's key.

Example (Reading a Profile URL)

get-text.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 url = await ens.record.getText({ name: "nick.eth", key: "url" });

The result is a string, or null when the record is not set. ensforge normalises the name and finds its resolver, so wildcard names and off-chain names work too. Calls made in the same tick are batched into one multicall where possible. See record.getText and How a lookup works.

Read several records in one call

record.get reads any mix of records in one request. List the keys in texts, and the result has exactly the fields you asked for.

Example (Loading a Profile)

get-profile.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 profile = await ens.record.get({
  name: "nick.eth",
  texts: ["avatar", "url", "com.twitter"],
  addresses: ["eth", "btc"],
});

profile.texts.url;
profile.addresses.btc;
profile.resolver;
  • texts lists text keys. Each key becomes a field of profile.texts, typed string | null.
  • addresses lists coins by symbol or coin type. Each becomes a field of profile.addresses.
  • resolver is the address of the resolver that answered, or null when the name has none.
  • A field you did not ask for does not exist on the result: profile.texts.url is there only because "url" was requested.

record.get is one Universal Resolver call whatever you select. It can also read the content hash (contentHash: true), the public key, the name record and more. See record.get, Get a name's address and Get a website.

Options

record.getText takes:

OptionTypeDefaultDescription
namestringrequiredThe name to read. Normalised for you.
keystringrequiredThe text record key, such as url, avatar or com.twitter.

record.get takes name and any of these selections:

OptionTypeDefaultDescription
textsreadonly string[]noneText record keys to read.
addressesreadonly (string | bigint)[]noneCoins to read, by symbol or coin type.
contentHashtruenoneRead the content hash.
abitrue or { contentTypes: bigint }noneRead the ABI record.
pubkeytruenoneRead the public key.
nameRecordtruenoneRead the name record.
interfacesreadonly Hex[]noneERC-165 interface IDs to look up implementers for.
datareadonly string[]noneData record keys.

Both actions also take 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.

Troubleshooting

A record is null

The record is not set, the name has no resolver, or its resolver does not store text records. With strict: true, getText fails with RECORD_NOT_FOUND, RESOLVER_NOT_FOUND or RESOLVER_PROFILE_UNSUPPORTED, so you can tell which. record.get with strict: true fails with RESOLVER_NOT_FOUND when the name has no resolver. Without strict, it returns resolver: null and every record null.

INVALID_NAME

The name cannot be normalised. INVALID_NAME is thrown before any request is sent.

GATEWAY_REQUEST_FAILED

The name's resolver sends the lookup to an off-chain gateway, and the gateway failed. See Look up off-chain names and GATEWAY_REQUEST_FAILED.

Was this page helpful?