Help & Support

Assigning Usernames

This guide explains how to assign and unassign a username to an Account on Lens.

Username usage is regulated by Username Rules set on the desired username namespace contract. More information on this will be provided in due course.

Assign a Username

1

Fetch Owned Usernames

An address can own multiple usernames, typically you might want to list all owned usernames before assigning a new one.

Use the paginated fetchUsernames action to fetch the list of owned usernames for a given address.

import { evmAddress } from "@lens-protocol/client";import { fetchUsernames } from "@lens-protocol/client/actions";
import { client } from "./client";
const result = await fetchUsernames(client, {  filter: { owned: evmAddress("0x1234...") },});
if (result.isErr()) {  return console.error(result.error);}
// items: Array<Username>const { items, pageInfo } = result.value;

See the Pagination guide for more information on how to handle paginated results.

2

Assign Owned Username

Once you know the available usernames, you can assign a new username to an Account.

You MUST be authenticated as Account Owner or Account Manager to make this request.

Use the assignUsernameToAccount action to assign one of the owned usernames (from the previous step) to the logged-in Account.

Assign Username
import { assignUsernameToAccount } from "@lens-protocol/client/actions";
const result = await assignUsernameToAccount(sessionClient, {     username: {      localName: "wagmi"      // optional, defaults to lens/* namespace      // namespace: EvmAddress    }  })

3

Handle Result

Finally, handle the result using the adapter for the library of your choice:

import { handleWith } from "@lens-protocol/client/viem";
// …
const result = await assignUsernameToAccount(sessionClient, {  username: {    localName: "wagmi",  },}).andThen(handleWith(walletClient));

See the Transaction Lifecycle guide for more information on how to determine the status of the transaction.

Unassign a Username

1

Unassign Current Username

You MUST be authenticated as Account Owner or Account Manager to make this request.

First, use the unassignUsernameFromAccount to unassign a username from the logged-in Account.

Create Username
import { unassignUsernameFromAccount } from "@lens-protocol/client/actions";
const result = await unassignUsernameFromAccount(sessionClient, {  // optional, defaults to lens/* namespace  // namespace: EvmAddress});

2

Handle Result

Finally, handle the result using the adapter for the library of your choice:

import { handleWith } from "@lens-protocol/client/viem";
// …
const result = await unassignUsernameFromAccount(sessionClient).andThen(  handleWith(walletClient),);

See the Transaction Lifecycle guide for more information on how to determine the status of the transaction.