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

Quick start

Install ensforge, read your first ENS name in under five minutes, then preview and send your first write on the Sepolia test network.

By the end of this page you will have read an address, an avatar, a text record and a primary name from ENS in one batch. The second part sends your first write, on the Sepolia test network.

You need Node.js 20.19 or later. Nothing else: the first part reads from Ethereum mainnet and needs no wallet.

1. Create a project

Create an empty folder, make it an ES module project, and install the SDK with viem and Effect.

mkdir ens-quickstart && cd ens-quickstart
npm init -y && npm pkg set type=module
npm install @ensforge/sdk viem effect@^4 tsx

tsx runs the TypeScript files on this page directly. Any other way of running TypeScript works too.

2. Create a client

The client is the object you call ENS actions on. Create it once from a viem public client; the chain of that client tells ensforge which ENS contracts to use.

Example (Creating a Mainnet Client)

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

export const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
}).extend(ensActions());
  • Ensforge.create takes the viem client. No wallet is needed to read.
  • .extend(ensActions()) adds every ENS action to the client: ens.record, ens.name, ens.primaryName and the rest.

See Create a client for every option.

3. Get an address

Ask for the Ethereum address of nick.eth. This is the most common ENS lookup: turning a name into the address it points to.

Example (Getting an Address)

address.ts
import { ens } from "./ens";

const address = await ens.record.getAddress({ name: "nick.eth" });
console.log(address);

Run it:

npx tsx address.ts
Output
0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5

The result is null when the name has no address, so your code handles a missing record without a try. ensforge also checks and normalises the name for you: Nick.ETH reads the same record. See Get a name's address for other chains and coins.

4. Look up several things at once

A profile page needs more than an address. ens.batch runs several lookups together, in as few requests to the chain as possible.

Example (Loading a Profile in One Batch)

profile.ts
import { Actions } from "@ensforge/sdk";
import { ens } from "./ens";

const { results } = await ens.batch({
  requests: {
    address: Actions.record.getAddress.request({ name: "nick.eth" }),
    avatar: Actions.record.getAvatar.request({ name: "nick.eth" }),
    github: Actions.record.getText.request({ name: "nick.eth", key: "com.github" }),
    primaryName: Actions.primaryName.get.request({
      address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    }),
  },
});

console.log(results);
npx tsx profile.ts
Output
{
  address: {
    status: 'success',
    result: '0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5'
  },
  avatar: { status: 'success', result: 'https://euc.li/nick.eth' },
  github: { status: 'success', result: 'arachnid' },
  primaryName: { status: 'success', result: 'vitalik.eth' }
}
  • Every read action has a .request(...) form. It describes the lookup without running it, so batch can run them together.
  • record.getAvatar returns a URL a browser can load, not the raw record.
  • primaryName.get goes the other way: from an address to its name. ensforge only returns the name when it points back to the same address.
  • One failed lookup does not fail the others: each result has its own status.

You have read ENS. The next part writes to it.

See Look up many at once and How a lookup works.

5. Get a test name and test ETH

Writes change data on a chain, so they need a wallet that pays for gas and controls the name. Use the Sepolia test network, where both are free.

  • A private key for a test account. Never use a key that holds real funds.
  • Some Sepolia ETH in that account, from any Sepolia faucet.
  • A .eth name on Sepolia owned by that account. Register one in the ENS app on Sepolia.

Put the key in an environment variable so it stays out of your code:

export PRIVATE_KEY=0x...

6. Preview the write

Add a wallet client to a Sepolia client, then ask ensforge to plan a text record change without sending it. Replace ensforge-docs-demo.eth with your Sepolia name.

Example (Planning a Write on Sepolia)

write.ts
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);

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

const records = { name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" } };

const plan = await ens.record.set.prepare(records);
console.log(plan.steps.map((step) => step.description));
Output
[ 'Set records' ]
  • The wallet client signs. The public client still does every read.
  • record.set.prepare returns a plan: the transactions the write needs, in order. Nothing is sent and the wallet is not asked to sign.
  • Every write has .prepare, so a UI can show what will happen before the user confirms.

See How writes work.

7. Send it and wait

Send the same write with record.setSync. The Sync form waits until the transaction is mined, then you read the record back to see the change.

Example (Setting a Text Record and Reading It Back)

write.ts
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);

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

const records = { name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" } };
const { hash } = await ens.record.setSync(records);
console.log("Mined:", hash);

console.log(await ens.record.getText({ name: "ensforge-docs-demo.eth", key: "url" }));
Output
Mined: 0x...
https://example.com
  • ensforge simulates the transaction before the wallet prompt. A write that would fail, for example because the account does not own the name, throws a typed error such as NOT_OWNER and sends nothing.
  • record.set (without Sync) returns as soon as the transaction is submitted. Use it when your UI tracks confirmation itself.

Choose where to go next

You have read ENS records, batched lookups, and planned and sent a write. From here:

Was this page helpful?