Solana Token Holder Distribution Over Time
Returns the distribution of a Solana token's holders over a specified block range, sampled at a given block interval and grouped into USD value tiers. Use it to track how holder concentration and value distribution change as the token's on-chain activity unfolds.
GET
https://api.cambrian.org/solana/tokens/holder-distribution-over-time
Parameters
token_address* (string)
Token mint address (program id)
interval* (integer)
Block interval to use
start_block* (integer)
Block to start from
end_block* (integer)
Block to end at
Responses
Code
Description
200
Successful response
Media type: application/vnd.cambrian.table.v1.0.0+json
[
{
"columns": [
{
"name": "blockNumber",
"type": "UInt64"
},
{
"name": "blockTime",
"type": "DateTime('UTC')"
},
{
"name": "minAmountUSD",
"type": "Nullable(UInt32)"
},
{
"name": "maxAmountUSD",
"type": "Nullable(UInt32)"
},
{
"name": "totalHeldUSD",
"type": "Float64"
},
{
"name": "holderCount",
"type": "UInt64"
}
],
"data": [
[
340000000,
"2025-05-14T16:53:13+00:00",
0,
100,
64672.01377046308,
6380
],
[
340000000,
"2025-05-14T16:53:13+00:00",
100,
1000,
620681.6522664049,
1689
],
[
340000000,
"2025-05-14T16:53:13+00:00",
1000,
10000,
2751297.04059455,
891
],
[
340000000,
"2025-05-14T16:53:13+00:00",
10000,
100000,
7071390.425242035,
247
],
[
340000000,
"2025-05-14T16:53:13+00:00",
100000,
1000000,
13759394.531400206,
51
],
[
340000000,
"2025-05-14T16:53:13+00:00",
1000000,
null,
36312518.00213441,
4
],
[
340500000,
"2025-05-16T23:53:03+00:00",
0,
100,
3915.4879536763506,
342
],
[
340500000,
"2025-05-16T23:53:03+00:00",
100,
1000,
30717.89440404316,
88
],
[
340500000,
"2025-05-16T23:53:03+00:00",
1000,
10000,
143098.24544360803,
44
],
[
340500000,
"2025-05-16T23:53:03+00:00",
10000,
100000,
221563.2437320579,
10
]
],
"rows": 16
}
]
400
Bad Request: Invalid request parameters or malformed request.
401
Unauthorized: Missing or invalid API key. Include X-API-Key header with your request.
403
Forbidden: Invalid API key or insufficient permissions to access this resource.
404
Not Found: Endpoint or resource does not exist.
408
Request Timeout: Request took too long to process. Try again.
500
Internal Server Error: An unexpected error occurred while processing your request.
503
Service Unavailable: The server is temporarily unable to handle the request. Please try again later.
Examples
1. Retrieve Holder Distribution Over a Block Range
This example fetches the holder distribution for a token across a 1,000,000 block range, sampled every 500,000 blocks, grouped by USD value tiers.
curl
curl -X GET "https://api.cambrian.org/solana/tokens/holder-distribution-over-time?token_address=HeLp6NuQkmYB4pYWo2zYs22mESHXPQYzXbB8n4V98jwC&interval=500000&start_block=340000000&end_block=341000000" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
Response:
JSON
1[
2 {
3 "columns": [
4 {
5 "name": "blockNumber",
6 "type": "UInt64"
7 },
8 {
9 "name": "blockTime",
10 "type": "DateTime('UTC')"
11 },
12 {
13 "name": "minAmountUSD",
14 "type": "Nullable(UInt32)"
15 },
16 {
17 "name": "maxAmountUSD",
18 "type": "Nullable(UInt32)"
19 },
20 {
21 "name": "totalHeldUSD",
22 "type": "Float64"
23 },
24 {
25 "name": "holderCount",
26 "type": "UInt64"
27 }
28 ],
29 "data": [
30 [
31 340000000,
32 "2025-05-14T16:53:13+00:00",
33 0,
34 100,
35 64672.01377046308,
36 6380
37 ],
38 [
39 340000000,
40 "2025-05-14T16:53:13+00:00",
41 100,
42 1000,
43 620681.6522664049,
44 1689
45 ],
46 [
47 340000000,
48 "2025-05-14T16:53:13+00:00",
49 1000,
50 10000,
51 2751297.04059455,
52 891
53 ],
54 [
55 340000000,
56 "2025-05-14T16:53:13+00:00",
57 10000,
58 100000,
59 7071390.425242035,
60 247
61 ],
62 [
63 340000000,
64 "2025-05-14T16:53:13+00:00",
65 100000,
66 1000000,
67 13759394.531400206,
68 51
69 ],
70 [
71 340000000,
72 "2025-05-14T16:53:13+00:00",
73 1000000,
74 null,
75 36312518.00213441,
76 4
77 ],
78 [
79 340500000,
80 "2025-05-16T23:53:03+00:00",
81 0,
82 100,
83 3915.4879536763506,
84 342
85 ],
86 [
87 340500000,
88 "2025-05-16T23:53:03+00:00",
89 100,
90 1000,
91 30717.89440404316,
92 88
93 ],
94 [
95 340500000,
96 "2025-05-16T23:53:03+00:00",
97 1000,
98 10000,
99 143098.24544360803,
100 44
101 ],
102 [
103 340500000,
104 "2025-05-16T23:53:03+00:00",
105 10000,
106 100000,
107 221563.2437320579,
108 10
109 ]
110 ],
111 "rows": 16
112 }
113]
2 {
3 "columns": [
4 {
5 "name": "blockNumber",
6 "type": "UInt64"
7 },
8 {
9 "name": "blockTime",
10 "type": "DateTime('UTC')"
11 },
12 {
13 "name": "minAmountUSD",
14 "type": "Nullable(UInt32)"
15 },
16 {
17 "name": "maxAmountUSD",
18 "type": "Nullable(UInt32)"
19 },
20 {
21 "name": "totalHeldUSD",
22 "type": "Float64"
23 },
24 {
25 "name": "holderCount",
26 "type": "UInt64"
27 }
28 ],
29 "data": [
30 [
31 340000000,
32 "2025-05-14T16:53:13+00:00",
33 0,
34 100,
35 64672.01377046308,
36 6380
37 ],
38 [
39 340000000,
40 "2025-05-14T16:53:13+00:00",
41 100,
42 1000,
43 620681.6522664049,
44 1689
45 ],
46 [
47 340000000,
48 "2025-05-14T16:53:13+00:00",
49 1000,
50 10000,
51 2751297.04059455,
52 891
53 ],
54 [
55 340000000,
56 "2025-05-14T16:53:13+00:00",
57 10000,
58 100000,
59 7071390.425242035,
60 247
61 ],
62 [
63 340000000,
64 "2025-05-14T16:53:13+00:00",
65 100000,
66 1000000,
67 13759394.531400206,
68 51
69 ],
70 [
71 340000000,
72 "2025-05-14T16:53:13+00:00",
73 1000000,
74 null,
75 36312518.00213441,
76 4
77 ],
78 [
79 340500000,
80 "2025-05-16T23:53:03+00:00",
81 0,
82 100,
83 3915.4879536763506,
84 342
85 ],
86 [
87 340500000,
88 "2025-05-16T23:53:03+00:00",
89 100,
90 1000,
91 30717.89440404316,
92 88
93 ],
94 [
95 340500000,
96 "2025-05-16T23:53:03+00:00",
97 1000,
98 10000,
99 143098.24544360803,
100 44
101 ],
102 [
103 340500000,
104 "2025-05-16T23:53:03+00:00",
105 10000,
106 100000,
107 221563.2437320579,
108 10
109 ]
110 ],
111 "rows": 16
112 }
113]
x402 Payment Option
This endpoint supports pay-per-use access via the x402 payment protocol (v2): pay $0.05 USDC per request using blockchain micropayments. No API key required.
Quickstart (Typescript)
bash
npm install @x402/fetch @x402/evm viem
TypeScript
1import { x402Client } from "@x402/core/client";
2import { ExactEvmScheme } from "@x402/evm/exact/client";
3import { wrapFetchWithPayment } from "@x402/fetch";
4import { privateKeyToAccount } from "viem/accounts";
5const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
6const client = new x402Client();
7client.register("eip155:*", new ExactEvmScheme(signer));
8const fetchWithPayment = wrapFetchWithPayment(fetch, client);
9const response = await fetchWithPayment(
10 "https://x402.cambrian.org/solana/tokens/holder-distribution-over-time"
11);
12const data = await response.json();
2import { ExactEvmScheme } from "@x402/evm/exact/client";
3import { wrapFetchWithPayment } from "@x402/fetch";
4import { privateKeyToAccount } from "viem/accounts";
5const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
6const client = new x402Client();
7client.register("eip155:*", new ExactEvmScheme(signer));
8const fetchWithPayment = wrapFetchWithPayment(fetch, client);
9const response = await fetchWithPayment(
10 "https://x402.cambrian.org/solana/tokens/holder-distribution-over-time"
11);
12const data = await response.json();
Quickstart (Python)
bash
pip install "x402[httpx]"
Python
1import asyncio, os
2from eth_account import Account
3from x402 import x402Client
4from x402.http.clients import x402HttpxClient
5from x402.mechanisms.evm import EthAccountSigner
6from x402.mechanisms.evm.exact.register import register_exact_evm_client
7async def main():
8 client = x402Client()
9 account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
10 register_exact_evm_client(client, EthAccountSigner(account))
11 async with x402HttpxClient(client) as http:
12 response = await http.get("https://x402.cambrian.org/solana/tokens/holder-distribution-over-time")
13 print(response.json())
14asyncio.run(main())
2from eth_account import Account
3from x402 import x402Client
4from x402.http.clients import x402HttpxClient
5from x402.mechanisms.evm import EthAccountSigner
6from x402.mechanisms.evm.exact.register import register_exact_evm_client
7async def main():
8 client = x402Client()
9 account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
10 register_exact_evm_client(client, EthAccountSigner(account))
11 async with x402HttpxClient(client) as http:
12 response = await http.get("https://x402.cambrian.org/solana/tokens/holder-distribution-over-time")
13 print(response.json())
14asyncio.run(main())
Payment Flow
- Send a normal request to the endpoint (no API key needed)
- Server returns 402 Payment Required with payment details
- The x402 SDK automatically signs a payment authorization with your wallet
- The SDK resubmits the request with the signed payment
- Server verifies payment and returns the API response
The x402 SDK handles steps 2 through 5 automatically.
Network: Base (chain ID 8453) | Currency: USDC | Price: $0.05 per request