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 nowExample 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.
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.