1"use strict";(globalThis.webpackChunkv2_docs=globalThis.webpackChunkv2_docs||[]).push([[2549],{48190(e,n,r){r.r(n),r.d(n,{assets:()=>c,contentTitle:()=>d,default:()=>h,frontMatter:()=>l,metadata:()=>s,toc:()=>i});const s=JSON.parse('{"id":"schema/evm/token-holders","title":"EVM Token Holders API","description":"EVM Token Holders API: Bitquery EVM GraphQL schema reference with fields, filters, relationships, and query patterns. See examples in the Bitquery IDE.","source":"@site/docs/schema/evm/token-holders.md","sourceDirName":"schema/evm","slug":"/schema/evm/token-holders","permalink":"/docs/schema/evm/token-holders","draft":false,"unlisted":false,"editUrl":"https://github.com/bitquery/streaming-data-platform-docs/tree/main/docs/schema/evm/token-holders.md","tags":[],"version":"current","frontMatter":{"title":"EVM Token Holders API","description":"EVM Token Holders API: Bitquery EVM GraphQL schema reference with fields, filters, relationships, and query patterns. See examples in the Bitquery IDE."},"sidebar":"tutorialSidebar","previous":{"title":"Balances","permalink":"/docs/schema/evm/balances"},"next":{"title":"EVM Token Transfers API","permalink":"/docs/schema/evm/transfers"}}');var t=r(74848),o=r(28453);const l={title:"EVM Token Holders API",description:"EVM Token Holders API: Bitquery EVM GraphQL schema reference with fields, filters, relationships, and query patterns. See examples in the Bitquery IDE."},d="EVM Token Holders API",c={},i=[{value:"Token holder count",id:"token-holder-count",level:2},{value:"Filter parameters",id:"filter-parameters",level:3},{value:"Return fields",id:"return-fields",level:3},{value:"Examples on Ethereum",id:"examples-on-ethereum",level:3}];function a(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.header,{children:(0,t.jsx)(n.h1,{id:"evm-token-holders-api",children:"EVM Token Holders API"})}),"\n",(0,t.jsx)(n.admonition,{title:"Query-only",type:"caution",children:(0,t.jsxs)(n.p,{children:["A subscription on ",(0,t.jsx)(n.code,{children:"Holders"})," is accepted but never pushes a message. Poll it on a schedule, and\nstream ",(0,t.jsx)(n.code,{children:"Transfers"})," for the token to know when a refresh is worthwhile. See\n",(0,t.jsx)(n.a,{href:"/docs/subscriptions/which-cubes-stream/",children:"which cubes support subscriptions"}),"."]})}),"\n",(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.strong,{children:"Holders"})," API returns token holder data for ERC-20 tokens: top holders, holder counts, and balance thresholds. Non-zero balances use ",(0,t.jsx)(n.code,{children:'Amount(selectWhere: { gt: "0" })'})," on the ",(0,t.jsx)(n.code,{children:"Balance"})," field (not in ",(0,t.jsx)(n.code,{children:"where"}),"). Use ",(0,t.jsx)(n.code,{children:"dataset: combined"})," or ",(0,t.jsx)(n.code,{children:"dataset: archive"})," as follows:"]}),"\n",(0,t.jsxs)(n.table,{children:[(0,t.jsx)(n.thead,{children:(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.th,{children:"Dataset"}),(0,t.jsx)(n.th,{children:"When to use"})]})}),(0,t.jsxs)(n.tbody,{children:[(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.strong,{children:(0,t.jsx)(n.code,{children:"combined"})})}),(0,t.jsxs)(n.td,{children:["Latest holder count, top holders, and balances. Queries ",(0,t.jsx)(n.strong,{children:"realtime and archive"})," databases and merges results."]})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.strong,{children:(0,t.jsx)(n.code,{children:"archive"})})}),(0,t.jsx)(n.td,{children:"Addresses not recently active (not in the realtime window)."})]})]})]}),"\n",(0,t.jsxs)(n.p,{children:["Full Ethereum examples: ",(0,t.jsx)(n.a,{href:"/docs/blockchain/Ethereum/token-holders/token-holder-api",children:"Token Holders API"}),"."]}),"\n",(0,t.jsx)(n.h2,{id:"token-holder-count",children:"Token holder count"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-graphql",children:'query {\n EVM(network: eth, dataset: combined) {\n Holders(\n where: {\
1n Currency: {\n SmartContract: {\n is: "0x54D2252757e1672EEaD234D27B1270728fF90581"\n }\n }\n }\n ) {\n uniq(of: Holder_Address)\n }\n }\n}\n'})}),"\n",(0,t.jsx)(n.h3,{id:"filter-parameters",children:"Filter parameters"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"dataset: combined"})," \u2014 latest holder count, top holders, and activity"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"dataset: archive"})," \u2014 addresses not recently active"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"where.Currency.SmartContract"})," \u2014 token contract address (required)"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"where.Balance.LastChangeTime"})," \u2014 filter by last balance change (datetime, e.g. ",(0,t.jsx)(n.code,{children:'till: "2026-05-01T00:00:00Z"'}),"). The Holders cube does not support ",(0,t.jsx)(n.code,{children:"Block.Date"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"where.Holder.Address"})," \u2014 filter to a specific wallet"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:'Balance.Amount(selectWhere: { gt: "..." })'})," \u2014 non-zero balances when listing amounts"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:'uniq(of: Holder_Address, if: { Balance: { Amount: { gt: "..." } } } })'})," \u2014 holder count above a threshold"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"limit"}),", ",(0,t.jsx)(n.code,{children:"orderBy"})," \u2014 pagination and sorting (e.g. ",(0,t.jsx)(n.code,{children:"descending: Balance_Amount"}),")"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"return-fields",children:"Return fields"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"Holder.Address"})," \u2014 holder wallet address"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"Balance.Amount"}),", ",(0,t.jsx)(n.code,{children:"Balance.AmountInUSD"})," \u2014 token balance (use ",(0,t.jsx)(n.code,{children:"selectWhere"})," for non-zero)"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"Balance.UpdateCount"}),", ",(0,t.jsx)(n.code,{children:"Balance.FirstChangeTime"}),", ",(0,t.jsx)(n.code,{children:"Balance.LastChangeTime"})," \u2014 holder activity"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"examples-on-ethereum",children:"Examples on Ethereum"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"/docs/blockchain/Ethereum/token-holders/token-holder-api#top-holders-of-a-currency-current",children:"Top holders (current)"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"/docs/blockchain/Ethereum/token-holders/token-holder-api#token-holder-count-for-an-erc-20-token",children:"Token holder count"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"/docs/blockchain/Ethereum/token-holders/token-holder-api#holder-count-with-balance-above-a-threshold",children:"Holder count above a threshold"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"/docs/blockchain/Ethereum/token-holders/token-holder-api#track-whale-wallets-and-token-holdings",children:"Track whale wallets"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"/docs/blockchain/Ethereum/token-holders/token-holder-api#historical-top-holders-by-date",children:"Historical top holders"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"/docs/blockchain/Ethereum/token-holders/token-holder-api#token-holder-count-history-over-time",children:"Holder count history"})}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.a,{href:"/docs/blockchain/Ethereum/token-holders/token-holder-api#wallet-balance-at-a-point-in-time",children:"Wallet token balance at a date"})," (via ",(0,t.jsx)(n.a,{href:"/docs/blockchain/Ethereum/balances/balance-api/#wallet-balance-for-a-specific-token-on-a-date",children:"Balances API"}),")"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.a,{href:"/docs/blockchain/Ethereum/token-holders/token-holder-api#token-holder-activity",children:"Holder activity"})," \u2014 ",(0,t.jsx)(n.code,{children:"UpdateCount"}),", ",(0,t.jsx)(n.code,{children:"FirstChangeTime"}),", ",(0,t.jsx)(n.code,{children:"LastChangeTime"})]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(a,{...e})}):a(e)}},28453(e,n,r){r.d(n,{R:()=>l,x:()=>d});var s=r(96540);const t={},o=s.createContext(t);function l(e){const n=s.useContext(o);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:l(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.