Farcaster Token Holders

Get farcaster users holding a specified token. Optionally return users that are followed by the specified Farcaster FID.

To get farcaster agnostic token holders, see token holders documentation.

farcasterHolders

Use farcasterHolders to get the top farcaster holders of a token.

Try it now

Example Variables

{
  "address": "0x9cb41fd9dc6891bae8187029461bfaadf6cc0c69",
  "chainId": 8453,
  "first": 12
}

Example Query

query FungibleTokenV2($address: Address!, $chainId: Int!, $first: Int!) {
  fungibleTokenV2(address: $address, chainId: $chainId) {
    farcasterHolders(first: $first) {
      totalCount
      pageInfo {
        hasPreviousPage
        hasNextPage
        startCursor
        endCursor
      }
      edges {
        node {
          account {
            farcasterProfile {
              username
            }
          }
          holderAddress
          percentileShare
        }
      }
    }
  }
}

Example Response

{
  "data": {
    "fungibleTokenV2": {
      "farcasterHolders": {
        "totalCount": 23990,
        "pageInfo": {
          "hasPreviousPage": false,
          "hasNextPage": true,
          "startCursor": "Mzc3OjA6MTY3NDczNDk0MzMxNzc1MjI5MTkzMDkxODUwNg==",
          "endCursor": "NDQ0MDY3OjA6MTM1MjM4MDQ0NjAyNTA0NDk5MDQwMTg2NjA4"
        },
        "edges": [
          {
            "node": {
              "account": {
                "farcasterProfile": {
                  "username": "srijan.eth"
                }
              },
              "holderAddress": "0x950615b7fdffb113ba53801ea6129ae7e372558e",
              "percentileShare": 1.6747349433177523
            }
          },
          {
            "node": {
              "account": {
                "farcasterProfile": {
                  "username": "krw"
                }
              },
              "holderAddress": "0x74fd379a494ba1e5396130693118a6a5ac522812",
              "percentileShare": 1.0199703737710355
            }
          },
          {
            "node": {
              "account": {
                "farcasterProfile": {
                  "username": "cryptomaniac09"
                }
              },
              "holderAddress": "0x564b3a3cf630d7b3b35ae78e47feb074bce2b06e",
              "percentileShare": 0.4723984698675472
            }
          },
          {
            "node": {
              "account": {
                "farcasterProfile": {
                  "username": "kien"
                }
              },
              "holderAddress": "0x65495c757f41296ae6a232808bc21ff5c5202809",
              "percentileShare": 0.27786702721736345
            }
          }
        ]
      }
    }
  }
}

followedFarcasterHolders

Use followedFarcasterHolders to find token holders within a Farcaster user's social graph.

Try it now

Example Variables

{
  "chainId": 8453,
  "address": "0x9cb41fd9dc6891bae8187029461bfaadf6cc0c69",
  "fid": 954583,
  "first": 10, // Optional: number of results to return
  "after": null // Optional: cursor for pagination
}

Example Query

query FollowedFarcasterHolders($chainId: Int!, $address: Address!, $fid: Int!, $first: Int!, $after: String) {
  fungibleTokenV2(chainId: $chainId, address: $address) {
    followedFarcasterHolders(fid: $fid, first: $first, after: $after) {
      totalCount
      pageInfo {
        hasPreviousPage
        hasNextPage
        startCursor
        endCursor
      }
      edges {
        node {
          holderAddress
          percentileShare
          account {
            displayName {
              value
            }
            farcasterProfile {
              username
              fid
            }
          }
        }
      }
    }
  }
}

Example Response

{
  "data": {
    "fungibleTokenV2": {
      "followedFarcasterHolders": {
        "totalCount": 27,
        "pageInfo": {
          "hasPreviousPage": false,
          "hasNextPage": true,
          "startCursor": "OTk6MDoxMjgyMzEyOTUzNTU1MTc0NjQxNzg2NDIzMw==",
          "endCursor": "MTI6MDo5NTIwMTU1NzA2MDQwNjI2OTcwODA1MzM="
        },
        "edges": [
          {
            "node": {
              "holderAddress": "0x85c0ba9e1456bc755a6ce69e1a85ccaa1faa9e41",
              "percentileShare": 0.012823129535551746,
              "account": {
                "displayName": {
                  "value": "0x85c0...9e41"
                },
                "farcasterProfile": {
                  "username": "jesse.base.eth",
                  "fid": 99
                }
              }
            }
          },
          {
            "node": {
              "holderAddress": "0xdb3ec7b16fd60fb4fdb58a438bd8af57d8d3a91c",
              "percentileShare": 0.001002015991382736,
              "account": {
                "displayName": {
                  "value": "agrimony.eth"
                },
                "farcasterProfile": {
                  "username": "agrimony.eth",
                  "fid": 191780
                }
              }
            }
          },
          {
            "node": {
              "holderAddress": "0x54d06a08ffdf44258a9f9bd2f4b4cdd6692a900f",
              "percentileShare": 0.000952015570604063,
              "account": {
                "displayName": {
                  "value": "0x54d0...900f"
                },
                "farcasterProfile": {
                  "username": "linda",
                  "fid": 12
                }
              }
            }
          }
        ]
      }
    }
  }
}

Available Fields

Required Parameters

Field	Description	Type
chainId	Blockchain network ID	Int!
address	Token contract address	Address!
fid	Farcaster ID to query social graph from	Int!

Optional Parameters

Field	Description	Type
first	Number of results to return	Int
after	Cursor for pagination	String

Response Fields

PaginatedSupportedTokenHolders

Field	Description	Type
totalCount	Total number of followed holders	Int!
pageInfo	Pagination information	PageInfo!
edges	Array of holder edges	[SupportedTokenHolderEdge!]!

SupportedTokenHolder

Field	Description	Type
holderAddress	Ethereum address of the token holder	String!
percentileShare	Holder's percentile rank among all holders	Float!
account	Account information and social profiles	Account!

Account

The account field contains detailed profile information including display names, avatars, social links, ENS records, and Farcaster profiles. For complete Account field documentation, see Onchain Identity.