# registration.register

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

Registers one or more .eth names: approve, commit, wait, register, then records and primary name. Options, errors and examples for registration.register.

Source: https://ensforge.com/docs/reference/sdk/registration/register

<ApiMeta kind="Write" stability="stable" since="1.0.0" source="packages/sdk/src/actions/registration/register/index.ts#L73" />

Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the transaction is submitted.

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

Use to buy names in one flow; the plan runs every transaction in order. Use [`registerSync`](/docs/reference/sdk/registration/register#wait-for-the-receipt-with-registersync) to wait for the receipt.

## Details [#details]

- The plan: approve the token (if the allowance is short) with the commit → wait the registrar's
  minimum commitment age on chain time → register (deploying each name's resolver) → records →
  primary name.
- The approval covers the quote plus 2%, since the price is charged at `register` and can drift
  (e.g. a decaying premium); only the actual price is paid.
- Paid in ERC-20 (USDC by default); the registrar does not accept ETH.
- By default each name gets its own PermissionedResolver with `records` written at creation; its
  ETH address defaults to the owner (`addresses: { eth: null }` leaves it unset).
- The result's `secret` resumes an interrupted registration: call again with the same options and `secret`.

<Callout type="warn" title="Gotchas">
- Resolves after the last transaction is submitted, at least a minute after the commit.
- Resuming needs exactly the same options: they are part of the commitment.
</Callout>

## Signature [#signature]

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

Call it as `ens.registration.register(options)` on a client, or `Actions.registration.register(client, options)`.

In React, use [`useRegister`](/docs/reference/react/use-register).

## Parameters [#parameters]

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `names` (required) | `string \| readonly string[]` |  | One or more `.eth` second-level names; several share one plan. Normalized automatically. |
| `duration` (required) | `bigint` |  | Registration length in seconds, e.g. `Duration.years(1)`. |
| `owner` | `string` | the signing account | Owner of the names. |
| `resolver` | `string \| null` |  | Resolver for the names. By default each name gets its own PermissionedResolver, deployed in the same plan with `records` written at creation. `"owned"` uses the signer's shared PermissionedResolver (the ENS app's address), deployed once and reused; its roles cover every name on it. `null` registers without a resolver. |
| `records` | `Omit<recordSet.Options, "name" \| "resolver" \| "clear" \| "pubkey">` |  | Records for every name, written when its resolver is created (or right after registering). |
| `primaryName` | `boolean` |  | Set the (single) name as the signer's primary name; adds its `eth` address record. |
| `paymentToken` | `PaymentToken` | `"usdc"` | Token to pay with. |
| `subregistry` | `string` |  | ENSv2 registry for the names' subnames. |
| `referrer` | `Hex` |  | Referrer recorded by the registrar: 32 bytes, or an address (left-padded). |
| `secret` | `Hex` |  | Secret from an earlier `commit` or `register`, to finish that registration. |

Also takes the [write options](/docs/reference/sdk/client#write-options).

## Returns [#returns]

Resolves to `Write.Result & { readonly secret: Hex }`. Submitted hashes, the plan and the commitment secret.

## 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), [`DURATION_TOO_SHORT`](/docs/reference/errors/DURATION_TOO_SHORT), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. |
| [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_NOT_AVAILABLE`](/docs/reference/errors/NAME_NOT_AVAILABLE) | a name is taken or in its grace period. |
| [`CommitmentError`](/docs/reference/errors/commitment-error) | [`COMMITMENT_TOO_NEW`](/docs/reference/errors/COMMITMENT_TOO_NEW), [`COMMITMENT_TOO_OLD`](/docs/reference/errors/COMMITMENT_TOO_OLD), [`COMMITMENT_EXISTS`](/docs/reference/errors/COMMITMENT_EXISTS) | a resumed commitment outside its window. |
| [`InsufficientFundsError`](/docs/reference/errors/insufficient-funds-error) | [`INSUFFICIENT_TOKEN_BALANCE`](/docs/reference/errors/INSUFFICIENT_TOKEN_BALANCE) | the signer cannot pay in the payment token. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`PAYMENT_TOKEN_UNSUPPORTED`](/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED), [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | an unaccepted token or without ENSv2. |
| [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. |
| [`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="Registering a name"
const { secret } = await ens.registration.register({ names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } })
```
</Tab>

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

await Actions.registration.register(ens, { names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } })
```
</Tab>

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

yield* Actions.registration.register(ens, { names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } })
```
</Tab>
</Tabs>

## Plan methods [#plan-methods]

Each method takes the same options as `registration.register` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).

| Method | Description |
| --- | --- |
| `registration.register.prepare(options)` | Builds the plan without sending anything. |
| `registration.register.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `registration.register.estimateGas(options)` | Estimates the gas and ETH the plan needs. |

## Wait for the receipt with `registerSync` [#wait-for-the-receipt-with-registersync]

Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the receipt is in.

Use when the next step depends on the change being on-chain.

`registration.registerSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).

Resolves to `registerSync.ReturnType`. Receipts, the registered names with token IDs and expiries, and the amount paid.

<Tabs groupId="api" items={["Client","Standalone","Effect"]} persist>
<Tab>
```ts title="Registering a name and waiting"
const { receipt } = await ens.registration.registerSync({ names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } })
```
</Tab>

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

await Actions.registration.registerSync(ens, { names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } })
```
</Tab>

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

yield* Actions.registration.registerSync(ens, { names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } })
```
</Tab>
</Tabs>

## See also [#see-also]

- [`registration.getPrice`](/docs/reference/sdk/registration/get-price) to quote it first