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

Transfer a name

Send a name to another account, or hand its manager role or its record control to someone else, and check the new owner afterwards.

You will send a name you own to another address. ensforge moves the right token for the name's kind, so one call works for ENSv2 names, unwrapped ENSv1 names and wrapped names.

Prerequisites

  • A wallet client for the account that owns the name. See Create a client.
  • A registered name. Expired, reserved and unregistered names cannot be transferred.

1. Send the name

name.transfer takes the name and the recipient. name.transferSync also waits for the receipt.

Example (Sending a Name)

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

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

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

const { hash } = await ens.name.transfer({
  name: "ensforge-docs-demo.eth",
  to: "0xB0b0000000000000000000000000000000000000",
});

What moves depends on where the name lives:

NameWhat transfer moves
On ENSv2The name's registry token.
Wrapped on ENSv1The NameWrapper token.
Unwrapped .eth name on ENSv1The registrar token and the registry ownership (the manager).
Other unwrapped ENSv1 nameThe registry owner.
OptionTypeDefaultDescription
namestringrequiredThe name to send. Normalised automatically.
tostringrequiredThe recipient address.
role"owner" | "registrant""owner"Unwrapped .eth names only. "registrant" moves only the registrar token.
unsafebooleanfalseENSv2 only. Send even while other accounts still hold roles on the name.
records"keep" | "handover""keep"ENSv2 only. What happens to the sender's roles on the name's resolver.

2. Decide who keeps control of the records

On ENSv2, a name's resolver has its own roles. By default they stay with the sender, who can still edit the records after the transfer. The plan carries a RECORD_CONTROL_RETAINED warning.

Pass records: "handover" to grant them to the recipient and revoke the sender's in the same step.

Example (Handing Over Record Control)

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

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

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

await ens.name.transferSync({
  name: "ensforge-docs-demo.eth",
  to: "0xB0b0000000000000000000000000000000000000",
  records: "handover",
});

"handover" is refused for the sender's shared "owned" resolver, because its roles cover other names too. See Resolvers and shared records.

Give only the registrar token (ENSv1)

An unwrapped .eth name on ENSv1 has two holders. The registrant holds the registrar token and owns the name. The manager is the registry owner and edits records and subnames. See Who can change a name.

  • role: "registrant" on name.transfer moves only the registrar token.
  • name.setManager lets another account edit records and subnames while you keep ownership.
  • name.reclaim resets the manager to the registrant (or to owner). Use it after receiving a registrar token, or to repair a lost manager.

setManager and reclaim fail with UNSUPPORTED_PROTOCOL for ENSv2 names and wrapped names, and reclaim also for names that are not .eth names. ENSv2 uses roles instead. See Roles and permissions.

Check the result

Read the name with name.get and compare owner with the recipient. See Get a name's owner, expiry and status.

Troubleshooting

NOT_OWNER

The signer does not own the name. Send from the owner's account. See NOT_OWNER.

TRANSFER_DISALLOWED

The owner lacks the role to transfer, other accounts hold roles on an ENSv2 name, or the recipient (an HCA) refuses it. Revoke the other roles, or pass unsafe: true. See TRANSFER_DISALLOWED.

NAME_EXPIRED, NAME_RESERVED or NAME_NOT_REGISTERED

Only registered names can be sent. See NAME_EXPIRED, NAME_RESERVED and NAME_NOT_REGISTERED.

UNSUPPORTED_PROTOCOL

You passed role: "registrant" for a name that has no registrant. See UNSUPPORTED_PROTOCOL.

INVALID_ADDRESS

to is not an address. See INVALID_ADDRESS.

Was this page helpful?