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

Fetch Owned Usernames

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

TypeScript
GraphQL
React

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.

Assign Owned Username

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

TypeScript
GraphQL
React

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 Usernameimport { assignUsernameToAccount } from "@lens-protocol/client/actions";
const result = await assignUsernameToAccount(sessionClient, {     username: {      localName: "wagmi"      // optional, defaults to lens/* namespace      // namespace: EvmAddress    }  })

Handle Result

TypeScript
GraphQL
React

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

Unassign Current Username

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

TypeScript
GraphQL
React

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

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

Handle Result

TypeScript
GraphQL
React

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.