Help & Support

Assigning Usernames

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

Assign a Username

To assign a Username to the logged-in Account, follow these steps.

You MUST be authenticated as Account Owner or Account Manager of the Account you want to assign a Username to.

1

Fetch Owned Usernames

First, list all usernames owned by the logged-in Account.

Use the paginated fetchUsernames action to fetch the list of usernames owned by the logged-in Account address.

Get Owned Usernames
import { evmAddress } from "@lens-protocol/client";import { fetchUsernames } from "@lens-protocol/client/actions";
import { client } from "./client";
const result = await fetchUsernames(sessionClient, {  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

Check Rules

Next, inspect the username.operations.canAssign field of the desired Username to determine whether the logged-in Account is allowed to assign the given Username. Some username namespaces may have restrictions on who can assign a Username.

Check Rules
switch (username.operations.canAssign.__typename) {  case "NamespaceOperationValidationPassed":    // Assignment is allowed    break;
  case "NamespaceOperationValidationFailed":    // Assignment is not allowed    console.log(username.operations.canAssign.reason);    break;
  case "NamespaceOperationValidationUnknown":    // Validation outcome is unknown    break;}

Where:

  • NamespaceOperationValidationPassed: The logged-in Account is allowed to assign the given Username.

  • NamespaceOperationValidationFailed: Assignment is not allowed. The reason field explains why, and unsatisfiedRules lists the unmet requirements.

  • NamespaceOperationValidationUnknown: The Namespace has one or more unknown rules requiring ad-hoc verification. The extraChecksRequired field provides the addresses and configurations of these rules.

Treat the NamespaceOperationValidationUnknown as failed unless you intend to support the specific rules. See Namespace Rules for more information.

3

Assign the Username

Next, if allowed, assign the desired Username to the Account.

Use the assignUsernameToAccount action to assign a Username.

import { assignUsernameToAccount } from "@lens-protocol/client/actions";
const result = await assignUsernameToAccount(sessionClient, {  username: {    localName: "wagmi",  },});

4

Handle Result

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

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

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

Unassign a Username

To unassign a Username from the logged-in Account, follow these steps.

You MUST be authenticated as Account Owner or Account Manager of the Account that owns the Username you want to unassign.

1

Check Rules

First, inspect the username.operations.canUnassign field of the desired Username to determine whether the logged-in Account is allowed to unassign the given Username. Some username namespaces may have restrictions on who can unassign a Username.

Check Rules
switch (username.operations.canUnassign.__typename) {  case "NamespaceOperationValidationPassed":    // Unassignment is allowed    break;
  case "NamespaceOperationValidationFailed":    // Unassignment is not allowed    console.log(username.operations.canUnassign.reason);    break;
  case "NamespaceOperationValidationUnknown":    // Validation outcome is unknown    break;}

Where:

  • NamespaceOperationValidationPassed: The logged-in Account is allowed to unassign the given Username.

  • NamespaceOperationValidationFailed: Unassignment is not allowed. The reason field explains why, and unsatisfiedRules lists the unmet requirements.

  • NamespaceOperationValidationUnknown: The Namespace has one or more unknown rules requiring ad-hoc verification. The extraChecksRequired field provides the addresses and configurations of these rules.

Treat the NamespaceOperationValidationUnknown as failed unless you intend to support the specific rules. See Namespace Rules for more information.

2

Unassign Current Username

Next, if allowed, unassign the Username.

Use the unassignUsernameFromAccount to unassign a Username.

import { unassignUsernameFromAccount } from "@lens-protocol/client/actions";
const result = await unassignUsernameFromAccount(sessionClient);

3

Handle Result

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

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

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

Previous
Fetch Usernames
Next
Custom Namespaces