πŸ“ΊFarcaster Channels

Learn how to fetch data from Farcaster channels, including their original host, followers, and participants who have interacted (either by casting or replying) within the channels.

Table Of Contents

In this guide, you will learn to use Airstack to:

Pre-requisites

  • An Airstack account

  • Basic knowledge of GraphQL

Get Started

JavaScript/TypeScript/Python

If you are using JavaScript/TypeScript or Python, Install the Airstack SDK:

React

npm install @airstack/airstack-react

Node

npm install @airstack/node

Then, add the following snippets to your code:

import { init, useQuery } from "@airstack/airstack-react";

init("YOUR_AIRSTACK_API_KEY");

const query = `YOUR_QUERY`; // Replace with GraphQL Query

const Component = () => {
  const { data, loading, error } = useQuery(query);

  if (data) {
    return <p>Data: {JSON.stringify(data)}</p>;
  }

  if (loading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>Error: {error.message}</p>;
  }
};

Other Programming Languages

To access the Airstack APIs in other languages, you can use https://api.airstack.xyz/gql as your GraphQL endpoint.

Get Channel Details

Get Channel Details Tutorial

You can fetch a certain channel details by using the FarcasterChannels and providing the channel ID (e.g. /farcaster channel ID is "farcaster") to $channelId variable:

Try Demo

Get /farcaster Farcaster channel details

Code

query MyQuery {
  FarcasterChannels(
    input: {
      blockchain: ALL,
      filter: {
        channelId: {_eq: "farcaster"} # input 'farcaster' for /farcaster channel
      }
    }
  ) {
    FarcasterChannel {
      channelId
      dappName
      createdAtTimestamp
      dappSlug
      description
      followerCount
      name
      url
      imageUrl
    }
  }
}

Get All Casts Casted In A Channel

Get All Casts In A Channel Tutorial

You can fetch all the casts casted in a certain Farcaster channel by using the FarcasterCasts API and providing the Farcaster channel's URL to the channelUrl filter:

If you don't know the channel's URL, then find the channel's URL with this query here. The url field will return you the channel's URL associated with the given channel ID.

Try Demo

Code

query MyQuery {
  FarcasterCasts(
    input: {
      filter: {
        rootParentUrl: {
          # add channel URL here
          _eq: "https://warpcast.com/~/channel/airstack"
        }
      },
      blockchain: ALL
    }
  ) {
    Cast {
      castedAtTimestamp
      castedBy {
        profileName
        fid: userId
      }
      embeds
      fid
      hash
      text
      numberOfLikes
      numberOfRecasts
      numberOfReplies
    }
  }
}

Get All The Most Followed Farcaster Channels

You can fetch all Farcaster channels sorted by their follower count in descending order by using the FarcasterChannels API:

Try Demo

Code

query MyQuery {
  FarcasterChannels(
    input: {
      blockchain: ALL,
      # specify to sort in descending order by followerCount
      order: {followerCount: DESC}
    }
  ) {
    FarcasterChannel {
      name
      channelId
      followerCount
    }
  }
}

Get All The Most Recently Created Farcaster Channels

You can fetch all Farcaster channels sorted by their creation timestamp in descending order by using the FarcasterChannels API:

Try Demo

Code

query MyQuery {
  FarcasterChannels(
    input: {
      blockchain: ALL,
      # specify to sort in descending order by createdAtTimestamp
      order: {createdAtTimestamp: DESC}
    }
  ) {
    FarcasterChannel {
      name
      channelId
      createdAtTimestamp
    }
  }
}

Get Followers Of A Channel

You can fetch all the followers of a Farcaster channel by using FarcasterChannelParticipants by providing the channel ID (e.g. /farcaster channel ID is "farcaster") to $channelId variable and specify channelActions to "follow" value:

Try Demo

Code

query MyQuery {
  FarcasterChannelParticipants(
    input: {
      filter: {
        channelName: {_eq: "/airstack"},
        channelActions: {_eq: follow}
      },
      blockchain: ALL,
      limit: 200
    }
  ) {
    FarcasterChannelParticipant {
      participant {
        profileName
        fid: userId
      }
      lastCastedTimestamp
    }
  }
}

Get Participants Of A Channel

Channel participants includes users that:

  • followed the channel

  • casted in the channel

  • replied to a cast in a channel

If you are only looking for channel followers, click here.

You can fetch all the participants of a channel by using the FarcasterChannels and providing the channel ID (e.g. /farcaster channel ID is "farcaster") to $channelId variable:

Try Demo

Code

query MyQuery {
  FarcasterChannels(
    input: {
      blockchain: ALL,
      filter: {
        channelId: {_eq: "farcaster"} # input 'farcaster' for /farcaster channel
      }
    }
  ) {
    FarcasterChannel {
      participants {
        participant {
          userAddress
          profileName
          fid: userId
          userAssociatedAddresses
          followerCount
          followingCount
        }
      }
    }
  }
}

Get The Original Host Of A Channel

You can fetch the original host of a Farcaster channel by using the FarcasterChannels and providing the channel ID (e.g. /farcaster channel ID is "farcaster") to $channelId variable:

Try Demo

Code

query MyQuery {
  FarcasterChannels(
    input: {
      blockchain: ALL,
      filter: {
        channelId: {_eq: "farcaster"} # input 'farcaster' for /farcaster channel
      }
    }
  ) {
    FarcasterChannel {
      leadProfiles {
        userAddress
        profileName
        fid: userId
        userAssociatedAddresses
        followerCount
        followingCount
      }
    }
  }
}

Get All The Channels Followed By A User

You can fetch all the channel a given Farcaster user follows by using the FarcasterChannelParticipants and providing the participant's FID to $participant variable and specifying the channelActions to "follow":

Try Demo

Code

query MyQuery {
  FarcasterChannelParticipants(
    input: {
      filter: {
        channelActions: {_eq: follow},
        participant: {_eq: "fc_fid:602"}
      },
      blockchain: ALL,
      limit: 200
    }
  ) {
    FarcasterChannelParticipant {
      channelName
      channelId
      lastFollowedTimestamp
    }
  }
}

Get All The Channels Of A Farcaster User Participates In

Channel participants includes users that:

  • followed the channel

  • casted in the channel

  • replied to a cast in a channel

If you are only looking for channel followers, click here.

You can fetch all the channel a given Farcaster user participates in (either have followed, casted, or replied to a cast) by using the FarcasterChannelParticipants and providing the participant's FID to $participant variable:

Try Demo

Code

query MyQuery {
  FarcasterChannelParticipants(
    input: {
      filter: {
        participant: {_eq: "fc_fid:602"} # Participant's FID
      },
      blockchain: ALL
    }
  ) {
    FarcasterChannelParticipant {
      channelName
    }
  }
}

Get All Farcaster Users Who Casted In Certain Channel

You can fetch all Farcaster users who casted in a given channel by using the FarcasterChannelParticipants and providing the $channelActions variable with "cast" value and the channel ID (e.g. /farcaster channel ID is "farcaster") to $channelId variable:

Try Demo

Code

query MyQuery {
  FarcasterChannelParticipants(
    input: {
      filter: {
        channelActions: {_eq: cast}, # Filter only for those who casted
        channelId: {_eq: "warpcast"}, # Search in /warpcast channel
      },
      blockchain: ALL
    }
  ) {
    FarcasterChannelParticipant {
      participant {
        userAddress
        profileName
        fid: userId
      }
    }
  }
}

Get All Farcaster Users Who Casted In Certain Channel Since Certain Timestamp

You can fetch all Farcaster users who casted in a given channel since a certain time by using the FarcasterChannelParticipants and providing:

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

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

  • the timestamp to the $lastActionTimestamp variable, e.g. 2024-02-01T00:00:00Z for Feb 1, 2024 at 00:00.

Try Demo

Code

query MyQuery {
  FarcasterChannelParticipants(
    input: {
      filter: {
        channelActions: {_eq: cast}, # Filter only for those who casted
        channelId: {_eq: "warpcast"}, # Search in /warpcast channel
        # Filter last timestamp to be "greater than or equal to" Feb 1st, 2024
        lastActionTimestamp: {_gte: "2024-02-01T00:00:00Z"}
      },
      blockchain: ALL
    }
  ) {
    FarcasterChannelParticipant {
      participant {
        userAddress
        profileName
        fid: userId
      }
    }
  }
}

Get All Farcaster Users Who Participates In A Channel And Following The Host

To fetch all Farcaster users who participates in a channel and following the host, you'll first need to fetch the original host of the channel:

Try Demo

Code

query MyQuery {
  FarcasterChannels(
    input: { blockchain: ALL, filter: { channelId: { _eq: "airstack" } } }
  ) {
    FarcasterChannel {
      leadIds
    }
  }
}

Once you have the original host's FID, you can then use it as an input variable to check on each participant if they're following the original host or not:

Try Demo

Code

query MyQuery($originalHost: Identity!) {
  FarcasterChannelParticipants(
    input: { filter: { channelId: { _eq: "airstack" } }, blockchain: ALL }
  ) {
    FarcasterChannelParticipant {
      participant {
        userAddressDetails {
          socialFollowers(
            input: { filter: { identity: { _eq: $originalHost } } }
          ) {
            Follower {
              followerAddress {
                addresses
                socials(input: { filter: { dappName: { _eq: farcaster } } }) {
                  profileName
                  fid: userId
                  userAssociatedAddresses
                  followerCount
                  followingCount
                }
              }
            }
          }
        }
      }
    }
  }
}

Here, you can simply filter out those who return null as they are a participant of the /airstack channel, but does not follow the original host.

Get All Farcaster Channel Participants That Also Have A Power Badge

You can fetch all the channel participants of a Farcaster channel and check if they have a power badge by using the FarcasterChannelParticipants API:

Try Demo

Code

query MyQuery {
  FarcasterChannelParticipants(
    input: {
      filter: {
        channelId: {_eq: "airstack"}
      },
      blockchain: ALL
    }
  ) {
    FarcasterChannelParticipant {
      participantId
      participant {
        profileName
        isFarcasterPowerUser
      }
    }
  }
}

Check If Farcaster User Has Followed A Given Channel

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

  • the "follow" 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

Code

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