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).

GraphQL
React
TypeScript

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

query {  username(    request: {      username: {        localName: "wagmi"
        # Optional. Defaults to lens/* namespace.        # namespace: EvmAddress      }
      # OR you can use this query also to fetch the username by ID      # id: ID    }  ) {    ...Username  }}

If available, the query returns null.

{  "data": {    "username": null  }}

Create the Username

Then, create the username.

GraphQL
React
TypeScript

Use the createUsername mutation to mint the desired username.

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

mutation {  createUsername(    request: {      username: {        localName: "wagmi"
        # optional, defaults to lens/* namespace        # namespace: EvmAddress      }    }  ) {    ... on CreateUsernameResponse {      hash    }
    ... on SponsoredTransactionRequest {      ...SponsoredTransactionRequest    }
    ... on SelfFundedTransactionRequest {      ...SelfFundedTransactionRequest    }
    ... on TransactionWillFail {      reason    }  }}

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

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