Cambrian Top token holders API
GET /api/v1/evm/tvl/top-owners
Top Token Holders
Overview
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.
Business Value
- Portfolio Analysis: Identify whale wallets and major token holders for investment research and risk assessment
- Token Distribution: Analyze token concentration and decentralization metrics for due diligence
- Market Intelligence: Track large holder movements to anticipate potential market impacts
- Risk Management: Monitor concentration risk by identifying addresses holding significant portions of token supply
- Competitive Analysis: Research major stakeholders and institutional holders across different tokens
Endpoint Details
URL:
https://api.cambrian.org/evm/tvl/top-owners
Method: GET
Authentication: Required via X-API-Key header
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chain_id | integer | No | 8453 | EVM chain ID. Enum: 1, 8453, 42161, 4663, 56 |
| token_address | string | Yes | - | Token address. Pattern: ^0x[a-fA-F0-9]{40}$ |
| limit | integer | No | 20 | Limit the number of results. Min: 1, Max: 10000 |
| offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. Min: 0, Max: 100000000 |
Response Field Descriptions
| Response Field | Type | Description |
|---|---|---|
| chainId | UInt16 | EVM chain ID the holder data belongs to |
| ownerAddress | FixedString(42) | Wallet address of the token holder |
| tokenAddress | FixedString(42) | Contract address of the token |
| tokenSymbol | String | Symbol of the token |
| tokenAmount | Float64 | Amount of tokens held by the address |
| valueUsd | Float64 | USD value of the held token amount |
Examples
1. Top Holders for a Base Token
Retrieve the top 10 holders of the AAVE token on Base (chain ID 8453).
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:
[
{
"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
}
]
Results are capped at 10 items per request. This response shows the top 10 AAVE holders on Base by USD value, with the largest holding over $1.07M worth of AAVE.
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.
Quick Start (TypeScript)
npm install @x402/fetch @x402/evm viem
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));
const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const response = await fetchWithPayment(
"https://x402.cambrian.org/evm/tvl/top-owners"
);
const data = await response.json();
Quick Start (Python)
pip install "x402[httpx]"
import asyncio, os
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client
async def main():
client = x402Client()
account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
register_exact_evm_client(client, EthAccountSigner(account))
async with x402HttpxClient(client) as http:
response = await http.get("https://x402.cambrian.org/evm/tvl/top-owners")
print(response.json())
asyncio.run(main())
Payment Flow
- Send a normal request to the endpoint; no API key is needed
- The server returns
402 Payment Requiredwith payment details - The x402 SDK signs a payment authorization with your wallet
- The SDK resubmits the request with the signed payment
- The server verifies the 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