Create Username

This guide explains to create a new username.

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

Verify Availability

First, check if the username is available in the target namespace (lens/ by default).

TypeScript
GraphQL
React

Use the fetchUsername action to fetch a username by local name and namespace (if different from lens/*) or id.

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

If available, the action returns null.

Create the Username

Then, create the username.

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

TypeScript
GraphQL
React

Use the createUsername action to mint the desired username.

Create Usernameimport { createUsername } from "@lens-protocol/client/actions";
const result = await createUsername(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 createUsername(sessionClient, {  username: {    localName: "wagmi",  },}).andThen(handleWith(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.