🎭Allow List

Learn how to build an Allow List for your Farcaster Frames based on various criterias by using the Airstack Frames SDK.

You can limit access to your Farcaster Frame to only certain users that fulfill a requirement by creating an allow list based on certain criteria.

Get Started

First, install the Airstack Frog Recipes:

npm

npm install @airstack/frog hono

yarn

yarn add @airstack/frog hono

pnpm

pnpm install @airstack/frog hono

bun

bun install @airstack/frog hono

Create A Custom Allow List

You can create an allow list that checks various onchain data easily using the createAllowList function. Some of the parameters that you can add to the allow list are:

Name	Type	Description
numberOfFollowersOnFarcaster	number	Check If the number of Farcaster followers greater than or equal to the given number.
isFollowingOnFarcaster	number[]	Check if the given FIDs are being followed by a Farcaster user.

Once you have the criteria set, the function will help you check whether all the criterias are fulfilled.

By default, it will only return true for Farcaster users that satisfy ALL the given requirements. However, if you would like to check your user with a different logic, you can provide an optional custom isAllowedFunction:

TypeScript

import {
  createAllowList,
  CreateAllowListInput,
  CreateAllowListOutput,
  TokenBlockchain,
} from "@airstack/frames";

const allowListCriteria = {
  numberOfFollowersOnFarcaster: 100,
  isFollowingOnFarcaster: [2602],
};
const input: CreateAllowListInput = {
  fid: 602,
  allowListCriteria,
  isAllowedFunction: function (data) {
    console.log(data);
    return true;
  },
};
const { isAllowed, error }: CreateAllowListOutput = await createAllowList(
  input
);

if (error) throw new Error(error);

console.log(isAllowed);

JavaScript

const { createAllowList, TokenBlockchain } = require("@airstack/frames");

const allowListCriteria = {
  numberOfFollowersOnFarcaster: 100,
  isFollowingOnFarcaster: [2602],
};
const input = {
  fid: 602,
  allowListCriteria,
  isAllowedFunction: function (data) {
    console.log(data);
    return true;
  },
};
const { isAllowed, error } = await createAllowList(input);

if (error) throw new Error(error);

console.log(isAllowed);

Response

{
  "isAllowed": true,
  "error": null
}

Check If User Is Following Farcaster User(s)

You can check if a Farcaster user is following a list of FIDs by using the checkIsFollowingFarcasterUser function:

TypeScript

import {
  checkIsFollowingFarcasterUser,
  CheckIsFollowingFarcasterUserInput,
  CheckIsFollowingFarcasterUserOutput,
} from "@airstack/frames";

const input: CheckIsFollowingFarcasterUserInput = {
  fid: 602,
  isFollowing: [2602, 15971, 13242],
};
const { data, error }: CheckIsFollowingFarcasterUserOutput =
  await checkIsFollowingFarcasterUser(input);

if (error) throw new Error(error);

console.log(data);

JavaScript

const { checkIsFollowingFarcasterUser } = require("@airstack/frames");

const input = {
  fid: 602,
  isFollowing: [2602, 15971, 13242],
};
const { data, error } = await checkIsFollowingFarcasterUser(input);

if (error) throw new Error(error);

console.log(data);

Response

[
  { "fid": 2602, "isFollowing": true },
  { "fid": 15971, "isFollowing": true },
  { "fid": 13242, "isFollowing": false }
]

Check If User Is Followed By Farcaster User(s)

You can check if a Farcaster user is being followed by a list of FIDs by using the checkIsFollowedByFarcasterUser function:

TypeScript

import {
  checkIsFollowedByFarcasterUser,
  CheckIsFollowedByFarcasterUserInput,
  CheckIsFollowedByFarcasterUserOutput,
} from "@airstack/frames";

const input: CheckIsFollowedByFarcasterUserInput = {
  fid: 602,
  isFollowedBy: [2602, 15971, 13242],
};
const { data, error }: CheckIsFollowedByFarcasterUserOutput =
  await checkIsFollowedByFarcasterUser(input);

if (error) throw new Error(error);

console.log(data);

JavaScript

const {
  checkIsFollowedByFarcasterUser,
  CheckIsFollowedByFarcasterUserInput,
  CheckIsFollowedByFarcasterUserOutput,
} = require("@airstack/frames");

const input = {
  fid: 602,
  isFollowedBy: [2602, 15971, 13242],
};
const { data, error } = await checkIsFollowedByFarcasterUser(input);

if (error) throw new Error(error);

console.log(data);

Response

[
  { "fid": 2602, "isFollowedBy": true },
  { "fid": 15971, "isFollowedBy": true },
  { "fid": 13242, "isFollowedBy": false }
]

Check If Farcaster User Is Followed By Certain High Profile Users

You can check if the Farcaster user is followed by certain high profile users, e.g. vitalik.eth, jessepollak, etc., by using the checkIsFollowedByFarcasterUser function:

TypeScript

import {
  checkIsFollowedByFarcasterUser,
  CheckIsFollowedByFarcasterUserInput,
  CheckIsFollowedByFarcasterUserOutput,
} from "@airstack/frames";

const input: CheckIsFollowedByFarcasterUserInput = {
  fid: 602,
  isFollowedBy: [
    99, // jessepollak
    5650, // vitalik.eth
  ],
};
const { data, error }: CheckIsFollowedByFarcasterUserOutput =
  await checkIsFollowedByFarcasterUser(input);

if (error) throw new Error(error);

console.log(data);

JavaScript

const { checkIsFollowedByFarcasterUser } = require("@airstack/frames");

const input = {
  fid: 602,
  isFollowedBy: [
    99, // jessepollak
    5650, // vitalik.eth
  ],
};
const { data, error } = await checkIsFollowedByFarcasterUser(input);

if (error) throw new Error(error);

console.log(data);

Result

[
  { "fid": 99, "isFollowedBy": true },
  { "fid": 5650, "isFollowedBy": false }
]

Check If Farcaster User Follows The Creator Of The Frames

You can check if the Farcaster user follows the Frames' creator by using the checkIsFollowingFarcasterUser function:

TypeScript

import {
  checkIsFollowingFarcasterUser,
  CheckIsFollowingFarcasterUserInput,
  CheckIsFollowingFarcasterUserOutput,
} from "@airstack/frames";

const input: CheckIsFollowingFarcasterUserInput = {
  fid: 3,
  isFollowing: [99],
};
const { data, error }: CheckIsFollowingFarcasterUserOutput =
  await checkIsFollowingFarcasterUser(input);

if (error) throw new Error(error);

console.log(data);

JavaScript

import {
  checkIsFollowingFarcasterUser,
  CheckIsFollowingFarcasterUserInput,
  CheckIsFollowingFarcasterUserOutput,
} from "@airstack/frames";

const input: CheckIsFollowingFarcasterUserInput = {
  fid: 3, // The creator of frame
  isFollowing: [99], // The fid of user interacting with your frames
};
const { data, error }: CheckIsFollowingFarcasterUserOutput =
  await checkIsFollowingFarcasterUser(input);

if (error) throw new Error(error);

console.log(data);

Result

[{ "fid": 99, "isFollowing": true }]

Check If Farcaster User Has Casted In A Given Channel

You can check if Farcaster user has casted in a given channel by using the FarcasterChannelParticipants API and providing:

• the "cast" value to the $channelActions variable,

• the channel ID (e.g. /farcaster channel ID is "farcaster") to $channelId variable, and

• the FID to the $participant variable

Try Demo

https://app.airstack.xyz/query/PkFu8vdw9o

Check if Farcaster user FID 602 is participating in airstack channel

Code

Query

query MyQuery {
  FarcasterChannelParticipants(
    input: {
      filter: {
        participant: { _eq: "fc_fid:602" }
        channelId: { _eq: "airstack" }
        channelActions: { _eq: cast }
      }
      blockchain: ALL
    }
  ) {
    FarcasterChannelParticipant {
      lastActionTimestamp
    }
  }
}

Response

{
  "data": {
    "FarcasterChannelParticipants": {
      "FarcasterChannelParticipant": [
        {
          "lastActionTimestamp": "2024-02-23T17:12:13Z"
        }
      ]
    }
  }
}

Developer Support

If you have any questions or need help building an allow list for your Farcaster Frames using the Airstack Frames SDK, please join our Airstack's Telegram group.

More Resources

• Farcaster Data

• Farcaster Hubs

• Integrate to Existing Frog Project