# Set a primary name

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

Choose the name wallets and apps show for an address, on Ethereum, on every EVM chain or on an L2, including with a signed claim.

Source: https://ensforge.com/docs/sdk/set-a-primary-name

You will set the **primary name** of an address: the name wallets and apps show instead of `0x…`. It is stored as a **reverse record**, and readers check that the name resolves back to the address (ENSIP-19).

## Prerequisites [#prerequisites]

- A wallet client for the address you are naming. See [Create a client](/docs/sdk/create-a-client).
- A [name](/docs/reference/glossary#name) that resolves to that address. ensforge checks this before sending and fails with `PRIMARY_NAME_MISMATCH` otherwise. See [Set records](/docs/sdk/set-records).

## 1. Set the primary name on Ethereum [#1-set-the-primary-name-on-ethereum]

[`primaryName.set`](/docs/reference/sdk/primary-name/set) sets the name for the signer. `primaryName.setSync` also waits for the receipt.

**Example** (Setting Your Primary Name)

```ts title="set-primary-name.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.primaryName.setSync({ name: "ensforge-docs-demo.eth" });
```

Pass `name: null` to clear it. Names with encoded [labels](/docs/reference/glossary#label) (`[af2c…]`) are rejected, because readers show only [normalised](/docs/reference/glossary#normalisation) names.

| Option    | Type                                | Default    | Description                                                             |
| --------- | ----------------------------------- | ---------- | ----------------------------------------------------------------------- |
| `name`    | `string \| null`                    | required   | The primary name, or `null` to clear it.                                |
| `address` | `string`                            | the signer | The address to name. See [Name another address](#name-another-address). |
| `coin`    | `"eth" \| "default" \| { chainId }` | `"eth"`    | Where to set it. See below.                                             |
| `verify`  | `boolean`                           | `true`     | Check that `name` resolves to the address before sending.               |

## 2. Choose where it applies [#2-choose-where-it-applies]

`coin` picks the chain of the primary name.

| `coin`              | Stored in                      | Applies to                                 |
| ------------------- | ------------------------------ | ------------------------------------------ |
| `"eth"` (default)   | `addr.reverse`                 | Ethereum.                                  |
| `"default"`         | `default.reverse`              | Every EVM chain, as a fallback (ENSIP-19). |
| `{ chainId: 8453 }` | That chain's reverse registrar | That L2 only.                              |

A name in `addr.reverse` outranks `default.reverse` on Ethereum, so `"default"` also sets `addr.reverse` when it holds a different name. A default name whose only address record is an Ethereum address verifies on Ethereum alone. The plan carries a `DEFAULT_PRIMARY_NAME_ETHEREUM_ONLY` warning in that case.

## 3. Set a primary name on an L2 [#3-set-a-primary-name-on-an-l2]

An L2 primary name is a transaction on that L2, so the client needs clients for it in `chains`. The signer is the same account on every chain.

**Example** (Setting a Primary Name on Base Sepolia)

```ts title="set-primary-name-l2.ts"
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia, sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

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

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport }),
  walletClient: createWalletClient({ account, chain: sepolia, transport }),
  chains: {
    [baseSepolia.id]: {
      publicClient: createPublicClient({ chain: baseSepolia, transport: baseTransport }),
      walletClient: createWalletClient({ account, chain: baseSepolia, transport: baseTransport }),
    },
  },
}).extend(ensActions());

await ens.primaryName.setSync({
  name: "ensforge-docs-demo.eth",
  coin: { chainId: baseSepolia.id },
});
```

The plan is for the L2, and resumes there. Readers on Ethereum verify an L2 primary name against the L2's state as committed to Ethereum, so they see it only once that state is, which can take a while after the receipt.

Supported L2s are those with an L2 reverse registrar: OP Mainnet, Base, Arbitrum One, Linea and Scroll, and their Sepolia testnets. Other chains fail with [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT).

## 4. Set it on several L2s with one signature [#4-set-it-on-several-l2s-with-one-signature]

[`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) signs one EIP-191 message that covers several L2s, with no transaction. Anyone can then submit the claim on each chain with `primaryName.set`, so the account needs no gas or wallet connection on the L2s.

**Example** (Signing One Claim for Two Chains)

```ts title="sign-claim.ts"
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia, optimismSepolia, 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 }),
  chains: {
    [baseSepolia.id]: {
      publicClient: createPublicClient({ chain: baseSepolia, transport: http() }),
      walletClient: createWalletClient({ account, chain: baseSepolia, transport: http() }),
    },
    [optimismSepolia.id]: {
      publicClient: createPublicClient({ chain: optimismSepolia, transport: http() }),
      walletClient: createWalletClient({ account, chain: optimismSepolia, transport: http() }),
    },
  },
}).extend(ensActions());

const signed = await ens.primaryName.signClaim({
  name: "ensforge-docs-demo.eth",
  chainIds: [baseSepolia.id, optimismSepolia.id],
});

await ens.primaryName.set({ ...signed, coin: { chainId: baseSepolia.id } });
await ens.primaryName.set({ ...signed, coin: { chainId: optimismSepolia.id } });
```

- Every mainnet L2 shares one registrar, and testnets share another. One claim cannot mix mainnet chains and testnets, and it cannot include the ENS chain.
- The claim expires `expiresIn` seconds after signing, at most one hour (`3600n`, the default).
- Smart accounts sign as themselves (ERC-1271, or ERC-6492 before they are deployed). The account must exist, or be deployable, on each L2.

### Relay a claim from a server [#relay-a-claim-from-a-server]

The claim is plain JSON. The app signs and posts it. A server with a funded wallet on the L2 submits it.

**Example** (Relaying a Signed Claim)

```ts title="relay-claim.ts"
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia, sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const relayerAccount = privateKeyToAccount(process.env.RELAYER_PRIVATE_KEY as Hex);

const relayer = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
  chains: {
    [baseSepolia.id]: {
      publicClient: createPublicClient({ chain: baseSepolia, transport: http() }),
      walletClient: createWalletClient({
        account: relayerAccount,
        chain: baseSepolia,
        transport: http(),
      }),
    },
  },
}).extend(ensActions());

export async function relayClaim(body: string) {
  const { claim, signature } = JSON.parse(body);
  return relayer.primaryName.set({ claim, signature, coin: { chainId: baseSepolia.id } });
}
```

`relayer` is a client whose `chains` holds a funded wallet for that L2, and the relayer pays the gas. Validate the posted body before you submit it. The signature, not the sender, authorises the name.

## Name another address [#name-another-address]

`address` names another account. The signer must be the address's registry operator or, for a contract, its `Ownable` owner or its ContractNamer. Any other signer fails before sending with [`NOT_APPROVED`](/docs/reference/errors/NOT_APPROVED).

For `"eth"`, a ContractNamer goes through the ENSv2 adapter: it claims the contract's `addr.reverse` node, which makes the signer that node's owner, then sets the name. Those two dependent calls can only be simulated on an RPC that supports `eth_simulateV1`, or with `simulate: false`.

## Check the result [#check-the-result]

Read it back with [`primaryName.get`](/docs/reference/sdk/primary-name/get). See [Get the name for an address](/docs/sdk/get-a-primary-name).

## Troubleshooting [#troubleshooting]

### `PRIMARY_NAME_MISMATCH` [#primary_name_mismatch]

The name does not resolve to the address. Add an address record with `record.set`, then set the primary name. For an L2, the name needs an address for that chain's coin type or a default EVM address. See [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH).

### `CHAIN_NOT_CONFIGURED` [#chain_not_configured]

The L2 is not in the client's `chains`. Add it to `Ensforge.create`, or to the wagmi config with `fromWagmi`. See [`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED).

### `INVALID_COIN_TYPE` [#invalid_coin_type]

`coin` is not an EVM chain, or the claim does not cover the chain. For `signClaim`, `chainIds` is empty, includes the ENS chain, or mixes mainnet and testnets. See [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE).

### `SIGNATURE_INVALID` or `SIGNATURE_EXPIRED` [#signature_invalid-or-signature_expired]

The claim's signature does not match, or the claim has expired. Sign again, for the same name, chains and expiry. See [`SIGNATURE_INVALID`](/docs/reference/errors/SIGNATURE_INVALID) and [`SIGNATURE_EXPIRED`](/docs/reference/errors/SIGNATURE_EXPIRED).

### `INVALID_DURATION` [#invalid_duration]

`expiresIn` is not between 1 and 3600 seconds. See [`INVALID_DURATION`](/docs/reference/errors/INVALID_DURATION).

### `NOT_APPROVED` [#not_approved]

The signer may not name `address`. See [Name another address](#name-another-address) and [`NOT_APPROVED`](/docs/reference/errors/NOT_APPROVED).

<Callout type="info" title="Not supported yet">
Setting L2 primary names through an [HCA](/docs/reference/glossary#hca) (`via: hca()`) is not
supported, because the HCA lives on Ethereum. The contracts-v2 L2 registrar is not deployed.
</Callout>