What if you could get top holders, accurate supply distribution data, acquisition insights, and much more for any token with just one line of code? Enter Moralis Token Holder API, the ultimate tool for anyone looking to fetch and integrate crypto holder data into Web3 projects. Eager to learn more about this top-tier API? Join us in today’s guide as we show you exactly how it works. Let’s go!
If you want to jump straight into the code, check out the Token Holders endpoint in action right here:
import fetch from "node-fetch";
const options = {
method: "GET",
headers: {
accept: "application/json",
"X-API-Key": "YOUR_API_KEY",
},
};
fetch(
"https://deep-index.moralis.io/api/v2.2/erc20/0x6982508145454ce325ddbe47a25d4ec3d2311933/owners?chain=eth&order=DESC",
options
)
.then((response) => response.json())
.then((response) => console.log(response))
.catch((err) => console.error(err));
Calling the endpoint above will give you a list of the specified token’s top holders. Moreover, the response is enriched with address labels, logos, supply percentages, and more, minimizing the calls needed to build complex features:
{
//...
"result": (
{
balance: '6196351909968209613047652223963',
balance_formatted: '6196351909968.209613047652223963',
is_contract: false,
owner_address: '0xf89d7b9c864f589bbf53a82105107622b35eaa40',
owner_address_label: 'Bybit: Hot Wallet',
entity: 'Bybit',
entity_logo: 'https://entities-logos.s3.us-east-1.amazonaws.com/bybit.png',
usd_value: '42105073.909894451498985291',
percentage_relative_to_total_supply: 1.472902466893352
},
//...
)
}
The Token Holders endpoint only scratches the surface of the Token Holder API. To learn more, follow along as we show you how to easily fetch any token’s supply distribution, acquisition data, and much more.
Want to try out the Token Holder API yourself immediately? Sign up for a free Moralis account today!
Overview
Adding token holder data can significantly boost your platform’s value. Exposing wallet distribution insights, top holders, acquisition data, and more enables users to better gauge market sentiment, identify concentration risks, catch potential scams, and spot whale movements. And this added transparency can improve decision-making for both crypto traders and investors. As such, whether you’re building a DEX tracker, portfolio tool, or analytics dashboard, token holder insights can set your product apart.
But what is the best and easiest way to add token holder data to your Web3 projects?
If you’re looking for the answer to this question, join us down below as we kick things off by introducing you to the industry’s leading crypto data provider: Moralis!
Introducing Moralis for Developers: The Industry’s Leading Crypto Data Provider
Moralis for Developers is the industry’s #1 crypto data provider. In our suite of Web3 development tools, you’ll find top-tier APIs and next-generation RPC nodes designed to streamline reliable data integration into your projects. Consequently, when using Moralis, you can build decentralized applications (dapps) faster and more efficiently!
But what makes Moralis the #1 crypto data provider?
- Comprehensive APIs: Moralis APIs are built with the outcome in mind, giving you more data with fewer calls. Get comprehensive token holder data, a wallet’s full transaction history, in-depth portfolio data, and much more with just single requests.
- Cross-Chain Compatibility: Experience full feature parity across all major chains, including Solana, Ethereum, BNB Smart Chain (BSC), Base, Optimism, and many more networks. Use one set of tools to build across the entire Web3 ecosystem.
- Enterprise-Grade Reliability & Security: Moralis is SOC 2 Type 2 certified, highlighting our commitment to maintaining world-class reliability and security across all tools and features.
With an overview of Moralis, let’s dive into the industry’s leading Token Holder API!
Exploring the Best Token Holder API
Moralis Token Holder API is the ultimate tool for fetching and integrating holder data into your Web3 projects. You can use this premier API to get everything from top holders to acquisition data – all with single lines of code!
The Token Holder API features three key endpoints:
- Token Holders: Query all major holders of a token and their ownership percentage.
- Token Holder Stats: Get a list of token holder stats, including the holder count, acquisition data, supply distribution insights, and more.
- Token Holders Timeseries: Fetch historical holder statistics for any token over a set time period.
Nonetheless, let’s explore these three endpoints further in separate sections!
Token Holders
With the Token Holders endpoint, you can query a list of all major holders of a token. Simply pass along an address and chain parameter and call the endpoint. Here’s an example of what it looks like:
import fetch from "node-fetch";
const options = {
method: "GET",
headers: {
accept: "application/json",
"X-API-Key": "YOUR_API_KEY",
},
};
fetch(
"https://deep-index.moralis.io/api/v2.2/erc20/0x6982508145454ce325ddbe47a25d4ec3d2311933/owners?chain=eth&order=DESC",
options
)
.then((response) => response.json())
.then((response) => console.log(response))
.catch((err) => console.error(err));
In return for calling the endpoint, you get a list of holders for the specified token. Additionally, each item in the array is enriched with logos, address labels, and much more. Here’s a sample response:
{
//...
"result": (
{
balance: '6196351909968209613047652223963',
balance_formatted: '6196351909968.209613047652223963',
is_contract: false,
owner_address: '0xf89d7b9c864f589bbf53a82105107622b35eaa40',
owner_address_label: 'Bybit: Hot Wallet',
entity: 'Bybit',
entity_logo: 'https://entities-logos.s3.us-east-1.amazonaws.com/bybit.png',
usd_value: '42105073.909894451498985291',
percentage_relative_to_total_supply: 1.472902466893352
},
//...
)
}
Token Holder Stats
The Token Holder Stats endpoint returns a holder summary for the specified token. To call it, simply pass along an address and chain parameter. Here’s what it can look like:
import fetch from "node-fetch";
const options = {
method: "GET",
headers: {
accept: "application/json",
"X-API-Key": "YOUR_API_KEY",
},
};
fetch(
"https://deep-index.moralis.io/api/v2.2/erc20/0x6982508145454ce325ddbe47a25d4ec3d2311933/holders?chain=eth",
options
)
.then((response) => response.json())
.then((response) => console.log(response))
.catch((err) => console.error(err));
Calling this endpoint returns the total holder count, acquisition metrics, distribution insights, and holder changes over time. Here’s an example response:
{
totalHolders: 421342,
holdersByAcquisition: { swap: 122795, transfer: 282993, airdrop: 15554 },
holderChange: {
'5min': { change: 2, changePercent: 0.00047 },
'1h': { change: 18, changePercent: 0.0043 },
'6h': { change: 98, changePercent: 0.023 },
'24h': { change: 356, changePercent: 0.084 },
'3d': { change: 1156, changePercent: 0.27 },
'7d': { change: 2122, changePercent: 0.5 },
'30d': { change: 9819, changePercent: 2.3 }
},
holderSupply: {
top10: { supply: '164783457390612.77', supplyPercent: 39 },
top25: { supply: '226647944524114.14', supplyPercent: 54 },
top50: { supply: '273001677904297.12', supplyPercent: 65 },
top100: { supply: '307354487723478.82', supplyPercent: 73 },
top250: { supply: '344156607227442.39', supplyPercent: 82 },
top500: { supply: '362561870786335.94', supplyPercent: 86 }
},
holderDistribution: {
whales: 106,
sharks: 77,
dolphins: 634,
fish: 2130,
octopus: 6136,
crab: 22071,
shrimps: 390188
}
}
Token Holders Timeseries
With the Token Holders Timeseries endpoint, you can query an array of historical holder statistics within a specific timeframe. To call this endpoint, you must pass along a chain, address, toDate, fromDate, and timeFrame parameter. This is an example of what it can look like:
import fetch from "node-fetch";
const options = {
method: "GET",
headers: {
accept: "application/json",
"X-API-Key": "YOUR_API_KEY",
},
};
fetch(
"https://deep-index.moralis.io/api/v2.2/erc20/0x2260fac5e5542a773aa44fbcfedf7c193bc2c599/holders/historical?chain=eth&fromDate=2025-01-01T10%3A00%3A00&toDate=2025-02-01T11%3A00%3A00&timeFrame=1d",
options
)
.then((response) => response.json())
.then((response) => console.log(response))
.catch((err) => console.error(err));
Calling the endpoint above will give you an array of timestamps with the holder count, the net change in holder count, acquisition data, and much more. Here’s a sample response:
{
//...
"result": (
{
"timestamp": "2025-02-01T00:00:00.000Z",
"totalHolders": 113624,
"netHolderChange": 1474,
"holderPercentChange": 1.3,
"newHoldersByAcquisition": {
"swap": 531,
"transfer": 2052,
"airdrop": 6
},
"holdersIn": {
"whales": 0,
"sharks": 0,
"dolphins": 0,
"fish": 0,
"octopus": 5,
"crab": 23,
"shrimps": 2561
},
"holdersOut": {
"whales": 0,
"sharks": 0,
"dolphins": 0,
"fish": 0,
"octopus": 7,
"crab": 22,
"shrimps": 1086
}
},
//...
)
}
To learn more about these endpoints, please check out the Token API documentation page!
Full Tutorial: How to Get Crypto Holder Data with the Token Holder API
Now that you have familiarized yourself with the Token Holder API let’s take a closer look at how you can use this premier tool to get crypto holder data. More specifically, we’ll show you how to get token holder stats in three simple steps:
- Get an API Key
- Write a Script
- Run the Code
But before we can move on, you need to handle a couple of prerequisites!
Prerequisites
Before proceeding to the first step, make sure you have the following installed:
Step 1: Get an API Key
The first thing you’ll need is a Moralis API key. As such, if you haven’t already, click the ”Start for Free” button at the top right and sign up for an account:
With an account at hand, you’ll find your API key directly under the ”Home” tab once you log into the admin panel:
Copy the key for now, as you’ll need it in the next step when calling the Token Holder API.
Step 2: Write a Script
Open your preferred IDE, set up a project, launch a new terminal, and initialize a new project with this command:
npm init
Install the required dependencies:
npm install node-fetch --save npm install moralis @moralisweb3/common-evm-utils
Next, open your ”package.json” file and add ”type”: ”module” to the list:
From here, set up a new ”index.js” file and add the following code:
import fetch from "node-fetch";
const options = {
method: "GET",
headers: {
accept: "application/json",
"X-API-Key": "YOUR_API_KEY",
},
};
fetch(
"https://deep-index.moralis.io/api/v2.2/erc20/0x6982508145454ce325ddbe47a25d4ec3d2311933/holders?chain=eth",
options
)
.then((response) => response.json())
.then((response) => console.log(response))
.catch((err) => console.error(err));
Lastly, you need to make some small configurations to the code. Firstly, replace YOUR_API_KEY with the key you just copied. Also, swap out the address to fit your preferences:
Step 3: Run the Code
From here, all that remains is to run the code. To do so, open a new terminal and run this command in the project’s root folder:
node index.js
In return, you’ll get a response that looks like this:
{
totalHolders: 421342,
holdersByAcquisition: { swap: 122795, transfer: 282993, airdrop: 15554 },
holderChange: {
'5min': { change: 2, changePercent: 0.00047 },
'1h': { change: 18, changePercent: 0.0043 },
'6h': { change: 98, changePercent: 0.023 },
'24h': { change: 356, changePercent: 0.084 },
'3d': { change: 1156, changePercent: 0.27 },
'7d': { change: 2122, changePercent: 0.5 },
'30d': { change: 9819, changePercent: 2.3 }
},
holderSupply: {
top10: { supply: '164783457390612.77', supplyPercent: 39 },
top25: { supply: '226647944524114.14', supplyPercent: 54 },
top50: { supply: '273001677904297.12', supplyPercent: 65 },
top100: { supply: '307354487723478.82', supplyPercent: 73 },
top250: { supply: '344156607227442.39', supplyPercent: 82 },
top500: { supply: '362561870786335.94', supplyPercent: 86 }
},
holderDistribution: {
whales: 106,
sharks: 77,
dolphins: 634,
fish: 2130,
octopus: 6136,
crab: 22071,
shrimps: 390188
}
}
Let’s break down the response parameters here:
totalHolders: Number of holders in total.holdersByAcquisition: An overview of how holders acquired their tokens, whether it’s through airdrops, transfers, or swaps.holderChange: Changes in holder count over different timeframes. From as long as a month to as short as five minutes.holderSupply: Insight into supply distribution among top holders.holderDistribution: An overview of holder distribution by wallet size. Categories include shrimp, crabs, octopus, fish, dolphins, sharks, and whales.
That’s it! It’s this easy to get crypto holder data with the Token Holder API. However, if you’re looking for an even more in-depth tutorial, check out the YouTube video down below:
Also, to learn more about this premier interface and other endpoints, please explore the Token API further!
What Can You Build with the Token Holder API?
The Token Holder API has many prominent use cases, allowing you to build everything from holders lists to comprehensive crypto charts. Let’s look at three prominent examples down below.
#1 Top Holders List
With just one call to the Token Holders endpoint, you can create a comprehensive list of a token’s top holders. What’s more, thanks to the comprehensiveness of the response, you can include address labels, ownership percentages, and much more. Here’s an example of what it might look like:
#2 Token Holder Stats
With the Token Holder API, you can give users in-depth insight into token holder stats, including short-term trends, supply distribution, and acquisition data. And the best part? You can get all the data you need with just one request to the Token Holder Stats endpoint. Here’s an example of what the feature can look like:
#3 Token Holders Chart
With the Token Holders Timeseries endpoint, you can fetch all the data needed to build a comprehensive token holders chart, giving your users an overview of how the holder count has developed over time. Here’s an example of what it can look like:
Top lists, size distribution tables, and crypto charts are only three prominent examples of what you can build with the Token Holder API. Here, the only thing stopping you is your imagination!
Moralis vs. HolderScan API: Which is the Best Crypto Holder API?
Now that you know what the Token Holder API is, let’s take a closer look at how this premier tool stacks up against a known competitor: HolderScan API. Here’s a quick summary of some key differences:
Let’s break it down a bit further below:
- Cross-Chain Support: Moralis APIs support all EVM chains and Solana, while HolderScan API is limited to Solana only.
- Token Coverage: Moralis APIs give you access to more than 6,500,000 tokens across all major chains. In contrast, the HolderScan API has a much narrower scope.
- Available Timeframes: Moralis supports a wider range of holder timeframes, from five minutes to 30 days. In comparison, the HolderScan API only has three: seven, 14, and 30 days.
- In-Depth Holder Data: Moralis provides more detailed data on token holders compared to HolderScan API. This includes more granular distribution data, in-depth acquisition insights, and more.
All in all, the Token Holder API is a more complete solution than the HolderScan API. As such, if you’re looking for an easy way to integrate crypto holder insights into your platform, start using the Token Holder API today!
Also, superior APIs are one of many reasons why Moralis.com is a better platform for crypto traders than HolderScan. To learn more about this, read our HolderScan alternative guide!
Beyond the #1 Token Holder API – Exploring Other Moralis Tools & Features
In addition to a top-tier Token Holder API, Moralis offers a bunch of other industry-leading tools. Here are some other APIs and resources you’ll likely find helpful if you’re a Web3 developer:
- Wallet API: The perfect tool for integrating wallet-related data into your project, allowing you to build everything from portfolio trackers to tax tools without breaking a sweat. Fetch in-depth portfolio data, decoded wallet history, DeFi positions, a wallet’s net worth, and much more with just a single API call.
- NFT API: The NFT API is a top-tier tool for anyone building NFT-related platforms, such as marketplaces, NFT-Fi platforms, etc. It allows users to easily access real-time ownership insights, up-to-date metadata, balances, prices, and much more.
- Price API: The ultimate interface for anyone looking to enrich their crypto platform with accurate price data. Query real-time and historical prices, in-depth trading stats, and OHLCV data with single requests.
- Streams API: The Streams API is the industry’s #1 real-time data solution, allowing you to set up customized Web3 data pipelines with minimal effort. Experience 100% delivery guarantees, rich data payloads, and full cross-chain support spanning all major networks.
- Extended RPC Methods: With the Extended RPC Methods, you get the same data Moralis’ APIs deliver but through RPC-style requests. Get real-time prices, fully decoded transactions, token balances, NFT metadata, and much more with ease.
To learn more about the tools and interfaces above, please check out the Web3 API page!
Summary: Token Holder API – Best Cross-Chain Crypto Holder API
Adding token holder data to your platform can help boost its value by allowing users to identify concentration risks, detect whale movements, and gauge overall market sentiment. But what is the best way to fetch and integrate these insights? The answer: Moralis Token Holder API!
The Token Holder API is the easiest way to fetch and integrate crypto holder data into your Web3 projects. Here’s an overview of the available endpoints:
- Token Holders: Get a list of all major holders of a token.
- Token Holder Stats: Query token holder stats, including acquisition insights, supply distribution data, holder count, and more.
- Token Holders Timeseries: Fetch historical holder statistics for any token.
So, if you’re looking for an easy way to get crypto holder data, be sure to check out the Token Holder API today!
Also, if you liked this guide, consider checking out more content here on the blog. For example, dive into our Raydium API article or learn how to explore the top SimpleHash alternative in 2025.
