Top Token Holders
Returns the top token holders for a given ERC-20 token address on a supported EVM chain. Results are sorted by holdings and include each holder's token amount and USD value, so you can quickly see how concentrated a token's supply is among its largest holders.
GET
https://api.cambrian.org/evm/tvl/top-owners
Parameters
chain_id (integer)
EVM chain ID.
token_address* (string)
token address
limit (integer)
Limit the number of results.
offset (integer)
Offset the results, allows you to skip a number of rows before starting to return rows.
Responses
Code
Description
200
Successful response
Media type: application/vnd.cambrian.table.v1.0.0+json
[
{
"columns": [
{
"name": "chainId",
"type": "UInt16"
},
{
"name": "ownerAddress",
"type": "FixedString(42)"
},
{
"name": "tokenAddress",
"type": "FixedString(42)"
},
{
"name": "tokenSymbol",
"type": "String"
},
{
"name": "tokenAmount",
"type": "Float64"
},
{
"name": "valueUsd",
"type": "Float64"
}
],
"data": [
[
8453,
"0x67eaf2bee4384a2f84da9eb8105c661c123736ba",
"0x63706e401c06ac8513145b7687a14804d17f814b",
"AAVE",
6488.687538110045,
1079227.2506855628
],
[
8453,
"0x4a79b0168296c0ef7b8f314973b82ad406a29f1b",
"0x63706e401c06ac8513145b7687a14804d17f814b",
"AAVE",
6097.478579178618,
1014159.6439143328
],
[
8453,
"0x2e86514cfd61fb19c5cf2b879d536d273d6e693d",
"0x63706e401c06ac8513145b7687a14804d17f814b",
"AAVE",
605.33109911312,
100681.34950455723
],
[
8453,
"0xce94090458719c167af5477db61c9bc985961d1b",
"0x63706e401c06ac8513145b7687a14804d17f814b",
"AAVE",
517.5104988036608,
86074.63829079158
],
[
8453,
"0x4446adc0b8136ffc55ddb7a488ba5509ace2a5ef",
"0x63706e401c06ac8513145b7687a14804d17f814b",
"AAVE",
499.9907037231182,
83160.6683752583
],
[
8453,
"0x7d94baf661d5ed8ad30d7241d1a50f3883083ef7",
"0x63706e401c06ac8513145b7687a14804d17f814b",
"AAVE",
488.85504901645874,
81308.53696300166
],
[
8453,
"0x30ee902ec31b826ae92d22310eb9a138613002a9",
"0x63706e401c06ac8513145b7687a14804d17f814b",
"AAVE",
436.8705580657543,
72662.24618115915
],
[
8453,
"0xa20dfe337e9361ae0a7cb986a900a4a0410858a4",
"0x63706e401c06ac8513145b7687a14804d17f814b",
"AAVE",
397.1463434771646,
66055.13886642255
],
[
8453,
"0xcebf685d48005a1d34086fee14e34639341e84ab",
"0x63706e401c06ac8513145b7687a14804d17f814b",
"AAVE",
380.67812577406386,
63316.07195789557
],
[
8453,
"0x4e3560437dd1f478ba8bb3dc2653071287af7c89",
"0x63706e401c06ac8513145b7687a14804d17f814b",
"AAVE",
370.31553529012695,
61592.52001117676
]
],
"rows": 10
}
]
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. Top Holders for a Base Token
Retrieve the top 10 holders of the AAVE token on Base (chain ID 8453).
curl
curl -X GET "https://api.cambrian.org/evm/tvl/top-owners?token_address=0x63706e401c06ac8513145b7687a14804d17f814b&limit=10" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
Response:
JSON
1[
2 {
3 "columns": [
4 {
5 "name": "chainId",
6 "type": "UInt16"
7 },
8 {
9 "name": "ownerAddress",
10 "type": "FixedString(42)"
11 },
12 {
13 "name": "tokenAddress",
14 "type": "FixedString(42)"
15 },
16 {
17 "name": "tokenSymbol",
18 "type": "String"
19 },
20 {
21 "name": "tokenAmount",
22 "type": "Float64"
23 },
24 {
25 "name": "valueUsd",
26 "type": "Float64"
27 }
28 ],
29 "data": [
30 [
31 8453,
32 "0x67eaf2bee4384a2f84da9eb8105c661c123736ba",
33 "0x63706e401c06ac8513145b7687a14804d17f814b",
34 "AAVE",
35 6488.687538110045,
36 1079227.2506855628
37 ],
38 [
39 8453,
40 "0x4a79b0168296c0ef7b8f314973b82ad406a29f1b",
41 "0x63706e401c06ac8513145b7687a14804d17f814b",
42 "AAVE",
43 6097.478579178618,
44 1014159.6439143328
45 ],
46 [
47 8453,
48 "0x2e86514cfd61fb19c5cf2b879d536d273d6e693d",
49 "0x63706e401c06ac8513145b7687a14804d17f814b",
50 "AAVE",
51 605.33109911312,
52 100681.34950455723
53 ],
54 [
55 8453,
56 "0xce94090458719c167af5477db61c9bc985961d1b",
57 "0x63706e401c06ac8513145b7687a14804d17f814b",
58 "AAVE",
59 517.5104988036608,
60 86074.63829079158
61 ],
62 [
63 8453,
64 "0x4446adc0b8136ffc55ddb7a488ba5509ace2a5ef",
65 "0x63706e401c06ac8513145b7687a14804d17f814b",
66 "AAVE",
67 499.9907037231182,
68 83160.6683752583
69 ],
70 [
71 8453,
72 "0x7d94baf661d5ed8ad30d7241d1a50f3883083ef7",
73 "0x63706e401c06ac8513145b7687a14804d17f814b",
74 "AAVE",
75 488.85504901645874,
76 81308.53696300166
77 ],
78 [
79 8453,
80 "0x30ee902ec31b826ae92d22310eb9a138613002a9",
81 "0x63706e401c06ac8513145b7687a14804d17f814b",
82 "AAVE",
83 436.8705580657543,
84 72662.24618115915
85 ],
86 [
87 8453,
88 "0xa20dfe337e9361ae0a7cb986a900a4a0410858a4",
89 "0x63706e401c06ac8513145b7687a14804d17f814b",
90 "AAVE",
91 397.1463434771646,
92 66055.13886642255
93 ],
94 [
95 8453,
96 "0xcebf685d48005a1d34086fee14e34639341e84ab",
97 "0x63706e401c06ac8513145b7687a14804d17f814b",
98 "AAVE",
99 380.67812577406386,
100 63316.07195789557
101 ],
102 [
103 8453,
104 "0x4e3560437dd1f478ba8bb3dc2653071287af7c89",
105 "0x63706e401c06ac8513145b7687a14804d17f814b",
106 "AAVE",
107 370.31553529012695,
108 61592.52001117676
109 ]
110 ],
111 "rows": 10
112 }
113]
2 {
3 "columns": [
4 {
5 "name": "chainId",
6 "type": "UInt16"
7 },
8 {
9 "name": "ownerAddress",
10 "type": "FixedString(42)"
11 },
12 {
13 "name": "tokenAddress",
14 "type": "FixedString(42)"
15 },
16 {
17 "name": "tokenSymbol",
18 "type": "String"
19 },
20 {
21 "name": "tokenAmount",
22 "type": "Float64"
23 },
24 {
25 "name": "valueUsd",
26 "type": "Float64"
27 }
28 ],
29 "data": [
30 [
31 8453,
32 "0x67eaf2bee4384a2f84da9eb8105c661c123736ba",
33 "0x63706e401c06ac8513145b7687a14804d17f814b",
34 "AAVE",
35 6488.687538110045,
36 1079227.2506855628
37 ],
38 [
39 8453,
40 "0x4a79b0168296c0ef7b8f314973b82ad406a29f1b",
41 "0x63706e401c06ac8513145b7687a14804d17f814b",
42 "AAVE",
43 6097.478579178618,
44 1014159.6439143328
45 ],
46 [
47 8453,
48 "0x2e86514cfd61fb19c5cf2b879d536d273d6e693d",
49 "0x63706e401c06ac8513145b7687a14804d17f814b",
50 "AAVE",
51 605.33109911312,
52 100681.34950455723
53 ],
54 [
55 8453,
56 "0xce94090458719c167af5477db61c9bc985961d1b",
57 "0x63706e401c06ac8513145b7687a14804d17f814b",
58 "AAVE",
59 517.5104988036608,
60 86074.63829079158
61 ],
62 [
63 8453,
64 "0x4446adc0b8136ffc55ddb7a488ba5509ace2a5ef",
65 "0x63706e401c06ac8513145b7687a14804d17f814b",
66 "AAVE",
67 499.9907037231182,
68 83160.6683752583
69 ],
70 [
71 8453,
72 "0x7d94baf661d5ed8ad30d7241d1a50f3883083ef7",
73 "0x63706e401c06ac8513145b7687a14804d17f814b",
74 "AAVE",
75 488.85504901645874,
76 81308.53696300166
77 ],
78 [
79 8453,
80 "0x30ee902ec31b826ae92d22310eb9a138613002a9",
81 "0x63706e401c06ac8513145b7687a14804d17f814b",
82 "AAVE",
83 436.8705580657543,
84 72662.24618115915
85 ],
86 [
87 8453,
88 "0xa20dfe337e9361ae0a7cb986a900a4a0410858a4",
89 "0x63706e401c06ac8513145b7687a14804d17f814b",
90 "AAVE",
91 397.1463434771646,
92 66055.13886642255
93 ],
94 [
95 8453,
96 "0xcebf685d48005a1d34086fee14e34639341e84ab",
97 "0x63706e401c06ac8513145b7687a14804d17f814b",
98 "AAVE",
99 380.67812577406386,
100 63316.07195789557
101 ],
102 [
103 8453,
104 "0x4e3560437dd1f478ba8bb3dc2653071287af7c89",
105 "0x63706e401c06ac8513145b7687a14804d17f814b",
106 "AAVE",
107 370.31553529012695,
108 61592.52001117676
109 ]
110 ],
111 "rows": 10
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/evm/tvl/top-owners"
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/evm/tvl/top-owners"
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/evm/tvl/top-owners")
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/evm/tvl/top-owners")
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