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

name.transfer

Sends a name to another account and resolves once the transaction is submitted. Options, result, errors and examples for name.transfer.

Writestable
Since v1.0.0View source

Sends a name to another account and resolves once the transaction is submitted.

When to use

Use to give a name away or move it between your own accounts. Use transferSync to wait for the receipt.

Details

  • ENSv2 names move their registry token. With unsafe, the transfer also succeeds while other accounts still hold roles on the name.
  • Wrapped ENSv1 names move their NameWrapper token.
  • Unwrapped .eth names: role: "owner" (default) moves the registrar token and the registry ownership (manager); role: "registrant" moves only the registrar token.
  • Other unwrapped ENSv1 names change their registry owner.

Gotchas

  • Expired, reserved and unregistered names cannot be transferred.
  • ENSv2: roles on the name's PermissionedResolver stay with the sender, who can still edit its records (the plan carries a RECORD_CONTROL_RETAINED warning). records: "handover" grants them to the recipient and revokes the sender's in the same step; it is refused for the sender's shared "owned" resolver, whose roles cover other names.

Signature

function transfer(
  client: Like,
  options: transfer.Options & Write.Options,
): Promise<transfer.ReturnType>

Call it as ens.name.transfer(options) on a client, or Actions.name.transfer(client, options).

In React, use useTransferName.

Parameters

OptionTypeDefaultDescription
name (required)stringName to send. Normalized automatically.
to (required)stringRecipient address.
role"owner" | "registrant""owner"For unwrapped .eth names: owner moves the registrar token and the manager, registrant moves only the registrar token.
unsafebooleanfalseENSv2 only: transfer even while other accounts hold roles on the name.
records"keep" | "handover""keep"ENSv2: what happens to the sender's roles on the name's PermissionedResolver.

Also takes the write options.

Returns

Resolves to Write.Result. Submitted transaction hashes and the plan that produced them.

FieldTypeDescription
hashHexHash of the last transaction.
hashesreadonly Hex[]Every submitted transaction, in order.
idstringEIP-5792 bundle id when the calls were sent as one batch.
planPlanThe plan the write executed: its steps, in order, as they were submitted.

Errors

ErrorCodesWhen
InvalidInputErrorINVALID_NAME, INVALID_ADDRESSinvalid input.
NameStateErrorNAME_EXPIRED, NAME_RESERVED, NAME_NOT_REGISTEREDthe name cannot be sent.
NameStateErrorNAME_UNREACHABLEENSv2 resolution no longer reaches the name.
NameStateErrorREGISTRY_NOT_EMANCIPATEDthe name's registry is not emancipated and unsafe is not set.
UnauthorizedErrorNOT_OWNER, TRANSFER_DISALLOWEDthe account may not send it, or the recipient (an HCA) refuses it.
UnsupportedErrorUNSUPPORTED_PROTOCOLrole: "registrant" on names without a registrant.
UserRejectedErrorUSER_REJECTEDthe user rejects the request.
WalletErrorCHAIN_MISMATCH, ACCOUNT_NOT_FOUNDthe wallet is on another chain or has no account to sign with.
UnsupportedErrorWALLET_BATCH_UNSUPPORTEDwith mode: "batch" or a paymaster when the wallet cannot send calls as one batch.

It can also fail with the errors every write can (Errors.WriteError: the common errors plus InsufficientFundsError, TransactionError, UnsupportedError, UserRejectedError, WalletError).

See How errors work.

Examples

Sending a name
const { hash } = await ens.name.transfer({ name: "alice.eth", to: "0xB0b0000000000000000000000000000000000000" })

Plan methods

Each method takes the same options as name.transfer and sends nothing. See Preview before sending.

MethodDescription
name.transfer.prepare(options)Builds the plan without sending anything.
name.transfer.simulate(options)Simulates the plan with eth_call, reporting each step.
name.transfer.estimateGas(options)Estimates the gas and ETH the plan needs.

Wait for the receipt with transferSync

Sends a name to another account and resolves once the receipt is in.

Use when the next step depends on the new owner being on-chain.

name.transferSync takes the same options plus confirmations and timeout.

Resolves to Write.SyncResult. Receipts plus the submitted hashes and plan.

Sending and waiting
const { receipt } = await ens.name.transferSync({ name: "alice.eth", to: bob })

See also

Was this page helpful?