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

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

Nested query - list of all followers on Farcaster or Lens

followingCount

Int

Total number of followings

followings

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.

isFarcasterPowerUser

Boolean

Whether a social profile is has a power badge or not.

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

Farcaster user's social capital score.

updatedAt

Time

Timestamp when the social profile was last updated.

userAddressDetails

Nested Queries – Wallet details of custody address from userAddress field.

userAssociatedAddressDetails

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)

Last updated

#946:

Change request updated