Create an Account

This guide will help you create your first Lens account.


To create an Account, you need to:

  1. Authenticate as an Onboarding User.

  2. Create an Account Metadata object.

  3. Upload the Account Metadata object onto a public URI.

  4. Deploy the Lens Account smart contract.

  5. Switch to Account Owner authentication role.

1

Log In as Onboarding User

First, authenticate as an Onboarding User.

The process is explained in detail in the Authentication guide, so we will keep it brief here.

Generate an authentication challenge:

mutation {  challenge(    request: {      app: "<app-address>"      account: "<wallet-address>"      signedBy: "<wallet-address>"    }  ) {    id    text  }}

Sign it and acquire the authentication tokens:

mutation {  authenticate(request: { id: "<challenge.id>", signature: "<signature>" }) {    ... on AuthenticationTokens {      accessToken      refreshToken      idToken    }
    ... on WrongSignerError {      reason    }
    ... on ExpiredChallengeError {      reason    }
    ... on ForbiddenError {      reason    }  }}

2

Create Account Metadata

Then, construct a new Account Metadata object with the necessary details.

Use the @lens-protocol/metadata package to construct a valid AccountMetadata object:

Example
import { MetadataAttributeType, account } from "@lens-protocol/metadata";
const metadata = account({  name: "Jane Doe",  bio: "I am a photographer based in New York City.",  picture: "ipfs://bafybeigdyrzt5sfp7udm7hu76u…",  coverPicture: "ipfs://bafybeihqj6arccj5xiky5jf…",  attributes: [    {      key: "twitter",      type: MetadataAttributeType.STRING,      value: "https://twitter.com/janedoexyz",    },    {      key: "dob",      type: MetadataAttributeType.DATE,      value: "1990-01-01T00:00:00Z",    },    {      key: "enabled",      type: MetadataAttributeType.BOOLEAN,      value: "true",    },    {      key: "height",      type: MetadataAttributeType.NUMBER,      value: "1.65",    },    {      key: "settings",      type: MetadataAttributeType.JSON,      value: '{"theme": "dark"}',    },  ],});

See the Lens Metadata Standards guide for more information on creating and hosting Metadata objects.

3

Upload Account Metadata

Then, upload the Account Metadata object to a public URI.

import { account } from "@lens-protocol/metadata";import { uploadJson } from "./my-upload-lib";
const metadata = account({  name: "Jane Doe",});
const metadataURI = await uploadJson(metadata); // e.g., lens://4f91ca…

4

Deploy Account Contract

Then, you can use the createAccountWithUsername mutation to deploy Lens Account smart contract and contextually mint a username for it.

Remember you MUST be authenticated as Onboarding User to make this request.

mutation {  createAccountWithUsername(    request: {      username: {        localName: "jane" # lens/jane in this example
        # Optional. Defaults to lens/* namespace.        # namespace: EvmAddress      }      metadataUri: "lens://4f91ca…"      accountManager: ["0x5071DeEcD24EBFA6161107e9a875855bF79f7b21"]    }  ) {    ... on CreateAccountResponse {      hash    }
    ... on SponsoredTransactionRequest {      ...SponsoredTransactionRequest    }
    ... on SelfFundedTransactionRequest {      ...SelfFundedTransactionRequest    }
    ... on InvalidUsername {      reason    }
    ... on TransactionWillFail {      reason    }  }}

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

In this example, we will assume the previous step returned a CreateAccountResponse object so we will poll the transactionStatus query until it returns a FinishedTransactionStatus result.

Query
query {  transactionStatus(    request: { txHash: "0x5e9d8f8a4b8e4b8e4b8e4b8e4b8e4b8e4b8e4b" }  ) {    ... on NotIndexedYetStatus {      reason      txHasMined    }
    ... on PendingTransactionStatus {      blockTimestamp    }
    ... on FinishedTransactionStatus {      blockTimestamp    }
    ... on FailedTransactionStatus {      reason      blockTimestamp    }  }}

5

Switch to Account Owner

Finally, switch to the Account Owner authentication role.

Do so by using the account query to retrieve the newly created Account's address:

query {  account(request: { txHash: "0x5e9d8f8a4b8e4b8e4b8e4b8e4b8e4b8e4b8e4b" }) {    address    username    metadata {      name      picture    }  }}

Finally, use the switchAccount mutation to switch to the Account Owner role:

mutation {  switchAccount(request: { account: "0x1234…" }) {    ... on AuthenticationTokens {      accessToken      refreshToken      idToken    }
    ... on ForbiddenError {      reason    }  }}

That's it—you are now authenticated with the newly created Account.