🎭Allow List

Learn how to use the Allow List Middleware to check whether a user is allowed to use your Frames.js Frames based on their onchain data.

Get Started

First, install the Airstack Frames SDK:

npm

npm install @airstack/frames

yarn

yarn add @airstack/frames

pnpm

pnpm install @airstack/frames

bun

bun install @airstack/frames

Check User's Farcaster Followers Count

You can use the allowListFramesjsMiddleware to check if a user has certain number of followers by using the NUMBER_OF_FARCASTER_FOLLOWERS and specifying the criteria using one of the comparison operator offered by Airstack:

TypeScript

import { createFrames, Button } from "frames.js/next";
import {
  AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
} from "@airstack/frames";

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY as string,
        criteria: {
          or: [
            // Only allow those with greater than 100 followers
            [AllowListCriteria.NUMBER_OF_FARCASTER_FOLLOWERS, { _gte: 100 }],
          ],
        },
      }),
    ],
  }
);

JavaScript

const { createFrames, Button } = require("frames.js/next");
const {
  type AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
} = require("@airstack/frames");

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY,
        criteria: {
          or: [
            // Only allow those with greater than 100 followers
            [AllowListCriteria.NUMBER_OF_FARCASTER_FOLLOWERS, { _gte: 100 }],
          ],
        },
      }),
    ],
  }
);

Response

true

Check If User Is Followed By Certain Farcaster User

You can use the allowListFramesjsMiddleware to check if a user is followed by a certain Farcaster user by using the FARCASTER_FOLLOWED_BY and specifying the fid of that certain Farcaster user:

TypeScript

import { createFrames, Button } from "frames.js/next";
import {
  AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
} from "@airstack/frames";

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY as string,
        criteria: {
          or: [
            // Only allow those who are followed by fid 1
            [AllowListCriteria.FARCASTER_FOLLOWED_BY, { fid: 1 }],
          ],
        },
      }),
    ],
  }
);

JavaScript

const { createFrames, Button } = require("frames.js/next");
const {
  type AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
} = require("@airstack/frames");

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY,
        criteria: {
          or: [
            // Only allow those who are followed by fid 1
            [AllowListCriteria.FARCASTER_FOLLOWED_BY, { fid: 1 }],
          ],
        },
      }),
    ],
  }
);

Response

true

Check If User Is Following Certain Farcaster User

You can use the allowListFramesjsMiddleware to check if a user is following a certain Farcaster user by using the FARCASTER_FOLLOWED_BY and specifying the fid of that certain Farcaster user:

TypeScript

import { createFrames, Button } from "frames.js/next";
import {
  AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
} from "@airstack/frames";

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY as string,
        criteria: {
          or: [
            // Only allow those who are following fid 1
            [AllowListCriteria.FARCASTER_FOLLOWING, { fid: 1 }],
          ],
        },
      }),
    ],
  }
);

JavaScript

const { createFrames, Button } = require("frames.js/next");
const {
  type AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
} = require("@airstack/frames");

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY,
        criteria: {
          or: [
            // Only allow those who are following fid 1
            [AllowListCriteria.FARCASTER_FOLLOWING, { fid: 1 }],
          ],
        },
      }),
    ],
  }
);

Response

true

Check If User Is Following The Caster

You can use the allowListFramesjsMiddleware to check if a user is following the caster of the Frame by using the FARCASTER_FOLLOWING_CASTER:

TypeScript

import { createFrames, Button } from "frames.js/next";
import {
  AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
} from "@airstack/frames";

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY as string,
        criteria: {
          or: [
            // Only allow those who are following the caster
            [AllowListCriteria.FARCASTER_FOLLOWING_CASTER],
          ],
        },
      }),
    ],
  }
);

JavaScript

const { createFrames, Button } = require("frames.js/next");
const {
  type AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
} = require("@airstack/frames");

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY,
        criteria: {
          or: [
            // Only allow those who are following the caster
            [AllowListCriteria.FARCASTER_FOLLOWING_CASTER],
          ],
        },
      }),
    ],
  }
);

Response

true

Check If User Hold Certain Token

You can use the allowListFramesjsMiddleware to check if a user is holding certain token on Ethereum, Base, Degen Chain, and other Airstack-supported chains by using the TOKEN_HOLD and specify the token's address and chain:

TypeScript

import { createFrames, Button } from "frames.js/next";
import {
  AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
  TokenBlockchain,
} from "@airstack/frames";

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY as string,
        criteria: {
          or: [
            // Only allow holders of this token on Base
            [AllowListCriteria.TOKEN_HOLD, {
              chain: TokenBlockchain.Base,
              address: "0x4c17ff12d9a925a0dec822a8cbf06f46c6268553",
            }],
          ],
        },
      }),
    ],
  }
);

JavaScript

const { createFrames, Button } = require("frames.js/next");
const {
  type AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
  type TokenBlockchain,
} = require("@airstack/frames");

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY,
        criteria: {
          or: [
            // Only allow holders of this token on Base
            [AllowListCriteria.TOKEN_HOLD, {
              chain: TokenBlockchain.Base,
              address: "0x4c17ff12d9a925a0dec822a8cbf06f46c6268553",
            }],
          ],
        },
      }),
    ],
  }
);

Response

true

Check If User Minted Certain Token

You can use the allowListFramesjsMiddleware to check if a user has minted certain token on Ethereum, Base, Degen Chain, and other Airstack-supported chains by using the TOKEN_HOLD and specify the token's address and chain:

TypeScript

import { createFrames, Button } from "frames.js/next";
import {
  AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
  TokenBlockchain,
} from "@airstack/frames";

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY as string,
        criteria: {
          or: [
            // Only allow minters of this token on Base
            [AllowListCriteria.TOKEN_MINT, {
              chain: TokenBlockchain.Base,
              address: "0x4c17ff12d9a925a0dec822a8cbf06f46c6268553",
            }],
          ],
        },
      }),
    ],
  }
);

JavaScript

const { createFrames, Button } = require("frames.js/next");
const {
  type AllowListCriteriaEnum as AllowListCriteria,
  allowListFramesjsMiddleware as allowList,
  type TokenBlockchain,
} = require("@airstack/frames");

const frames = createFrames();

const handleRequest = frames(
  async (ctx) => {
    // Use `ctx.isAllowed` to check if user is allowed or not
    // based on the Farcaster followers count
    console.log(ctx.isAllowed);
    return {
      image: (<div></div>),
      buttons: [],
    };
  },
  {
    middleware: [
      // Allow List Middleware
      allowList({
        apiKey: process.env.AIRSTACK_API_KEY,
        criteria: {
          or: [
            // Only allow minters of this token on Base
            [AllowListCriteria.TOKEN_MINT, {
              chain: TokenBlockchain.Base,
              address: "0x4c17ff12d9a925a0dec822a8cbf06f46c6268553",
            }],
          ],
        },
      }),
    ],
  }
);

Response

true

Developer Support

If you have any questions or need help regarding building Farcaster Frames with Airstack Frames.js Middleware, please join our Airstack's Telegram group.

More Resources

• Allow List Frames.js Middleware Reference