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

Create a client

Create an ensforge client from viem clients or a wagmi config, add the actions you need, and set options such as indexer and storage.

The client is the object you call ENS actions on. You create it once, at app start, from the viem clients your app already has, then add groups of actions to it with extend.

Create a client for reads

A viem public client is all a client needs to read. Its chain selects the ENS contracts: ensforge ships them for Ethereum mainnet and Sepolia.

Example (Creating a Client for Reads)

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

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http("https://your-rpc.example") }),
}).extend(ensActions());

const name = await ens.primaryName.get({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" });
  • Ensforge.create returns a client with no actions yet.
  • extend(ensActions()) returns a new client with every ENS action on it. The original client is left unchanged: clients are frozen.

A viem client on another chain fails with UNKNOWN_CHAIN unless you pass deployment. See Custom deployments.

Add a wallet for writes

Writes need a signer. Pass a viem wallet client as walletClient. Reads still go through the public client.

Example (Adding a Wallet Client)

ens.ts
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, custom, http, type EIP1193Provider } from "viem";
import { sepolia } from "viem/chains";

declare const provider: EIP1193Provider; // e.g. window.ethereum

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
  walletClient: createWalletClient({ chain: sepolia, transport: custom(provider) }),
}).extend(ensActions());
  • When the public client was created with an account, it is also used as the wallet, so walletClient can be left out.
  • walletClient can also be a function that returns the wallet, or undefined while none is connected. ensforge calls it on every write, so a wallet that connects later works.
  • Without a wallet, writes fail with WALLET_NOT_CONFIGURED. Reads keep working.

From a wagmi config

Apps on wagmi create the client with Ensforge.fromWagmi, from @ensforge/sdk/wagmi. Reads use wagmi's client for the ENS chain. Writes use whichever wallet is connected when they run.

Example (Creating a Client From wagmi)

ens.ts
import { ensActions } from "@ensforge/sdk";
import { Ensforge } from "@ensforge/sdk/wagmi";
import { wagmiConfig } from "./wagmi"; // your app's createConfig(...)

const ens = Ensforge.fromWagmi(wagmiConfig).extend(ensActions());
  • The ENS chain is mainnet when the wagmi config has it, otherwise the first configured chain ensforge has contracts for. Pass { chainId: 11155111 } to pick Sepolia.
  • A wallet connected to another chain is asked to switch first. Pass { switchChain: false } to turn that off.
  • Every other chain in the wagmi config is added to chains, so a primary name on an L2 uses wagmi's client and wallet there.
  • fromWagmi takes every option of Ensforge.create except the viem clients.

It works with wagmi 2 (2.14 or later) and wagmi 3. For React apps, see Use with wagmi.

Add actions with extend

extend adds a group of actions and returns a new client. Choose the groups by what your app does.

DecoratorFromAdds
ensActions()@ensforge/sdkEvery ENS action (ens.name, ens.record, ens.registration, …) and ens.batch. Not the indexer actions.
recordActions(), nameActions(), …@ensforge/sdkOne group each, for smaller bundles. There is one per group, plus batchActions().
indexerActions()@ensforge/sdk/indexer (also @ensforge/sdk)ens.indexer.*: lists, search and history. Needs an indexer.
hcaActions()@ensforge/hcaSmart-account actions (experimental). See HCA.

Example (Adding Indexer Actions)

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

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
  indexer: bigname(),
})
  .extend(ensActions())
  .extend(indexerActions());

const page = await ens.indexer.getNamesForAddress({
  address: "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
});

The indexer actions are a separate group because they need an indexer service. Calling them on a client without indexer fails with INDEXER_NOT_CONFIGURED. See Name lists and indexers.

Example (Only the Record Actions)

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

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
}).extend(recordActions());

const url = await ens.record.getText({ name: "nick.eth", key: "url" });

A client with only recordActions() has ens.record and nothing else, so the other groups stay out of your bundle. See Keep bundles small.

Options

Every option except publicClient is optional.

OptionTypeDefaultDescription
publicClientviem client(required)Client for reads. Its chain selects the ENS deployment.
walletClientviem wallet client, or a function returning onepublicClient when it has an accountClient for writes. A function is called on every write.
accountAccount | Addressthe wallet client's accountDefault signer for writes. A write's own account overrides it.
chainsRecord<chainId, { publicClient, walletClient? }>noneClients for other chains, for writes ENS makes there, such as a primary name on an L2. Without one, such writes fail with CHAIN_NOT_CONFIGURED.
deploymentDeployments.Profilethe built-in deployment for the chainENS contract addresses. Required for devnets, forks and other chains.
ccipRead{ gatewayUrls? } | falsethe Universal Resolver's own batch gatewayOff-chain lookups (CCIP-Read): the batch gateways the Universal Resolver sends them through. false turns them off.
batch{ multicall?: boolean | { batchSize?, wait? } }{ multicall: true }Groups reads made at the same time into multicall requests. wait is in milliseconds.
blockTagBlockTag"latest"Block that reads run at.
storagePlan.StoragePlan.memoryStorage()Where multi-step writes save their plan progress. Use Plan.localStorage() to survive a reload.
simulatebooleantrueSimulate writes before the wallet prompt.
indexerIndexernoneIndexer for indexer.* actions and for finding records and subnames during migration, from @ensforge/sdk/indexer.
gateways{ ipfs?, arweave?, swarm? }https://ipfs.io, https://arweave.net, https://api.gateway.ethswarm.orgHTTP gateways for avatars and website links. The public IPFS gateway is rate limited: set your own in production.

See Configure RPC and gateways.

Example (Adding an L2 for Primary Names)

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

declare const provider: EIP1193Provider;

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
  walletClient: createWalletClient({ chain: mainnet, transport: custom(provider) }),
  chains: {
    [base.id]: {
      publicClient: createPublicClient({ chain: base, transport: http() }),
      walletClient: createWalletClient({ chain: base, transport: custom(provider) }),
    },
  },
}).extend(ensActions());

await ens.primaryName.set({ name: "ensforge-docs-demo.eth", coin: { chainId: base.id } });

Each key of chains must match the chain of its clients. A mismatch fails at creation with CHAIN_NOT_CONFIGURED. See Set a primary name.

What the client holds

Besides its actions, every client has a few fields you can read.

FieldDescription
chain{ id, name } of the ENS chain.
accountThe default signer's address, or undefined without a wallet.
deploymentThe ENS contracts on this chain: addresses and what they support.
publicClientThe viem client used for reads.
configThe resolved options, with defaults filled in.
extendAdds a group of actions and returns a new client.

These names are reserved: an action group cannot use them.

Use a bare viem client

Every action also accepts a plain viem client in place of an ensforge client. ensforge creates a client for it with default options on first use, and reuses it for later calls.

Example (Calling an Action With a viem Client)

viem-client.ts
import { Actions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const publicClient = createPublicClient({ chain: mainnet, transport: http() });

const address = await Actions.record.getAddress(publicClient, { name: "nick.eth" });

Ensforge.from(client) does the same in your own helpers: it returns an ensforge client for either kind of client. See Ways to call actions.

Was this page helpful?