# name.transfer

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

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

Source: https://ensforge.com/docs/reference/sdk/name/transfer

<ApiMeta kind="Write" stability="stable" since="1.0.0" source="packages/sdk/src/actions/name/transfer/index.ts#L70" />

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

## When to use [#when-to-use]

Use to give a name away or move it between your own accounts. Use [`transferSync`](/docs/reference/sdk/name/transfer#wait-for-the-receipt-with-transfersync) to wait
for the receipt.

## Details [#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.

<Callout type="warn" title="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.
</Callout>

## Signature [#signature]

```ts
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`](/docs/reference/react/use-transfer-name).

## Parameters [#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](/docs/reference/sdk/client#write-options).

## Returns [#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 [#errors]

| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | invalid input. |
| [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED) | the name cannot be sent. |
| [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_UNREACHABLE`](/docs/reference/errors/NAME_UNREACHABLE) | ENSv2 resolution no longer reaches the name. |
| [`NameStateError`](/docs/reference/errors/name-state-error) | [`REGISTRY_NOT_EMANCIPATED`](/docs/reference/errors/REGISTRY_NOT_EMANCIPATED) | the name's registry is not emancipated and `unsafe` is not set. |
| [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`TRANSFER_DISALLOWED`](/docs/reference/errors/TRANSFER_DISALLOWED) | the account may not send it, or the recipient (an HCA) refuses it. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | `role: "registrant"` on names without a registrant. |
| [`UserRejectedError`](/docs/reference/errors/user-rejected-error) | [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED) | the user rejects the request. |
| [`WalletError`](/docs/reference/errors/wallet-error) | [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH), [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND) | the wallet is on another chain or has no account to sign with. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/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](/docs/sdk/errors-explained).

## Examples [#examples]

<Tabs groupId="api" items={["Client","Standalone","Effect"]} persist>
<Tab>
```ts title="Sending a name"
const { hash } = await ens.name.transfer({ name: "alice.eth", to: "0xB0b0000000000000000000000000000000000000" })
```
</Tab>

<Tab>
```ts title="Moving only the registrar token"
import { Actions } from "@ensforge/sdk"

await Actions.name.transfer(ens, { name: "alice.eth", to: bob, role: "registrant" })
```
</Tab>

<Tab>
```ts title="Sending in an Effect program"
import { Actions } from "@ensforge/sdk/effect"

const { hash } = yield* Actions.name.transfer(ens, { name: "alice.eth", to: bob })
```
</Tab>
</Tabs>

## Plan methods [#plan-methods]

Each method takes the same options as `name.transfer` and sends nothing. See [Preview before sending](/docs/sdk/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` [#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`](/docs/reference/sdk/client#sync-options).

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

<Tabs groupId="api" items={["Client","Standalone","Effect"]} persist>
<Tab>
```ts title="Sending and waiting"
const { receipt } = await ens.name.transferSync({ name: "alice.eth", to: bob })
```
</Tab>

<Tab>
```ts title="Waiting with a standalone call"
import { Actions } from "@ensforge/sdk"

await Actions.name.transferSync(ens, { name: "alice.eth", to: bob })
```
</Tab>

<Tab>
```ts title="Waiting in an Effect program"
import { Actions } from "@ensforge/sdk/effect"

yield* Actions.name.transferSync(ens, { name: "alice.eth", to: bob })
```
</Tab>
</Tabs>

## See also [#see-also]

- [`name.get`](/docs/reference/sdk/name/get) to read the current owner