🫂Followers
Learn how to fetch Web3 Social Followers data and its various use cases and combinations.
Airstack provides easy-to-use APIs for enriching Web3 social applications with and integrating on-chain and off-chain data with Lens and Farcaster.
Table Of Contents
In this guide you will learn how 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
React
yarn add @airstack/airstack-react
Node
yarn add @airstack/node
React
pnpm install @airstack/airstack-react
Node
pnpm install @airstack/node
pip install airstack
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>;
}
};
import { init, fetchQuery } from "@airstack/node";
init("YOUR_AIRSTACK_API_KEY");
const query = `YOUR_QUERY`; // Replace with GraphQL Query
const { data, error } = await fetchQuery(query);
console.log("data:", data);
console.log("error:", error);
import asyncio
from airstack.execute_query import AirstackClient
api_client = AirstackClient(api_key="YOUR_AIRSTACK_API_KEY")
query = """YOUR_QUERY""" # Replace with GraphQL Query
async def main():
execute_query_client = api_client.create_execute_query_object(
query=query)
query_response = await execute_query_client.execute_query()
print(query_response.data)
asyncio.run(main())
Other Programming Languages
To access the Airstack APIs in other languages, you can use https://api.airstack.xyz/gql as your GraphQL endpoint.
Get All Followers of 0x Address(es)
You can get the list of followers data of user(s) by inputting an array of 0x address(es)[^1]:
Try Demo
Code
query MyQuery {
SocialFollowers(
input: {
filter: {
identity: { _in: ["0xeaf55242a90bb3289dB8184772b0B98562053559"] }
}
blockchain: ALL
limit: 200
}
) {
Follower {
followerAddress {
addresses
domains {
name
}
socials {
dappName
profileName
profileTokenId
profileTokenIdHex
userId
userAssociatedAddresses
}
}
followerProfileId
followerTokenId
followingAddress {
addresses
}
followingProfileId
}
}
}
{
"data": {
"SocialFollowers": {
"Follower": [
{
"followerAddress": {
"addresses": ["0x3a134eb077cda063dec6f507e969556ddcb4e1f9"],
"domains": [],
"socials": [
{
"dappName": "farcaster",
"profileName": "florist",
"profileTokenId": "13915",
"profileTokenIdHex": "0x0365b",
"userId": "13915",
"userAssociatedAddresses": [
"0x3a134eb077cda063dec6f507e969556ddcb4e1f9"
]
}
]
},
"followerProfileId": "13915",
"followerTokenId": "",
"followingAddress": {
"addresses": [
"0x66bd69c7064d35d146ca78e6b186e57679fba249",
"0xeaf55242a90bb3289db8184772b0b98562053559"
]
},
"followingProfileId": "602"
}
// more followers of 0xeaf55242a90bb3289dB8184772b0B98562053559
]
}
}
}
Get All Followers of ENS Domain(s)
You can get the list of all follower of ENS domains(s) by providing ENS domain name:
Try Demo
Code
query MyQuery {
SocialFollowers(
input: {
filter: { identity: { _in: ["vitalik.eth"] } }
blockchain: ALL
limit: 200
}
) {
Follower {
followerAddress {
addresses
domains {
name
}
socials {
dappName
profileName
profileTokenId
profileTokenIdHex
userId
userAssociatedAddresses
}
}
followerProfileId
followerTokenId
followingAddress {
domains {
name
}
}
followingProfileId
}
}
}
{
"data": {
"SocialFollowers": {
"Follower": [
{
"followerAddress": {
"addresses": [
"0x3e21146008f07e27745918b71357f1b3abc30ca8",
"0x99d80e209b4904aa2ef25a6014e1a7cf3ed6d5ee"
],
"domains": [],
"socials": [
{
"dappName": "farcaster",
"profileName": "scnullois",
"profileTokenId": "6119",
"profileTokenIdHex": "0x017e7",
"userId": "6119",
"userAssociatedAddresses": [
"0x3e21146008f07e27745918b71357f1b3abc30ca8",
"0x99d80e209b4904aa2ef25a6014e1a7cf3ed6d5ee"
]
}
]
},
"followerProfileId": "6119",
"followerTokenId": "",
"followingAddress": {
"domains": [
{
"name": "quantumexchange.eth"
},
{
"name": "7860000.eth"
},
{
"name": "offchainexample.eth"
},
{
"name": "brianshaw.eth"
},
{
"name": "vbuterin.stateofus.eth"
},
{
"name": "quantumsmartcontracts.eth"
},
{
"name": "Vitalik.eth"
},
{
"name": "openegp.eth"
},
{
"name": "vitalik.cannafam.eth"
},
{
"name": "VITALIK.eth"
},
{
"name": "quantumdapps.eth"
},
{
"name": "vitalik.soy.eth"
},
{
"name": "satoshinart.eth"
},
{
"name": "vitalik.eth"
},
{
"name": "eth.soy.eth"
},
{
"name": "vitalik.thepeople.eth"
},
{
"name": "vitalik.dev.eth"
},
{
"name": "vitalik.takoyaki.eth"
}
]
},
"followingProfileId": "5650"
}
// more followers of vitalik.eth
]
}
}
}
Get All Followers of Farcaster User(s)
You can get the list of followers of Farcaster user(s) by either providing either Farcaster name[^3] or Farcaster ID:
Try Demo
Code
query MyQuery {
SocialFollowers(
input: {
filter: { identity: { _in: ["fc_fname:vitalik.eth"] } }
blockchain: ALL
limit: 200
}
) {
Follower {
followerAddress {
addresses
domains {
name
}
socials {
dappName
profileName
profileTokenId
profileTokenIdHex
userId
userAssociatedAddresses
}
}
followerProfileId
followerTokenId
followingAddress {
addresses
socials(input: { filter: { dappName: { _eq: farcaster } } }) {
profileName
profileTokenId
profileTokenIdHex
}
}
followingProfileId
}
}
}
{
"data": {
"SocialFollowers": {
"Follower": [
{
"followerAddress": {
"addresses": [
"0x3e21146008f07e27745918b71357f1b3abc30ca8",
"0x99d80e209b4904aa2ef25a6014e1a7cf3ed6d5ee"
],
"domains": [],
"socials": [
{
"dappName": "farcaster",
"profileName": "scnullois",
"profileTokenId": "6119",
"profileTokenIdHex": "0x017e7",
"userId": "6119",
"userAssociatedAddresses": [
"0x3e21146008f07e27745918b71357f1b3abc30ca8",
"0x99d80e209b4904aa2ef25a6014e1a7cf3ed6d5ee"
]
}
]
},
"followerProfileId": "6119",
"followerTokenId": "",
"followingAddress": {
"addresses": [
"0xadd746be46ff36f10c81d6e3ba282537f4c68077",
"0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
],
"socials": [
{
"profileName": "vitalik.eth",
"profileTokenId": "5650",
"profileTokenIdHex": "0x01612"
}
]
},
"followingProfileId": "5650"
}
// more followers of Farcaster user vitalik.eth
]
}
}
}
Check If User A Is Followed By User B
This can be done by providing the user B's identity either a 0x address, ENS, cb.id, Lens, or Farcaster on the Wallet
top-level query's identity
input and the user A's identities in the socialFollowers
.
For example, check if betashop.eth
(user A) is followed by ipeciura.eth
(user B):
Try Demo
Code
If you need to check multiple users A simultaneously, then simply provide more identities into the identity
input in the socialFollowers
nested API.
query isFollowing { # Top-level is User B's Identity (ipeciura.eth)
Wallet(input: {identity: "ipeciura.eth", blockchain: ethereum}) {
socialFollowers( # Here is User A's Identity (betashop.eth)
input: {filter: {identity: {_in: ["betashop.eth"]}}}
) {
Follower {
dappName
dappSlug
followingProfileId
followerProfileId
followingAddress {
addresses
socials {
dappName
profileName
}
domains {
name
}
}
}
}
}
}
{
"data": {
"Wallet": {
"socialFollowers": {
"Followers": [
{
"dappName": "farcaster", // follower on Farcaster
"dappSlug": "farcaster_optimism",
"followingProfileId": "2602",
"followerProfileId": "602",
"followerAddress": {
"addresses": [
"0x66bd69c7064d35d146ca78e6b186e57679fba249",
"0xeaf55242a90bb3289db8184772b0b98562053559"
],
"socials": [
{
"dappName": "farcaster",
"profileName": "betashop.eth" // betashop.eth is being followed by ipeciura.eth
},
{
"dappName": "lens",
"profileName": "lens/@betashop9"
}
],
"domains": [
{
"name": "jasongoldberg.eth"
},
{
"name": "betashop.eth"
}
]
}
}
]
}
}
}
}
If betashop.eth
is followed by ipeciura.eth
on either Lens or Farcaster, then it will appear as a response in the Follower
array as shown in the sample response and thus should be classified as a known sender.
Otherwise, betashop.eth
will be considered an unknown sender and should be classified as one in the UI.
Get The Most Recent Followers of User(s)
You can get the list of most recent followers of users(s) by providing either 0x addresses, ENS names, Lens profiles, or Farcasters:
Try Demo
Code
query MyQuery {
SocialFollowers(
input: {
filter: {
identity: {
_in: [
"lens/@stani"
"lens_id:0x024"
"fc_fname:dwr.eth"
"fc_fid:3"
"vitalik.eth"
"0xeaf55242a90bb3289dB8184772b0B98562053559"
]
}
}
blockchain: ALL
limit: 200
order: { followerSince: DESC }
}
) {
Follower {
followerAddress {
addresses
domains {
name
}
socials {
dappName
profileName
profileTokenId
profileTokenIdHex
userId
userAssociatedAddresses
}
}
followerProfileId
followerTokenId
followingAddress {
addresses
domains {
name
}
socials {
dappName
profileName
profileTokenId
profileTokenIdHex
userId
userAssociatedAddresses
}
}
followingProfileId
}
}
}
{
"data": {
"SocialFollowers": {
"Follower": [
{
"followerAddress": {
"addresses": ["0x0d2ad52c9ce562bffecf2d4381e23e97f5ff5267"],
"domains": [],
"socials": [
{
"dappName": "farcaster",
"profileName": "alcueca",
"profileTokenId": "19805",
"profileTokenIdHex": "0x04d5d",
"userId": "19805",
"userAssociatedAddresses": [
"0x0d2ad52c9ce562bffecf2d4381e23e97f5ff5267"
]
}
]
},
"followerProfileId": "19805",
"followerTokenId": "",
"followingAddress": {
"addresses": [
"0x74232bf61e994655592747e20bdf6fa9b9476f79",
"0xb877f7bb52d28f06e60f557c00a56225124b357f",
"0xa14b4c95b5247199d74c5578531b4887ca5e4909",
"0xd7029bdea1c17493893aafe29aad69ef892b8ff2"
],
"domains": [
{
"name": "dwr.eth"
},
{
"name": "noun124.eth"
},
{
"name": "dwr.mirror.xyz"
},
{
"name": "danromero.eth"
}
],
"socials": [
{
"dappName": "lens",
"profileName": "lens/@danromero",
"profileTokenId": "46189",
"profileTokenIdHex": "0x0b46d",
"userId": "0xd7029bdea1c17493893aafe29aad69ef892b8ff2",
"userAssociatedAddresses": [
"0xd7029bdea1c17493893aafe29aad69ef892b8ff2"
]
},
{
"dappName": "farcaster",
"profileName": "dwr.eth",
"profileTokenId": "3",
"profileTokenIdHex": "0x03",
"userId": "3",
"userAssociatedAddresses": [
"0x74232bf61e994655592747e20bdf6fa9b9476f79",
"0xb877f7bb52d28f06e60f557c00a56225124b357f",
"0xa14b4c95b5247199d74c5578531b4887ca5e4909",
"0xd7029bdea1c17493893aafe29aad69ef892b8ff2"
]
}
]
},
"followingProfileId": "3"
}
// more followers
]
}
}
}
Get The Earliest Followers of User(s)
You can get the list of the earliest followers of user(s) by providing either 0x addresses, ENS names, Lens profiles, or Farcasters:
Try Demo
Code
query MyQuery {
SocialFollowers(
input: {
filter: {
identity: {
_in: [
"lens/@stani"
"lens_id:0x024"
"fc_fname:dwr.eth"
"fc_fid:3"
"vitalik.eth"
"0xeaf55242a90bb3289dB8184772b0B98562053559"
]
}
}
blockchain: ALL
limit: 200
order: { followerSince: ASC }
}
) {
Follower {
followerAddress {
addresses
domains {
name
}
socials {
dappName
profileName
profileTokenId
profileTokenIdHex
userId
userAssociatedAddresses
}
}
followerProfileId
followerTokenId
followingAddress {
addresses
domains {
name
}
socials {
dappName
profileName
profileTokenId
profileTokenIdHex
userId
userAssociatedAddresses
}
}
followingProfileId
}
}
}
{
"data": {
"SocialFollowers": {
"Follower": [
{
"followerAddress": {
"addresses": [
"0x8005a9309966eb88f5f63291e0fe56cc7fbc09b1",
"0x416e0c10a3760a35f1891455f30e415e96fbd779"
],
"domains": [
{
"name": "maxbranzburg.eth"
},
{
"name": "chriswolf.eth"
},
{
"name": "branzburg.eth"
}
],
"socials": [
{
"dappName": "farcaster",
"profileName": "max",
"profileTokenId": "23",
"profileTokenIdHex": "0x017",
"userId": "23",
"userAssociatedAddresses": [
"0x8005a9309966eb88f5f63291e0fe56cc7fbc09b1",
"0x416e0c10a3760a35f1891455f30e415e96fbd779"
]
}
]
},
"followerProfileId": "23",
"followerTokenId": "",
"followingAddress": {
"addresses": [
"0xb877f7bb52d28f06e60f557c00a56225124b357f",
"0xa14b4c95b5247199d74c5578531b4887ca5e4909",
"0xd7029bdea1c17493893aafe29aad69ef892b8ff2",
"0x74232bf61e994655592747e20bdf6fa9b9476f79"
],
"domains": [
{
"name": "dwr.eth"
},
{
"name": "noun124.eth"
},
{
"name": "dwr.mirror.xyz"
},
{
"name": "danromero.eth"
}
],
"socials": [
{
"dappName": "lens",
"profileName": "lens/@danromero",
"profileTokenId": "46189",
"profileTokenIdHex": "0x0b46d",
"userId": "0xd7029bdea1c17493893aafe29aad69ef892b8ff2",
"userAssociatedAddresses": [
"0xd7029bdea1c17493893aafe29aad69ef892b8ff2"
]
},
{
"dappName": "farcaster",
"profileName": "dwr.eth",
"profileTokenId": "3",
"profileTokenIdHex": "0x03",
"userId": "3",
"userAssociatedAddresses": [
"0xb877f7bb52d28f06e60f557c00a56225124b357f",
"0xa14b4c95b5247199d74c5578531b4887ca5e4909",
"0xd7029bdea1c17493893aafe29aad69ef892b8ff2",
"0x74232bf61e994655592747e20bdf6fa9b9476f79"
]
}
]
},
"followingProfileId": "3"
}
// more followers
]
}
}
}
Get All Followers of User(s) that has ENS Domain
You can get the list of all followers of user(s) and check if they have any ENS domain:
Try Demo
Code
query MyQuery {
SocialFollowers(
input: {filter: {identity: {_in: ["lens/@stani", "lens_id:0x024", "fc_fname:dwr.eth", "fc_fid:3", "vitalik.eth", "0xeaf55242a90bb3289dB8184772b0B98562053559"]}}, blockchain: ALL, limit: 200}
) {
Follower {
followerAddress {
addresses
domains { # Show all domains owned by followers
name
isPrimary
}
socials {
dappName
profileName
profileTokenId
profileTokenIdHex
userId
userAssociatedAddresses
}
}
followerProfileId
followerTokenId
followingAddress {
addresses
domains {
name
}
socials {
dappName
profileName
profileTokenId
profileTokenIdHex
userId
userAssociatedAddresses
}
}
followingProfileId
}
}
}
{
"data": {
"SocialFollowers": {
"Follower": [
{
"followerAddress": {
"addresses": [
"0xac7a709f09eac9769c567a24a858fe65b44850af",
"0x3a497a2a8b35b934bf271938502ca24e444e689e"
],
"domains": [
{
"name": "pfizergang.eth",
"isPrimary": true
}
],
"socials": [
{
"dappName": "lens",
"profileName": "lens/@pfizergang",
"profileTokenId": "66242",
"profileTokenIdHex": "0x0102c2",
"userId": "0x3a497a2a8b35b934bf271938502ca24e444e689e",
"userAssociatedAddresses": [
"0x3a497a2a8b35b934bf271938502ca24e444e689e"
]
},
{
"dappName": "farcaster",
"profileName": "pfizergang",
"profileTokenId": "16250",
"profileTokenIdHex": "0x03f7a",
"userId": "16250",
"userAssociatedAddresses": [
"0xac7a709f09eac9769c567a24a858fe65b44850af",
"0x3a497a2a8b35b934bf271938502ca24e444e689e"
]
}
]
},
"followerProfileId": "16250",
"followerTokenId": "",
"followingAddress": {
"addresses": [
"0x66bd69c7064d35d146ca78e6b186e57679fba249",
"0xeaf55242a90bb3289db8184772b0b98562053559"
],
"domains": [
{
"name": "jasongoldberg.eth"
},
{
"name": "betashop.eth"
}
],
"socials": [
{
"dappName": "farcaster",
"profileName": "betashop.eth",
"profileTokenId": "602",
"profileTokenIdHex": "0x025a",
"userId": "602",
"userAssociatedAddresses": [
"0x66bd69c7064d35d146ca78e6b186e57679fba249",
"0xeaf55242a90bb3289db8184772b0b98562053559"
]
},
{
"dappName": "lens",
"profileName": "lens/@betashop9",
"profileTokenId": "94472",
"profileTokenIdHex": "0x017108",
"userId": "0xeaf55242a90bb3289db8184772b0b98562053559",
"userAssociatedAddresses": [
"0xeaf55242a90bb3289db8184772b0b98562053559"
]
}
]
},
"followingProfileId": "602"
}
// more followers
]
}
}
}
You can use the followerAddress.domains
that will return an array to see if there's any domain owned by the follower.
If the length of the followerAddress.domains
array is non-zero, then the follower has at least one ENS domain. Otherwise, it does not have any ENS domain.
Get Users that have a certain amount of Followers
You can get the list of all users of that have a certain amount of followers, e.g. at least 1000 followers:
Try Demo
Code
query MyQuery {
Socials(
input: {
filter: { followerCount: { _gte: 1000 } }
blockchain: ethereum
limit: 200
}
) {
Social {
dappName
profileName
profileTokenId
profileTokenIdHex
userId
userAssociatedAddresses
followerCount
}
}
}
{
"data": {
"Socials": {
"Social": [
{
"dappName": "farcaster",
"profileName": "pfista",
"profileTokenId": "451",
"profileTokenIdHex": "0x01c3",