Onboarding

Learn how to onboard new users to Lens.

The process of onboarding a new user involves minting a new Profile NFT. This can be accomplished either by the user themselves in a self-funded manner, or by a third party on behalf of the user.

Typically, users will choose their Handle during the onboarding process. They can only choose the local-name portion of the Handle, such as wagmi in lens/wagmi. The namespace is currently fixed to lens.

Here are the rules to follow when choosing an Handle:

In self-funded onboarding, the user is guided through the process of creating a Lens Profile with their desired Handle for a fee of 8 MATIC. As this process uses the user's wallet to send the transaction, it cannot be sponsored and requires the user's signature.

import { useAccount, useConnect } from "wagmi";import { injected } from "wagmi/connectors";
import { CreateProfileForm } from "./CreateProfileForm";
export function OnboardingPage() {  const { address, isDisconnected, isConnecting } = useAccount();  const { connect } = useConnect();
  if (isDisconnected && !address) {    return (      <button        disabled={isConnecting}        onClick={() => connect({ connector: injected() })}      >        Connect Wallet      </button>    );  }
  return <CreateProfileForm address={address} />;}

import { useState } from "react";import { useValidateHandle } from "@lens-protocol/react-web";import { Address } from "viem";
type CreateProfileFormProps = {  address: Address;};
export function CreateProfileForm({ address }: CreateProfileFormProps) {  const [localName, setLocalName] = useState("");  const { execute: validateHandle, loading: verifying } = useValidateHandle();
  const submit = async () => {    const result = await validateHandle({ localName });
    if (result.isFailure()) {      console.error();      return;    }
    // TODO: mint profile  };
  return (    <form onSubmit={submit}>      <input        type="text"        disabled={verifying}        value={localName}        onChange={(e) => setLocalName(e.target.value)}      />
      <button type="submit" disabled={verifying}>        Create      </button>    </form>  );}

import { useState } from "react";import { useCreateProfile, useValidateHandle } from "@lens-protocol/react-web";import { Address } from "viem";
type CreateProfileFormProps = {  address: Address;};
export function CreateProfileForm({ address }: CreateProfileFormProps) {  const [localName, setLocalName] = useState("");  const { execute: validateHandle, loading: verifying } = useValidateHandle();  const { execute: createProfile, loading: creating } = useCreateProfile();
  const submit = async () => {    const validity = await validateHandle({ localName });
    if (validity.isFailure()) {      window.alert(validity.error.message);      return;    }
    const result = await createProfile({ localName, to: address });
    if (result.isFailure()) {      window.alert(result.error.message);      return;    }
    const profile = result.value;    window.alert(      `Congratulations! You now own: ${profile.handle?.fullHandle}!`    );  };
  return (    <form onSubmit={submit}>      <input        type="text"        disabled={verifying || creating}        value={localName}        onChange={(e) => setLocalName(e.target.value)}      />
      <button type="submit" disabled={verifying || creating}>        Create      </button>    </form>  );}

For applications with unique onboarding requirements, a credit system for onboarding is available to cater to these needs.

The Lens Protocol team may grant an initial number of credits to particular app builders. These credits can be used to mint new Profile in behalf of the app new users. Each credit used reduces the total number of credits available to the app.

If you're interested in obtaining credits for your app, please reach out to the Lens Developer Garden, in the #general channel.

Below are the PermissionlessCreator contract features that can be utilized to mint new Profiles using credits.

The createProfileWithHandleUsingCredits function, available on the PermissionlessCreator smart contract, allows the minting of a new Profile with Handle using credits. This function operates similarly to createProfileWithHandle, but it doesn't require the a fee. Instead, the app builder can utilize their credits to mint the new profile for the user.

function createProfileWithHandleUsingCredits(  Types.CreateProfileParams calldata createProfileParams,  string calldata handle,  address[] calldata delegatedExecutors) external returns (uint256 profileId, uint256 handleId);
struct CreateProfileParams {  address to;  address followModule;  bytes followModuleInitData;}

The app builder can use the delegatedExecutors parameter to set up Profile Manager addresses on the newly created Profile. If the Lens API relayer address is included in the delegatedExecutors array, this effectively enables the Signless Experience for the new Profile.

We've made it possible to mint Profile and Handle independently using credits. Consider minting a batch of Profiles without Handles in advance. These can be held in reserve and transferred to new users during their onboarding process. The Handle can then be minted lazily, according to the user's request.

This method provides a seamless experience, enabling users to authenticate and start using the app immediately. The Handle is minted in the background, and once it's successfully created, it can be transferred and linked to the user's Profile smoothly.

Use the createProfileUsingCredits function to mint a new Profile without a Handle using credits.

function createProfileUsingCredits(  Types.CreateProfileParams calldata createProfileParams,  address[] calldata delegatedExecutors) external returns (uint256);
struct CreateProfileParams {  address to;  address followModule;  bytes followModuleInitData;}

Use the createHandleWithCredits function to mint a new Handle using credits.

function createHandleWithCredits(  address to,  string calldata handle) external returns (uint256);

Use the standard ERC-721 transferFrom method on the Handle NFT contract (refer to LensHandles in smart contracts) to transfer the Handle to the user.

Once the Profile is minted, the app builder can transfer it to the user using the standard ERC-721 transferFrom method on the Profile NFT contract (refer to LensHub in smart contracts).

If the Profile was created with delegatedExecutors (i.e., Profile Manager addresses), the transferFromKeepingDelegates function should be used to maintain this configuration after transferring the Profile to the user. This function is available on the PermissionlessCreator smart contract.

function transferFromKeepingDelegates(  address from,  address to,  uint256 tokenId) external;

It's worth noting that the credit address you provide to the Lens Protocol team can be a smart contract. This allows you to incorporate flexible rules into your onboarding process. For instance, you could set conditions such as requiring users to hold a specific NFT, or you could charge your own fee for onboarding. All these conditions can be composed on-chain.

Below, we provide two examples to illustrate the simplicity of creating a wrapper contract. However, the possibilities are endless, and you can customize your contract to suit your specific needs.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;
import {Ownable} from '@openzeppelin/contracts/access/Ownable.sol';
struct CreateProfileParams {    address to;    address followModule;    bytes followModuleInitData;}
interface IPermissonlessCreator {    function createProfileUsingCredits(        CreateProfileParams calldata createProfileParams,        address[] calldata delegatedExecutors    ) external returns (uint256);
    function createProfileWithHandleCredits(        CreateProfileParams calldata createProfileParams,        string calldata handle,        address[] calldata delegatedExecutors    ) external returns (uint256, uint256);
    function createHandleWithCredits(        address to,        string calldata handle    ) external returns (uint256);}
contract AppChargeLensOnboarding is Ownable {    // load the permissonless creator contract    IPermissonlessCreator public immutable PERMISSONLESS_CREATOR;
    // the cost to buy a profile with handle    uint256 public profileWithHandleCreationCost = 1 ether;
    error InvalidFunds();
    constructor(address owner, address permissonlessCreator) {        _transferOwnership(owner);        PERMISSONLESS_CREATOR = IPermissonlessCreator(permissonlessCreator);    }
    // charge funds send to your beneficiary and then create profile for the user    function createProfileWithHandle(        CreateProfileParams calldata createProfileParams,        string calldata handle,        address[] calldata delegatedExecutors    ) external payable returns (uint256 profileId, uint256 handleId) {        if (msg.value != profileWithHandleCreationCost) {            revert InvalidFunds();        }
        // delegatedExecutors are only allowed if to == msg.sender        if (delegatedExecutors.length > 0 && createProfileParams.to != msg.sender) {            revert NotAllowed();        }
        return PERMISSONLESS_CREATOR.createProfileWithHandleCredits(createProfileParams, handle, delegatedExecutors);    }
    function withdrawFunds() external onlyOwner {        payable(owner()).transfer(address(this).balance);    }}

Alternatively, you could use an Externally Owned Account (EOA) and manage the gating on the backend. This flexibility makes it a highly adaptable onboarding system.

In the card onboarding, the user is guided through the process of creating a Lens Profile with their desired Handle for a fee of 10 USD.

This feature is enabled through an integration with Stripe, a popular payment gateway. The Custom payment flow from Stripe is used, offering flexibility to customize the payment experience to suit your needs.

The following sequence diagrams shows in broad strokes how the integration works.

The process unfolds as follows:

Finally, the UI can fetch the newly created Profile and continue with the onboarding process.

The Lens API offers specific endpoints for this integration, available at the designated paths on the Lens API URL for each environment.

Two of these endpoints, Create Payment Intent and Get Blockchain Info, require a shared secret for server-to-server communication.

To use these endpoints, contact the Lens Protocol team to obtain a shared secret for your application. This shared secret should be included in the x-shared-secret HTTP headers when making requests.

Use the POST /payments/create endpoint to create a Payment Intent. This endpoint requires the user's wallet address and the desired Handle local-name. The Lens API will respond with the Payment Intent's client secret, which you can use to initiate the Stripe Checkout form.

POST /payments/createHost: <api-url>Accept: application/jsonContent-Type: application/jsonContent-Length: 103x-shared-secret: <shared-secret>{  "address": "0x1234567890abcdef1234567890abcdef12345678",  "handle": "wagmi",  "currency": "usd"}

HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 137{  "id": "pi_1J3xjz2eZvKYlo2C5z3z",  "for": "0x1234567890abcdef1234567890abcdef12345678",  "clientSecret": "pi_1J3xjz2eZvKYlo2C5z3z"}

HTTP/1.1 400 Bad RequestContent-Type: text/plainContent-Length: 21HANDLE_ALREADY_EXISTS

Use the GET /payments/<paymentIntentId>/blockchain-tx-info endpoint to retrieve the Blockchain Transaction Info associated with a specific Payment Intent ID that was previously created.

GET /payments/<paymentIntentId>/blockchain-tx-infoHost: <api-url>Accept: application/jsonx-shared-secret: <shared-secret>

HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 160{  "status": "FULL_SUCCESS",  "txId": "a8b3a0f9-87d7-42e5-b214-31ea3b76247b",  "handle": "wagmi",  "address": "0x1234567890abcdef1234567890abcdef12345678"}

Use the GET /payments/cost endpoint to retrieve the fiat cost of onboarding a user. This endpoint is useful for displaying the cost to the user before initiating the payment process.

GET /payments/costHost: <api-url>Accept: application/json

HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 16{  "cost": 10}

export const dynamic = "force-dynamic";
export async function POST(request: Request) {  const response = await fetch(`${process.env.LENS_API}/payments/create`, {    method: "POST",    headers: {      "Content-Type": "application/json",      "x-shared-secret": process.env.SHARED_SECRET,    },    body: await request.text(),  });
  if (response.ok) {    const data = await response.json();    return Response.json({ data, success: true }, { status: 200 });  }
  const error = await response.text();  return Response.json(    { error, success: false },    { status: response.status }  );}

export const dynamic = "force-dynamic";
type Params = { paymentIntentId: string };
export async function GET(request: Request, { params }: { params: Params }) {  const response = await fetch(    `${process.env.LENS_API}/payments/${params.paymentIntentId}/blockchain-tx-info`,    {      method: "GET",      headers: {        "Content-Type": "application/json",        "x-shared-secret": process.env.SHARED_SECRET,      },    }  );
  if (response.ok) {    const data = await response.json();    return Response.json({ data, success: true }, { status: 200 });  }
  const error = await response.text();  return Response.json(    { error, success: false },    { status: response.status }  );}

For testing your integration against the Amoy Testnet deployment, you can utilize the following test card details.

The standard onboarding process can be challenging when developing new applications that require multiple test profiles. To alleviate this, a feature is available exclusively on the Testnet, enabling the programmatic creation of Testnet Profiles.

import { LensClient, development, isRelaySuccess } from "@lens-protocol/client";
const client = new LensClient({  environment: development, // wont't work with `production`});
const result = await client.wallet.createProfileWithHandle({  // e.g. 'alice' which will be '@lens/alice' in full-handle notation  handle: "<local name>",  to: "<your address>",});
// handle relay errorsif (!isRelaySuccess(profileCreateResult)) {  console.error(`Something went wrong`, result);  process.exit(1);}
// wait for the transaction to be mined and indexedconst outcome = await client.transaction.waitUntilComplete({  forTxId: result.txId,});
// handle transaction not foundif (outcome === null) {  console.error("The transaction was not found");  process.exit(1);}
console.log("Profile created");