Cambrian Top token holders API

By Cambrian Network base

GET /api/v1/evm/tvl/top-owners

Top Token Holders

This endpoint returns the top token holders for a given EVM token address, providing comprehensive holder information including balance amounts, USD values, and token details.

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://opabinia.cambrian.network/api/v1/evm/tvl/top-owners

Method: GET
Authentication: Required via X-API-Key header

Query Parameters

Parameter Type Required Default Description
token_address string Yes - The contract address of the token to analyze
limit integer No 20 Maximum number of results to return (1-1000)
offset integer No 0 Number of results to skip for pagination (0-100000)

Response Field Descriptions

Response Field Type Description
ownerAddress String The wallet address of the token holder
tokenAddress String The contract address of the token being analyzed
tokenSymbol String The symbol of the token (e.g., ODOS)
tokenDecimals Integer Number of decimal places for the token
tokenAmountRaw String Raw token balance (without decimal adjustment)
tokenAmountUI Float Human-readable token balance (adjusted for decimals)
valueUSD Float USD value of the token holdings

Examples

1. Get Top ODOS Token Holders

This example demonstrates how to retrieve the top 20 holders of the ODOS token on the Ethereum network.

curl -X GET "https://opabinia.cambrian.network/api/v1/evm/tvl/top-owners?token_address=0xca73ed1815e5915489570014e024b7ebe65de679" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "columns": [
    {
      "name": "ownerAddress",
      "type": "FixedString(42)"
    },
    {
      "name": "tokenAddress",
      "type": "FixedString(42)"
    },
    {
      "name": "tokenSymbol",
      "type": "String"
    },
    {
      "name": "tokenDecimals",
      "type": "UInt8"
    },
    {
      "name": "tokenAmountRaw",
      "type": "Int256"
    },
    {
      "name": "tokenAmountUI",
      "type": "Float64"
    },
    {
      "name": "valueUSD",
      "type": "Float64"
    }
  ],
  "data": [
    [
      "0xae82febe00a21257ee813cfe2f913dcaa973d33b",
      "0xca73ed1815e5915489570014e024b7ebe65de679",
      "ODOS",
      18,
      "4372541660419060000000000025",
      4372541660.41906,
      8090772.497011255
    ],
    [
      "0x9d1e93bbc148fe7b19eb9ec22a5be4b75b57239f",
      "0xca73ed1815e5915489570014e024b7ebe65de679",
      "ODOS",
      18,
      "2666692701388850000000000011",
      2666692701.38885,
      4934339.256657825
    ],
    [
      "0x32235fe0b39849ddff11bce74d93bf981c9fe5ea",
      "0xca73ed1815e5915489570014e024b7ebe65de679",
      "ODOS",
      18,
      "624198753440077822809615472",
      624198753.4400778,
      1154991.8786863382
    ],
    [
      "0x7ec74ce1ff4c7c2b0bc2bc2f64ac8481db616b34",
      "0xca73ed1815e5915489570014e024b7ebe65de679",
      "ODOS",
      18,
      "458314999999999999999999992",
      458315000.0,
      848047.3566516759
    ],
    [
      "0xc3681709ee476308b45812eabe0eb22f3b816880",
      "0xca73ed1815e5915489570014e024b7ebe65de679",
      "ODOS",
      18,
      "366912550616272296679812715",
      366912550.6162723,
      678919.997539801
    ]
  ],
  "rows": 20
  // ... additional rows omitted for brevity
}

The response shows the top 5 ODOS token holders (truncated from 20 total results). The largest holder owns over 4.3 billion ODOS tokens worth approximately $8.09 million USD, while the fifth-largest holder owns about 366 million tokens worth $678,920 USD.

2. Get Top 5 Token Holders with Pagination

This example demonstrates how to limit results and use pagination to get only the top 5 holders.

curl -X GET "https://opabinia.cambrian.network/api/v1/evm/tvl/top-owners?token_address=0xca73ed1815e5915489570014e024b7ebe65de679&limit=5&offset=0" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "columns": [
    {
      "name": "ownerAddress",
      "type": "FixedString(42)"
    },
    {
      "name": "tokenAddress",
      "type": "FixedString(42)"
    },
    {
      "name": "tokenSymbol",
      "type": "String"
    },
    {
      "name": "tokenDecimals",
      "type": "UInt8"
    },
    {
      "name": "tokenAmountRaw",
      "type": "Int256"
    },
    {
      "name": "tokenAmountUI",
      "type": "Float64"
    },
    {
      "name": "valueUSD",
      "type": "Float64"
    }
  ],
  "data": [
    [
      "0xae82febe00a21257ee813cfe2f913dcaa973d33b",
      "0xca73ed1815e5915489570014e024b7ebe65de679",
      "ODOS",
      18,
      "4372541660419060000000000025",
      4372541660.41906,
      8090772.497011255
    ],
    [
      "0x9d1e93bbc148fe7b19eb9ec22a5be4b75b57239f",
      "0xca73ed1815e5915489570014e024b7ebe65de679",
      "ODOS",
      18,
      "2666692701388850000000000011",
      2666692701.38885,
      4934339.256657825
    ],
    [
      "0x32235fe0b39849ddff11bce74d93bf981c9fe5ea",
      "0xca73ed1815e5915489570014e024b7ebe65de679",
      "ODOS",
      18,
      "624198753440077822809615472",
      624198753.4400778,
      1154991.8786863382
    ],
    [
      "0x7ec74ce1ff4c7c2b0bc2bc2f64ac8481db616b34",
      "0xca73ed1815e5915489570014e024b7ebe65de679",
      "ODOS",
      18,
      "458314999999999999999999992",
      458315000.0,
      848047.3566516759
    ],
    [
      "0xc3681709ee476308b45812eabe0eb22f3b816880",
      "0xca73ed1815e5915489570014e024b7ebe65de679",
      "ODOS",
      18,
      "366912550616272296679812715",
      366912550.6162723,
      678919.997539801
    ]
  ],
  "rows": 20
}

This response shows exactly 5 token holders as requested, providing focused data on the largest holders without overwhelming detail.

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://deep42.cambrian.network/api/v1/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://deep42.cambrian.network/api/v1/evm/tvl/top-owners")
        print(response.json())

asyncio.run(main())

Payment Flow

  1. Send a normal request to the endpoint (no API key needed)
  2. Server returns 402 Payment Required with payment details
  3. The x402 SDK automatically signs a payment authorization with your wallet
  4. The SDK resubmits the request with the signed payment
  5. Server verifies payment and returns the API response

The x402 SDK handles steps 2–5 automatically.

Network: Base (chain ID 8453) | Currency: USDC | Price: $0.05 per request

Related Endpoints

  • /api/v1/evm/tvl/status - Returns the tokens held by a specific address
  • /api/v1/evm/tokens - Returns list of all whitelisted EVM tokens with contract addresses
  • /api/v1/evm/price-current - Returns current price of an EVM token
  • /api/v1/evm/price-hour - Returns historical hourly price data for EVM tokens
  • /api/v1/evm/dexes - List of supported DEXes on EVM compatible chains