Custom Feeds

This guide will introduce the concept of Custom Feeds and how to create and manage them.

As mentioned in the Feed concept page, there are two classes of Feed instances:

The Global Feed: The familiar shared feed that aggregates all public Lens activity.
Custom Feeds: App or group-specific feeds that can be open or governed by Feed Rules.

Create a Custom Feed

To create a Custom Feed, follow these steps.

You MUST be authenticated as Builder to create a Feed.

Create Metadata

First, construct a Feed Metadata object with the necessary content.

TS/JS
JSON Schema

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

Exampleimport { feed } from "@lens-protocol/metadata";
const metadata = feed({  name: "XYZ",  description: "My custom feed description",});

Upload Metadata

Next, upload the Feed Metadata object to a public URI.

import { storageClient } from "./storage-client";
const { uri } = await storageClient.uploadAsJson(metadata);
console.log(uri); // e.g., lens://4f91ca…

This example uses Grove storage to host the Metadata object. See the Lens Metadata Standards guide for more information on hosting Metadata objects.

Deploy Feed Contract

Next, deploy the Lens Feed smart contract.

TypeScript
GraphQL
React

Use the createFeed action to deploy the Lens Feed smart contract.

import { uri } from "@lens-protocol/client";import { createFeed } from "@lens-protocol/client/action";
const result = await createFeed(sessionClient, {  metadataUri: uri("lens://4f91ca…"),});

To learn more about how to use Feed Rules, see the Feed Rules guide.

Handle Result

TypeScript
GraphQL
React

Next, handle the result using the adapter for the library of your choice and wait for it to be indexed.

import { handleOperationWith } from "@lens-protocol/client/viem";
// …
const result = await createFeed(sessionClient, {  metadataUri: uri("lens://4f91ca…"),})  .andThen(handleOperationWith(walletClient))  .andThen(sessionClient.waitForTransaction);

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

Fetch New Feed

TypeScript
GraphQL

Finally, fetch the newly created Feed using the fetchFeed action.

viemimport { fetchFeed } from "@lens-protocol/client/actions";
// …
const result = await createFeed(sessionClient, {  metadataUri: uri("lens://4f91…"), // the URI from the previous step})  .andThen(handleOperationWith(walletClientOrSigner))  .andThen(sessionClient.waitForTransaction)  .andThen((txHash) => fetchFeed(sessionClient, { txHash }));
if (result.isErr()) {  return console.error(result.error);}
// feed: Feed | nullconst feed = result.value;

Fetch a Feed

TypeScript
GraphQL
React

Use the fetchFeed action to fetch a single Feed by address or by transaction hash.

import { evmAddress } from "@lens-protocol/client";import { fetchFeed } from "@lens-protocol/client/actions";import { client } from "./client";
const result = await fetchFeed(client, {  address: evmAddress("0x1234…"),});
if (result.isErr()) {  return console.error(result.error);}
const feed = result.value;

Search Feeds

TypeScript
GraphQL
React

Use the paginated fetchFeeds action to search for feeds.

import { fetchFeeds } from "@lens-protocol/client/actions";
import { client } from "./client";
const result = await fetchFeeds(client, {  filter: {    searchBy: "feedName",  },});
if (result.isErr()) {  return console.error(result.error);}
// items: Array<Feed>const { items, pageInfo } = result.value;

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

Access Control

The Feed contract supports two roles: Owner and Administrator.

Administrators can:

Update the Feed Metadata
Update the Feed Rules
Update the Feed Extra Data

The Owner can do everything the administrators can do, plus transfer ownership of the Feed to another address.

See the Team Management guide for more information on how to manage these roles.