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 tsxtsx 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)
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.createtakes the viem client. No wallet is needed to read..extend(ensActions())adds every ENS action to the client:ens.record,ens.name,ens.primaryNameand 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)
import { ens } from "./ens";
const address = await ens.record.getAddress({ name: "nick.eth" });
console.log(address);Run it:
npx tsx address.ts0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5The 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)
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{
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, sobatchcan run them together. record.getAvatarreturns a URL a browser can load, not the raw record.primaryName.getgoes 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
.ethname 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)
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));[ 'Set records' ]- The wallet client signs. The public client still does every read.
record.set.preparereturns 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)
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" }));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_OWNERand sends nothing. record.set(withoutSync) 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?