Launch Explorer API Studio

💡Activate Kit for Farcaster Auth Kit

Airstack Activate Kit enables you to execute a series of API calls to activate Farcaster users after they connect with Farcaster Auth Kit.

Farcaster Auth Kit enables your users to login to your app with their Farcaster custody address. Airstack Activate Kit is the next immediate step.

With Airstack Activate you can immediately fetch all of the user's:

  • Registration details from Optimism and Hubs

  • Profile details including bio, profile image

  • Connected addresses

  • Following

  • Followers

  • Onchain activity (e.g. POAPs, NFTs, tokens)

  • Onchain graph

You can also use Airstack regex search to enable auto-complete search for Farcaster users in your app.

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 Farcaster User Details

You can fetch the Farcaster user details of a 0x address by using the Socials API and provide the 0x address to the identity filter input:

Try Demo

Logohttps://app.airstack.xyz/query/qnp0VuwM2K
Show me Farcaster user details of Farcaster profile owned by 0x182327170fC284cAaA5b1bC3e3878233f529D741

Code

query MyQuery {
  Socials(
    input: {
      filter: {
        identity: { _eq: "0x182327170fC284cAaA5b1bC3e3878233f529D741" }
        dappName: { _eq: farcaster }
      }
      blockchain: ethereum
      limit: 200
    }
  ) {
    Social {
      profileName
      fnames
      userId
      profileImage
      profileImageContentValue {
        image {
          medium
        }
      }
    }
  }
}

Get Farcaster User's Connected Addresses

You can fetch the Farcaster profile's connected addresses of a 0x address by using the Socials API and provide the 0x address to the identity filter input and all the connected addresses will be returned in the userAssociatedAddresses field:

Try Demo

Code

query MyQuery {
  Socials(
    input: {
      filter: {
        identity: { _eq: "0x182327170fC284cAaA5b1bC3e3878233f529D741" }
        dappName: { _eq: farcaster }
      }
      blockchain: ethereum
      limit: 200
    }
  ) {
    Social {
      userAssociatedAddresses
    }
  }
}

Get Farcaster User's Followers and Following Counts

You can fetch the Farcaster profile's connected addresses of a 0x address by using the Socials API and provide the 0x address to the identity filter input.

The number of people following and people followed by the given Farcaster profile will be returned in the followerCount and followingCount, respectively:

Try Demo

Code

query MyQuery {
  Socials(
    input: {
      filter: {
        identity: { _eq: "0x182327170fC284cAaA5b1bC3e3878233f529D741" }
        dappName: { _eq: farcaster }
      }
      blockchain: ethereum
      limit: 200
    }
  ) {
    Social {
      followerCount
      followingCount
    }
  }
}

Get Farcaster User's Followers

You can fetch all the users following 0x address on Farcaster by using the SocialFollowers API and provide the 0x address to the identity filter input:

Try Demo

Code

query MyQuery {
  SocialFollowers(
    input: {
      filter: {
        dappName: { _eq: farcaster }
        identity: { _eq: "0x182327170fC284cAaA5b1bC3e3878233f529D741" }
      }
      blockchain: ALL
      limit: 200
    }
  ) {
    Follower {
      followerAddress {
        addresses
        socials(input: { filter: { dappName: { _eq: farcaster } } }) {
          profileName
          userId
        }
      }
    }
  }
}

Get Farcaster User's Followings

You can fetch all the users being followed by 0x address on Farcaster by using the SocialFollowings API and provide the 0x address to the identity filter input:

Try Demo

Code

query MyQuery {
  SocialFollowings(
    input: {
      filter: {
        dappName: { _eq: farcaster }
        identity: { _eq: "0x182327170fC284cAaA5b1bC3e3878233f529D741" }
      }
      blockchain: ALL
      limit: 200
    }
  ) {
    Following {
      followingAddress {
        addresses
        socials(input: { filter: { dappName: { _eq: farcaster } } }) {
          profileName
          userId
        }
      }
    }
  }
}

Get All POAPs Attended By Farcaster User

You can fetch all POAPs owned by a Farcaster user using the Poaps API and providing the Farcaster user's address to the owner filter:

Try Demo

Code

query POAPsOwnedByFarcasterUser {
  Poaps(
    input: {
      filter: { owner: { _eq: "0xD7029BDEa1c17493893AAfE29AAD69EF892B8ff2" } }
      blockchain: ALL
      limit: 200
    }
  ) {
    Poap {
      eventId
      poapEvent {
        eventName
        eventURL
        startDate
        endDate
        country
        city
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
      }
    }
  }
}

Get All NFTs Hold By Farcaster User

You can fetch all NFTs owned by a Farcaster user using the TokenBalances API and providing the Farcaster user's address to the owner filter:

For fetching NFT balances data from multiple chains, check out Cross-Chain Queries.

Try Demo

Code

query NFTsOwnedByFarcasterUser {
  TokenBalances(
    input: {
      filter: {
        owner: { _eq: "0xD7029BDEa1c17493893AAfE29AAD69EF892B8ff2" }
        tokenType: { _in: [ERC1155, ERC721] }
      }
      blockchain: ethereum
      limit: 200
    }
  ) {
    TokenBalance {
      amount
      tokenAddress
      tokenId
      tokenType
      tokenNfts {
        contentValue {
          image {
            extraSmall
            small
            medium
            large
          }
        }
      }
    }
  }
}

Get All ERC20 Tokens Hold By Farcaster User

You can fetch all ERC20 tokens owned by a Farcaster user using the TokenBalances API and providing the Farcaster user's address to the owner filter:

For fetching ERC20 token balances data from multiple chains, check out Cross-Chain Queries.

Try Demo

Code

query ERC20sOwnedByFarcasterUser {
  TokenBalances(
    input: {
      filter: {
        # Farcaster user's address
        owner: { _eq: "0xD7029BDEa1c17493893AAfE29AAD69EF892B8ff2" }
        tokenType: { _eq: ERC20 }
      }
      blockchain: ethereum
      limit: 200
    }
  ) {
    TokenBalance {
      amount
      tokenAddress
      token {
        name
        symbol
      }
    }
  }
}

Get Historical NFT Balance of Farcaster User

You can fetch Farcaster user's historical NFT balances and their time series data at a specified time by using Snapshots API and providing the given Farcaster user's 0x address to the owner input and specifying tokenType with the token type ERC721 and ERC1155:

For fetching historical NFT balances data from multiple chains, check out Cross-Chain Queries.

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        owner: {
          _eq: "0xD7029BDEa1c17493893AAfE29AAD69EF892B8ff2"
        },
        date: {_eq: "2023-08-18"} # Specifying date to Aug 18, 2023
        tokenType: {_in: [ERC721, ERC1155]}
      },
      blockchain: ethereum,
      limit: 200
    }
  ) {
    Snapshot {
      tokenAddress
      tokenId
      tokenType
      token {
        name
        symbol
        isSpam
      }
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
  }
}

Get Historical ERC20 Token Balance of Farcaster User

You can fetch Farcaster user's historical ERC20 token balances and their time series data at a specified time by using Snapshots API and providing the given Farcaster user's 0x address to the owner input and specifying tokenType with the token type ERC20:

For fetching historical ERC20 token balances data from multiple chains, check out Cross-Chain Queries.

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        owner: {
          _eq: "0xD7029BDEa1c17493893AAfE29AAD69EF892B8ff2"
        },
        date: {_eq: "2023-08-18"} # Specifying date to Aug 18, 2023
        tokenType: {_in: [ERC20]}
      },
      blockchain: ethereum,
      limit: 200
    }
  ) {
    Snapshot {
      tokenAddress
      token {
        name
        symbol
        isSpam
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
  }
}

Get NFT Mints By A Farcaster User

You can fetch all NFTs minted by a Farcaster user across multiple chains, such as Ethereum, Base, Degen Chain, and other Airstack-supported chains, by using the TokenTransfers API:

For fetching NFT mints data from multiple chains, check out Cross-Chain Queries.

Try Demo

Code

query MyQuery {
  TokenTransfers(
    input: {
      filter: {
        # Only get mints that are executed by the same Farcaster user
        operator: {_eq: "0xeaf55242a90bb3289dB8184772b0B98562053559"},
        # Mints are token transfers that has null address as `from`
        from: {_eq: "0x0000000000000000000000000000000000000000"},
        # Set this to the Farcaster user that receive the token mints
        to: {_eq: "0xeaf55242a90bb3289dB8184772b0B98562053559"},
        # Get only NFTs (ERC721/1155)
        tokenType: {_in: [ERC721, ERC1155]},
      },
      blockchain: ethereum,
      order: {blockTimestamp: DESC}
    }
  ) {
    TokenTransfer {
      blockchain
      formattedAmount
      tokenAddress
      tokenId
      tokenNft {
        metaData {
          name
        }
        contentValue {
          image {
            medium
          }
        }
      }
      tokenType
    }
  }
}

Get ERC20 Token Mints By A Farcaster User

You can fetch all ERC20 tokens minted by a Farcaster user across multiple chains, such as Ethereum, Base, Degen Chain, and other Airstack-supported chains, by using the TokenTransfers API:

For fetching ERC20 mints data from multiple chains, check out Cross-Chain Queries.

Try Demo

Code

query MyQuery {
  TokenTransfers(
    input: {
      filter: {
        # Only get mints that are executed by the same Farcaster user
        operator: {_eq: "0xB59Aa5Bb9270d44be3fA9b6D67520a2d28CF80AB"},
        # Mints are token transfers that has null address as `from`
        from: {_eq: "0x0000000000000000000000000000000000000000"},
        # Set this to the Farcaster user that receive the token mints
        to: {_eq: "0xB59Aa5Bb9270d44be3fA9b6D67520a2d28CF80AB"},
        # Get only ERC20 tokens
        tokenType: {_eq: ERC20},
      },
      blockchain: polygon,
      order: {blockTimestamp: DESC}
    }
  ) {
    TokenTransfer {
      blockchain
      formattedAmount
      tokenAddress
      token {
        name
      }
    }
  }
}

Get Token Transfers Sent From A Farcaster User

You can fetch all token transfers sent by a given Farcaster user across multiple chains, such as Ethereum, Base, Degen Chain, and other Airstack-supported chains, by using the TokenTransfers API:

For fetching token transfers data sent from a Farcaster user from multiple chains, check out Cross-Chain Queries.

Try Demo

Code

query GetTokenTransfers {
  TokenTransfers(
    input: {
      filter: {
        # Only get token transfers from 0xeaf55242a90bb3289dB8184772b0B98562053559
        from: {_eq: "0xeaf55242a90bb3289dB8184772b0B98562053559"},
        # Only get token transfers with non-zero amount
        formattedAmount: {_gt: 0},
        # Remove all minting/burning + self-transfer
        _nor: {
          from: {
            _in: [
              "0x0000000000000000000000000000000000000000",
              "0x000000000000000000000000000000000000dEaD"
            ]
          },
          to: {
            _in: [
              "0x0000000000000000000000000000000000000000",
              "0x000000000000000000000000000000000000dEaD",
              "0xeaf55242a90bb3289dB8184772b0B98562053559"
            ]
          }
        }
      },
      blockchain: ethereum,
      limit: 50
    }
  ) {
    TokenTransfer {
      formattedAmount
      tokenType
      token {
        name
      }
    }
  }
}

Get Token Transfers Received By A Farcaster User

You can fetch all token transfers received by a given Farcaster user across multiple chains, such as Ethereum, Base, Degen Chain, and other Airstack-supported chains, by using the TokenTransfers API:

For fetching token transfers data received by a Farcaster user from multiple chains, check out Cross-Chain Queries.

Try Demo

Code

query GetTokenTransfers {
  TokenTransfers(
    input: {
      filter: {
        # Only get token transfers to 0xeaf55242a90bb3289dB8184772b0B98562053559
        to: {_eq: "0xeaf55242a90bb3289dB8184772b0B98562053559"},
        # Only get token transfers with non-zero amount
        formattedAmount: {_gt: 0},
        # Remove all minting/burning + self-transfer
        _nor: {
          from: {
            _in: [
              "0x0000000000000000000000000000000000000000",
              "0x000000000000000000000000000000000000dEaD",
              "0xeaf55242a90bb3289dB8184772b0B98562053559"
            ]
          },
          to: {
            _in: [
              "0x0000000000000000000000000000000000000000",
              "0x000000000000000000000000000000000000dEaD"
            ]
          }
        }
      },
      blockchain: ethereum,
      limit: 50
    }
  ) {
    TokenTransfer {
      formattedAmount
      tokenType
      token {
        name
      }
    }
  }
}

Get All Farcaster Users Whose Names Start With Certain Terms (auto-complete)

You can fetch all Farcaster users that starts with given words by providing the regex pattern "^<given-words>" to the _regex operator in Socials API:

Try Demo

Code

query MyQuery {
  Socials(
    input: {
      filter: {
        # This regex pattern will search all Farcaster users
        # starting with "a"
        profileName: {_regex: "^a"},
        dappName: {_eq: farcaster}
      },
      blockchain: ethereum
    }
  ) {
    Social {
      dappName
      profileName
    }
  }
}

Get All Farcaster Users Whose Names Contain Certain Terms (auto-complete)

You can fetch all Farcaster users that contains given words by providing "<given-words>" directly to the _regex operator in Socials API:

Try Demo

Code

query MyQuery {
  Socials(
    input: {
      filter: {
        # This regex pattern will search all Farcaster users
        # containing "abc"
        profileName: {_regex: "abc"},
        dappName: {_eq: farcaster}
      },
      blockchain: ethereum
    }
  ) {
    Social {
      dappName
      profileName
    }
  }
}

Next Steps

To further enrich and improve the user experience for your Farcaster application, you can use Airstack to fetch a user's onchain contacts, which will provide all the users that have onchain connection to you, e.g. Farcaster followers/following, attended the same POAP events, holder of the same token, etc.

To learn more how to build this into your application, check out Onchain Graph and Onchain Contacts.

Developer Support

If you have any questions or need help regarding the activate kit for Farcaster Auth Kit, please join our Airstack's Telegram group.

More Resources

PreviousTrending MintsNextGet Token Balances

Last updated

Was this helpful?