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.

Fetch Owned Usernames

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

GraphQL
React
TypeScript

Use the paginated usernames query to fetch the list of owned usernames for a given address.

query {  usernames(request: { owner: "0x5E647e6197fa5C6aA814E11C3504BE232a3D671a" }) {    items {      id      value      namespace {        address        namespace        metadata {          description        }      }      localName      linkedTo      ownedBy    }    pageInfo {      prev      next    }  }}

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

Assign a Username

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

GraphQL
React
TypeScript

Use the assignUsernameToAccount mutation to assign a username to the logged-in Account.

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

mutation {  assignUsernameToAccount(    request: {      localName: "bob"      # optional, defaults to lens/* namespace      namespaceAddress: EvmAddress    }  ) {    ... on AssignUsernameResponse {      hash    }
    ... on SponsoredTransactionRequest {      ...SponsoredTransactionRequest    }
    ... on SelfFundedTransactionRequest {      ...SelfFundedTransactionRequest    }
    ... on TransactionWillFail {      reason    }  }}

Finally, handle the result as explained in the Transaction Lifecycle guide.

Unassign a Username

GraphQL
React
TypeScript

Use the unassignUsernameFromAccount mutation to unassign a username from the logged-in Account.

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

mutation {  unassignUsernameFromAccount(    request: {      # the username contract for which the username is to be unassigned      namespaceAddress: "0xF0F931CA31cb3abC452cC8007ebD555ca3Cd81b6"    }  ) {    ... on UnassignUsernameResponse {      hash    }
    ... on SponsoredTransactionRequest {      ...SponsoredTransactionRequest    }
    ... on SelfFundedTransactionRequest {      ...SelfFundedTransactionRequest    }
    ... on TransactionWillFail {      reason    }  }}

Finally, handle the result as explained in the Transaction Lifecycle guide.