Reserved Usernames

This guide explains how to reserve usernames in your custom Namespace.

Namespaces configured with the UsernameReservedNamespaceRule allow the Namespace owner or admins to reserve a specific set of usernames. This rule is applied by default to every new Namespace create through the Lens API.

List Reserved Usernames

TypeScript
GraphQL
React

Use the paginated fetchNamespaceReservedUsernames action to fetch a list of reserved usernames for a given namespace.

import { evmAddress } from "@lens-protocol/client";import { fetchNamespaceReservedUsernames } from "@lens-protocol/client/actions";
import { client } from "./client";
const result = await fetchNamespaceReservedUsernames(client, {  namespace: evmAddress("0x1234…"),});
if (result.isErr()) {  return console.error(result.error);}
// items: Array<{ ruleId: RuleId, namespace: EvmAddress, localName: string }>const { items, pageInfo } = result.value;

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

Update Reserved Usernames

To update the reserved usernames of a Namespace, you can either release or reserve usernames.

You MUST be authenticated as Builder and be either the owner or an admin of the Namespace you intend to configure reserved usernames for.

TypeScript
GraphQL

Use the updateReservedUsernames action to update the reserved usernames for a given namespace.

example.tsimport { evmAddress } from "@lens-protocol/client";import { updateReservedUsernames } from "@lens-protocol/client/action";
const result = await updateReservedUsernames(sessionClient, {  namespace: evmAddress("0x1234…"),  toRelease: ["alice", "bob"],  toReserve: ["charlie", "dave"],});

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

import { handleOperationWith } from "@lens-protocol/client/viem";
// …
const result = await updateReservedUsernames(sessionClient, {  namespace: evmAddress("0x1234…"),  toRelease: ["alice", "bob"],  toReserve: ["charlie", "dave"],}).andThen(handleOperationWith(walletClient));

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