name.transfer
Sends a name to another account and resolves once the transaction is submitted. Options, result, errors and examples for name.transfer.
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
.ethnames: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_RETAINEDwarning).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
| Option | Type | Default | Description |
|---|---|---|---|
name (required) | string | Name to send. Normalized automatically. | |
to (required) | string | Recipient address. | |
role | "owner" | "registrant" | "owner" | For unwrapped .eth names: owner moves the registrar token and the manager, registrant moves only the registrar token. |
unsafe | boolean | false | ENSv2 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.
| Field | Type | Description |
|---|---|---|
hash | Hex | Hash of the last transaction. |
hashes | readonly Hex[] | Every submitted transaction, in order. |
id | string | EIP-5792 bundle id when the calls were sent as one batch. |
plan | Plan | The plan the write executed: its steps, in order, as they were submitted. |
Errors
| Error | Codes | When |
|---|---|---|
InvalidInputError | INVALID_NAME, INVALID_ADDRESS | invalid input. |
NameStateError | NAME_EXPIRED, NAME_RESERVED, NAME_NOT_REGISTERED | the name cannot be sent. |
NameStateError | NAME_UNREACHABLE | ENSv2 resolution no longer reaches the name. |
NameStateError | REGISTRY_NOT_EMANCIPATED | the name's registry is not emancipated and unsafe is not set. |
UnauthorizedError | NOT_OWNER, TRANSFER_DISALLOWED | the account may not send it, or the recipient (an HCA) refuses it. |
UnsupportedError | UNSUPPORTED_PROTOCOL | role: "registrant" on names without a registrant. |
UserRejectedError | USER_REJECTED | the user rejects the request. |
WalletError | CHAIN_MISMATCH, ACCOUNT_NOT_FOUND | the wallet is on another chain or has no account to sign with. |
UnsupportedError | WALLET_BATCH_UNSUPPORTED | with 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
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.
| Method | Description |
|---|---|
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.
const { receipt } = await ens.name.transferSync({ name: "alice.eth", to: bob })See also
name.getto read the current owner
Was this page helpful?