Launch Explorer API Studio

📞Recommendation Users

Learn how to get recommended followers for Farcaster users based on on-chain insights from token transfers, POAPs, NFTS, and token holder combinations.

Airstack provides easy-to-use APIs for enriching Farcaster applications and for integrating onchain and offchain data with 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

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.

🤖 AI Natural Language​

Airstack provides an AI solution for you to build GraphQL queries to fulfill your use case easily. You can find the AI prompt of each query in the demo's caption or title for yourself to try.

Get Recommendation Follows For Farcaster User(s) Based on Token Transfers

To get recommendations by token transfers, simply fetch all token transfers that is received and sent from the Farcaster user(s):

Try Demo

Code

query GetRecommendationsByTokenTransfers {
  # first query on Ethereum
  ethereum: TokenTransfers(
    input: {
      filter: {
        _or: {
          from: { _in: ["fc_fname:dwr", "fc_fid:5650"] }
          to: { _in: ["fc_fname:dwr", "fc_fid:5650"] }
        }
      }
      blockchain: ethereum
      limit: 50
    }
  ) {
    TokenTransfer {
      from {
        addresses
        socials(input: { filter: { dappName: { _in: farcaster } } }) {
          userId
          profileName
        }
      }
      to {
        addresses
        socials(input: { filter: { dappName: { _in: farcaster } } }) {
          userId
          profileName
        }
      }
    }
  }
  # second query on Polygon
  polygon: TokenTransfers(
    input: {
      filter: {
        _or: {
          from: { _in: ["fc_fname:dwr", "fc_fid:5650"] }
          to: { _in: ["fc_fname:dwr", "fc_fid:5650"] }
        }
      }
      blockchain: polygon
      limit: 50
    }
  ) {
    TokenTransfer {
      from {
        addresses
        socials(input: { filter: { dappName: { _in: farcaster } } }) {
          userId
          profileName
        }
        domains {
          dappName
        }
      }
      to {
        addresses
        socials(input: { filter: { dappName: { _in: farcaster } } }) {
          userId
          profileName
        }
      }
    }
  }
  # third query on Base
  base: TokenTransfers(
    input: {
      filter: {
        _or: {
          from: { _in: ["fc_fname:dwr", "fc_fid:5650"] }
          to: { _in: ["fc_fname:dwr", "fc_fid:5650"] }
        }
      }
      blockchain: base
      limit: 50
    }
  ) {
    TokenTransfer {
      from {
        addresses
        socials(input: { filter: { dappName: { _in: farcaster } } }) {
          userId
          profileName
        }
        domains {
          dappName
        }
      }
      to {
        addresses
        socials(input: { filter: { dappName: { _in: farcaster } } }) {
          userId
          profileName
        }
      }
    }
  }
}

Get Recommendation Follows For Farcaster User(s) Based on POAPs

To get recommendations by POAPs, first fetch all POAPs that is owned by the Farcaster user(s):

Try Demo

Code

query POAPsOwnedByFarcasterUser {
  Poaps(
    input: {
      filter: { owner: { _in: ["fc_fname:dwr.eth", "fc_fid:1"] } }
      blockchain: ALL
    }
  ) {
    Poap {
      eventId
      poapEvent {
        eventName
        eventURL
        startDate
        endDate
        country
        city
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
      }
    }
    pageInfo {
      nextCursor
      prevCursor
    }
  }
}

With the response, you can compile the eventIds as an array that can be forwarded as an input for the next query.

The next query for recommending follows based on POAPs will be fetching all the holders of the POAP with the eventIds in the array:

Try Demo

Logohttps://app.airstack.xyz/query/LTs9rbCXWJ
Show follow recommendations based on POAP event IDs 6584, 14498, and 6481

Code

query GetAllAddressesSocialsAndENSOfPOAP {
  Poaps(
    input: {
      filter: { eventId: { _in: ["6584", "14498", "6481"] } }
      blockchain: ALL
      limit: 10
    }
  ) {
    Poap {
      owner {
        identity
        socials(input: { filter: { dappName: { _eq: farcaster } } }) {
          profileName
          userId
        }
      }
    }
  }
}

The follow recommendation will provide a list of Farcaster users with the Farcaster user name from the profileName field and Farcaster user ID from the userId field.

Get Recommendation Follows For Farcaster User(s) Based on NFTs

To get recommendations by NFTs, first fetch all NFTs that is owned by the Farcaster user(s) on Ethereum, Polygon, and Base:

Try Demo

Code

query GetNFTs {
  ethereum: TokenBalances(
    input: {
      filter: {
        owner: { _in: ["fc_fname:varunsrin.eth", "fc_fid:5650"] }
        tokenType: { _in: [ERC1155, ERC721] }
      }
      blockchain: ethereum
      limit: 200
    }
  ) {
    TokenBalance {
      tokenAddress
    }
  }
  polygon: TokenBalances(
    input: {
      filter: {
        owner: { _in: ["fc_fname:varunsrin.eth", "fc_fid:5650"] }
        tokenType: { _in: [ERC1155, ERC721] }
      }
      blockchain: polygon
      limit: 200
    }
  ) {
    TokenBalance {
      tokenAddress
    }
  }
  base: TokenBalances(
    input: {
      filter: {
        owner: { _in: ["fc_fname:varunsrin.eth", "fc_fid:5650"] }
        tokenType: { _in: [ERC1155, ERC721] }
      }
      blockchain: base
      limit: 200
    }
  ) {
    TokenBalance {
      tokenAddress
    }
  }
}

With the response, you can compile the many tokenAddress as an array that can be forwarded as an input for the next query.

The next query for recommending follows based on NFTs will be fetching all the holders of the NFT with the eventIds in the array:

Try Demo

Code

query GetNFTHoldersAndImages {
  ethereum: TokenNfts(
    input: {
      filter: {
        address: {
          _in: [
            "0x00000000000061ad8ee190710508a818ae5325c3"
            "0x37fb80ef28008704288087831464058a4a3940ae"
            "0x5a3c077906abf9a46a9de87bb3c6d075a8a67851"
          ]
        }
      }
      blockchain: ethereum
    }
  ) {
    TokenNft {
      tokenBalances {
        owner {
          identity
          socials(input: { filter: { dappName: { _eq: farcaster } } }) {
            profileName
            userId
          }
        }
      }
    }
  }
  polygon: TokenNfts(
    input: {
      filter: {
        address: {
          _in: [
            "0xd18359edd97ff13609c1978452b05b43213222d7"
            "0x27562885f784616be44a0dc801ff18ed4551ba3d"
            "0x579720c63ed37fd4bd60a44fc27a25d6f169e95e"
          ]
        }
      }
      blockchain: polygon
    }
  ) {
    TokenNft {
      tokenBalances {
        owner {
          identity
          socials(input: { filter: { dappName: { _eq: farcaster } } }) {
            profileName
            userId
          }
        }
      }
    }
  }
  base: TokenNfts(
    input: {
      filter: {
        address: {
          _in: [
            "0xd18359edd97ff13609c1978452b05b43213222d7"
            "0x27562885f784616be44a0dc801ff18ed4551ba3d"
            "0x579720c63ed37fd4bd60a44fc27a25d6f169e95e"
          ]
        }
      }
      blockchain: base
    }
  ) {
    TokenNft {
      tokenBalances {
        owner {
          identity
          socials(input: { filter: { dappName: { _eq: farcaster } } }) {
            profileName
            userId
          }
        }
      }
    }
  }
}

The follow recommendation will provide a list of Farcaster users with the Farcaster user name from the profileName field and Farcaster user ID from the userId field.

Get Recommendation Follows For Farcaster User(s) Based on NFTs and POAPs Commonly Held

Fetching

You can fetch follow recommendations based on the common holder of a specific NFT and a specific POAP by providing the token contract address and the POAP event ID:

Try Demo

Code

query GetCommonHoldersOfNounsAndEthCC {
  TokenBalances(
    input: {filter: {tokenAddress: {_eq: "0x9c8ff314c9bc7f6e59a9d9225fb22946427edc03"}}, blockchain: ethereum, limit: 200}
  ) {
    TokenBalance {
      owner {
        poaps(input: {filter: {eventId: {_eq: "141910"}}}) {
          owner {
            socials(input: {filter: {dappName: {_eq: farcaster}}}) {
              profileName
              userId
              userAssociatedAddresses
            }
          }
        }
      }
    }
  }
}

All the common holders' Farcaster details will be returned inside the innermost owner.socials field.

Formatting

To get the list of all holders in a flat array, use the following format function:

const formatFunction = (data) =>
  data?.TokenBalances?.TokenBalance?.map(({ owner }) =>
    owner?.poaps?.map(({ owner }) => owner?.socials)
  )
    .filter(Boolean)
    .flat(2)
    .filter((social, index, array) => array.indexOf(social) === index) ?? [];

The final result will the the list of all common holders in an array:

[
  {
    "profileName": "worthalter",
    "userId": "9456",
    "userAssociatedAddresses": [
      "0xc19628f57a46389b0ac0fc113de273f91b07faca",
      "0xf6b6f07862a02c85628b3a9688beae07fea9c863"
    ]
  }
  // ...other token holders
]

Get Recommendation Follows For Farcaster User(s) Based on Farcaster Followers

Fetching

You can fetch follow recommendations for Farcaster user(s) by simply showing them all the Farcaster accounts that followed the given user(s):

Try Demo

Code

query MyQuery {
  SocialFollowers(
    input: {
      filter: {
        dappName: { _eq: farcaster }
        identity: { _in: ["fc_fname:dwr.eth"] }
      }
      blockchain: ALL
      limit: 200
    }
  ) {
    Follower {
      followerAddress {
        addresses
        socials(input: { filter: { dappName: { _eq: farcaster } } }) {
          profileName
          userId
          userAssociatedAddresses
        }
      }
      followingAddress {
        addresses
        domains {
          name
        }
        socials(input: { filter: { dappName: { _eq: farcaster } } }) {
          profileName
          userId
          userAssociatedAddresses
        }
      }
    }
  }
}

With the response, you can get all followerAddress.socials and compile them into an array of Farcaster accounts that you can recommend for the given user(s) to follow.

Get Recommendation Follows For Farcaster User(s) Based on Lens Following

Fetching

You can fetch follow recommendations for Farcaster user(s) by simply showing them all their Lens following and show their corresponding Farcaster accounts, if any:

Try Demo

Code

query MyQuery {
  SocialFollowings(
    input: {
      filter: {
        identity: { _in: ["fc_fname:dwr.eth"] }
        dappName: { _eq: lens }
      }
      blockchain: ALL
      limit: 200
    }
  ) {
    Following {
      followingAddress {
        addresses
        socials(input: { filter: { dappName: { _eq: farcaster } } }) {
          profileName
          userId
          userAssociatedAddresses
        }
      }
      followerAddress {
        addresses
        domains {
          name
        }
        socials(input: { filter: { dappName: { _eq: farcaster } } }) {
          profileName
          userId
          userAssociatedAddresses
        }
      }
    }
  }
}

All the Farcaster accounts that can be used for recommendation will be returned in followingAddress.socials.

Formatting

To get the list of all following in a flat array and filter out all those that don't have any Farcaster account, use the following format function:

/**
 * @description Formats the given data.
 * @example
 * // For React
 * const { data } = useQuery(query);
 * formatFunction(data);
 *
 * // For Node
 * const { data } = await fetchQuery(query);
 * formatFunction(data);
 *
 * @param {Object} data – data result from the Airstack API call
 * @returns – an array of Farcaster and their user details for recommendataion
 */
const formatFunction = (data) =>
  data?.SocialFollowings?.Following?.map(({ followingAddress }) =>
    followingAddress?.xmtp?.length ? followingAddress?.socials : null
  )
    .filter(Boolean)
    .flat(1)
    .filter((address, index, array) => array.indexOf(address) === index) ?? [];

The formatted data will have data structure that look as follows:

[
  {
    "profileName": "keeks",
    "userId": "3283",
    "userAssociatedAddresses": [
      "0xadc0b2321bb9779bf2a565c51456fa300517bed5",
      "0x66da63b03feca7dd44a5bb023bb3645d3252fa32"
    ]
  }
  // more recommended users
]

Developer Support

If you have any questions or need help regarding building a recommendation engine, please join our Airstack's Telegram group.

More Resources

PreviousTokens In CommonNextFarcaster Users Details

Last updated

Was this helpful?