Create Username

This guide explains how to create a new username.

Username issuance is regulated by Namespace Rules defined on the desired Namespace.

If you’re creating a username under the Global Lens Namespace (lens/*), the only restrictions are:

Allowed characters: a-z, 0-9, -, and _
Minimum length: 5 characters
Must start with a letter or a number

To create a new username, follow these steps.

You MUST be authenticated as the Account Owner or Account Manager of the Account that you intend to be the initial owner of the new username.

Verify Availability

First, verify if the desired username is available.

TypeScript
GraphQL
React

Use the canCreateUsername action as follows:

import { canCreateUsername } from "@lens-protocol/client/actions";
import { client } from "./client";
const result = await canCreateUsername(sessionClient, {  username: { localName: "wagmi" },});
if (result.isErr()) {  return console.error(result.error);}
result.value; // CanCreateUsernameResult

The CanCreateUsernameResult tells you if the logged-in Account satisfy the Namespace Rules for creating a username, and if the desired username is available.

Check CanCreateUsernameResultswitch (data.__typename) {  case "NamespaceOperationValidationPassed":    // Creating a username is allowed    break;
  case "NamespaceOperationValidationFailed":    // Creating a username is not allowed    console.log(data.reason);    break;
  case "NamespaceOperationValidationUnknown":    // Validation outcome is unknown    break;
  case "UsernameTaken":    // The desired username is not available    break;}

Where:

NamespaceOperationValidationPassed: The logged-in Account can create a username under the desired Namespace.
NamespaceOperationValidationFailed: Reposting 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.
UsernameTaken: The desired username is not available.

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

To learn more about how to use Namespace Rules, see the Namespace Rules guide.

Create the Username

Next, if available, create the username.

TypeScript
GraphQL
React

Use the createUsername action to mint the desired username.

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

Handle Result

TypeScript
GraphQL
React

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

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

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

That's it—you have successfully created a new username.