Socials API

Learn all the detailed references of Socials API that provide a given user's web3 social information, including the input filters, supported chains, and output fields.

The Socials APIs deliver on-chain and off-chain user-level data pertaining to users of web3 social protocols such as Farcaster, and Lens.

Inputs

filter

Name	Type	Description
dappName	SocialDappName_Comparator_Exp	Social DApp name – lens, farcaster
dappSlug	SocialDappSlug_Comparator_Exp	Social DApp slug (contract version) – lens_polygon, lens_v2_polygon, farcaster_optimism, farcaster_goerli
followerCount	Int_Comparator_Exp	Total number of followers
followingCount	Int_Comparator_Exp	Total number of followings
identity	Identity_Comparator_Exp	Identity: blockchain address, domain name, social identity
isDefault	Boolean_Comparator_Exp	True/false if the profile is set to default on the corresponding dApp
profileName	String_Comparator_Exp	Profile name on the social app (prefix not required)
socialCapitalRank	Int_Comparator_Exp	Filter by social capital rank of a user.
socialCapitalScore	Float_Comparator_Exp	Filter by social capital score of a user.
updatedAt	Time_Comparator_Exp	Last timestamp when Lens/Farcaster profile was updated
userAssociatedAddresses	Address_Comparator_Exp	Any associated Wallet address
userId	String_Comparator_Exp	user ID on the social app (prefix not required)
profileCreatedAtBlockTimestamp	Time_Comparator_Exp	block timestamp when Lens/Farcaster profile was created

blockchain

For Socials API, it will return Lens & Farcaster data from all onchain and offchain sources, not specifically Ethereum.

You just need to specify the input for the query to work.

Enum	Description
ethereum	Ethereum mainnet

order

Name	Description
farRank	Sort by Farcaster profile's farrank.
farScore	Sort by Farcaster profile's farcaster score.
followerCount	Sort by the number of users following the Lens/Farcaster profile on Lens/Farcaster in ascending or descending order.
followingCount	Sort by the number of users being followed by the Lens/Farcaster profile on Lens/Farcaster in ascending or descending order.
profileCreatedAtBlockTimestamp	Sort by Lens/Farcaster profile creation block timestamp in ascending or descending order.
socialCapitalRank	Sort by Farcaster profile's social capital rank.
socialCapitalScore	Sort by Farcaster profile's social capital score.
updatedAt	Sort by Lens/Farcaster profile last update timestamp in ascending or descending order.

Outputs

Name	Type	Description
blockchain	Blockchain	Blockchain associated with the social identity
chainId	String	Unique identifier for the blockchain
dappName	SocialDappName	Either farcaster or lens
dappSlug	SocialDappSlug	Social DApp slug (contract version) with these values: farcaster_optimism, farcaster_goerli, lens_polygon, farcaster_v2_optimism, lens_v2_polygon
dappVersion	String	Airstack unique dapp version number
farcasterScore	FarcasterScore	The Farcaster score and rank details associated with the Farcaster user. This value will not be assigned for Lens accounts.
fnames	[String]	Farcaster names of a user, there could be more than one
followerCount	Int	Total number of followers
followerTokenAddress	Address
followers	SocialFollowers	Nested query - list of all followers on Farcaster or Lens
followingCount	Int	Total number of followings
followings	SocialFollowings	Nested query – list of all followings on Farcaster or Lens
id	ID	Airstack unique identifier for the data point
identity	Identity	Blockchain address, ENS domain name, social identity such as Farcaster (for Farcaster use 'fc_fid:' prefix followed by the Farcaster user ID like fc_fid:5650, or use 'fc_fname:' prefix followed by the Farcaster user ID like 'fc_fname:vbuterin') or Lens (e.g. 'stani.lens)
isDefault	Boolean	Whether a social profile is default/primary or not, only apply to Lens, Farcaster always false.
profileCreatedAtBlockNumber	Int	Block number when the social profile was created.
profileCreatedAtBlockTimestamp	Time	Timestamp when the social profile was created.
profileLastUpdatedAtBlockNumber	Int	Block number when the social profile was last updated.
profileLastUpdatedAtBlockTimestamp	Time	Timestamp when the social profile was last updated.
profileBio	String	Social profile bio on Farcaster or Lens.
profileDisplayName	String	Social profile display name on Farcaster or Lens.
profileImage	String	Link to Social profile image.
profileUrl	String	Social profile URL.
profileName	String	Farcaster profile name (fname primarily used) or Lens profile name (e.g. lens/@betashop9)
profileTokenAddress	Address	For Farcaster, it is going to return the IdRegistry contract address on Optimism. For Lens, it will return Lens profile NFT contract address on Polygon.
profileTokenId	String	For Farcaster, it's the user's FID. For Lens, it's the user's profile NFT's token ID.
profileTokenIdHex	String	Return the hex value of profileTokenId
profileTokenUri	String	Token URI of Lens Profile NFT. For Farcaster, this will return empty string.
socialCapital	SocialCapital	Farcaster user's social capital score.
updatedAt	Time	Timestamp when the social profile was last updated.
userAddressDetails	Wallet	Nested Queries – Wallet details of custody address from userAddress field.
userAssociatedAddressDetails	[Wallet!]	Nested Queries – Wallet details of all associated addresses from userAssociatedAddresses field.
userAddress	Address	User's custody address.
userAssociatedAddresses	[Address!]	All addresses associated with the social profiles. For Farcaster, it will return both the custody and connected addresses. If you are only fetching connected addresses, use connectedAddresses field instead.
userCreatedAtBlockNumber	Int	Block number when the social profile was created.
userCreatedAtBlockTimestamp	Number	Timestamp when the social profile was created.
userHomeURL	String	Social Profile Home URL.
userId	String	For Farcaster, it's the user's FID. For Lens, it's the user's profile NFT's token ID.
userLastUpdatedAtBlockNumber	Int	Block number when the social profile was last updated.
userLastUpdatedAtBlockTimestamp	Number	Timestamp when the social profile was last updated.
userRecoveryAddress	Address	Farcaster user's recovery address. For Lens, it will return empty string.
handleTokenAddress	Address	Lens Handle NFT contract address. For Farcaster, this will return an empty string.
handleTokenId	String	Lens Handle NFT token ID associated with the profile. For Farcaster, this will return an empty string.
metadataURI	String	Lens profile NFT metadata URI. This will return null for Farcaster profiles.
profileMetadata	Map	Lens profile NFT metadata. This will return null for Farcaster profiles.
coverImageURI	String	URI to the cover image of a social profile.
twitterUserName	String	Social profile's twitter (from Lens).
website	String	Social profile's website.
location	String	Social profile's location.
profileImageContentValue	Media	Nested Query – resized profile images.
coverImageContentValue	Media	Nested Query – resized cover images.
profileHandle	String	For Farcaster, this is equivalent to profileName. For Lens, it just display the Lens handle (e.g. @betashop9)