Skip to main content

​
Query Token Holders

This page covers how to fetch token holder data from the DAO Café GraphQL API. Endpoint: https://dao.cafe/graphql

​
Understanding Token Holders

Token holders are addresses that hold governance tokens. Each holder record tracks:
  • Balance: The actual token balance (tokens owned)
  • Votes: The voting power (may differ from balance due to delegation)
An address can have votes > balance if they’ve received delegations, or votes < balance if they’ve delegated to someone else.

​
Get Token Holders by DAO

Fetch all token holders in a DAO, ordered by voting power. 
query GetDAOTokenHolders($daoId: String!) {
  tokenHolders(
    where: { daoId: $daoId }
    orderBy: "votes"
    orderDirection: "desc"
    limit: 100
  ) {
    items {
      holder
      balance
      votes
      updatedAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
Variables: 
{
  "daoId": "8453_0xd6d4933c668b2070b3bd44f7420224fcbdb87378"
}

​
Get Top Token Holders

Find the addresses with the highest token balances. 
query GetTopTokenHolders($daoId: String!) {
  tokenHolders(
    where: { daoId: $daoId }
    orderBy: "balance"
    orderDirection: "desc"
    limit: 20
  ) {
    items {
      holder
      balance
      votes
    }
  }
}

​
Get Token Holder by Address

Find a specific holder’s token balance and voting power in a DAO. 
query GetTokenHolder($id: String!) {
  tokenHolder(id: $id) {
    holder
    balance
    votes
    token
    updatedAt
    blockNumber
  }
}
The holder ID format is: chainId_tokenAddress_holderAddress (all lowercase). Example: 8453_0xb67b87d2f26928784f51a0e263a0f7a9a5efd833_0x983332bb0b689ed97907f658525d19f4d876d96c

​
Get Holdings by Address

Find all token holdings for a specific address across all DAOs. 
query GetHoldingsByAddress($holder: String!) {
  tokenHolders(where: { holder: $holder }) {
    items {
      daoId
      token
      balance
      votes
      dao {
        name
        tokenSymbol
        chainId
      }
    }
  }
}
This is useful for building portfolio views showing all DAO holdings for a wallet.

​
Get Holders with Delegations

Find holders who have received delegations (votes > balance). 
query GetDelegateHolders($daoId: String!) {
  tokenHolders(
    where: { daoId: $daoId }
    orderBy: "votes"
    orderDirection: "desc"
    limit: 50
  ) {
    items {
      holder
      balance
      votes
    }
  }
}
Filter results where votes > balance to identify addresses that have received voting power through delegation.

​
Token Holder Schema

FieldTypeDescription
idStringComposite ID: chainId_token_holder
daoIdStringReference to DAO (chainId_governor)
chainIdIntNetwork chain ID (8453 for Base, 11155111 for Sepolia)
tokenAddressGovernance token contract address
holderAddressToken holder address
balanceBigIntToken balance (in wei)
votesBigIntVoting power (in wei)
updatedAtBigIntLast update timestamp
blockNumberBigIntLast update block number

​
Example Response

{
  "data": {
    "tokenHolders": {
      "items": [
        {
          "id": "8453_0xb67b87..._0x11e97f37...",
          "holder": "0x11e97f37b15c54b7400ee647ab7795334bd518ce",
          "balance": "990000000000000000000000",
          "votes": "990000000000000000000000"
        },
        {
          "id": "8453_0xb67b87..._0x983332bb...",
          "holder": "0x983332bb0b689ed97907f658525d19f4d876d96c",
          "balance": "10000000000000000000000",
          "votes": "10000000000000000000000"
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": null
      }
    }
  }
}
Balance and votes are returned as strings representing wei (18 decimals). Divide by 10^18 for human-readable amounts.