Cambrian Token Holders Distribution API

By Cambrian Network solana

GET /api/v1/solana/tokens/holder-distribution-over-time

Solana Token Holder Distribution Over Time

Overview

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.

Business Value

  • Portfolio Analysis: Track how token distribution changes across different holder value tiers over time
  • Market Insights: Understand concentration and democratization trends in token ownership
  • Risk Assessment: Identify periods of wealth concentration or distribution that may impact market stability
  • Investment Research: Analyze holder behavior patterns to inform strategic decisions
  • Compliance Monitoring: Track large holder movements for regulatory and risk management purposes

Endpoint Details

URL: 

https://api.cambrian.org/solana/tokens/holder-distribution-over-time

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

Query Parameters

Parameter Type Required Default Description
token_address string Yes - Token mint address (program id)
interval integer Yes - Block interval to use
start_block integer Yes - Block to start from
end_block integer Yes - Block to end at

Response Field Descriptions

Response Field Type Description
blockNumber UInt64 Block number of the sampled snapshot
blockTime DateTime('UTC') UTC timestamp corresponding to the block
minAmountUSD Nullable(UInt32) Lower bound (inclusive) of the USD value tier
maxAmountUSD Nullable(UInt32) Upper bound (exclusive) of the USD value tier; null indicates no upper bound
totalHeldUSD Float64 Total USD value held by all holders within this tier at this block
holderCount UInt64 Number of holders within this USD value tier at this block

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 -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:

[
  {
    "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
  }
]

Note: result collections are limited to 10 items. This response shows two block snapshots (340000000 and 340500000), each broken into USD value tiers with the total USD held and holder count per tier. At block 340000000, the top tier (holders with over $1,000,000) had only 4 holders but collectively held over $36M; a small number of large holders accounted for most of the value.

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/solana/tokens/holder-distribution-over-time"
);
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/solana/tokens/holder-distribution-over-time")
        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 through 5 automatically.

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

Related Endpoints

  • /solana/tokens - Returns a paginated list of known tokens for the Solana chain.
  • /solana/tokens/holders - Returns a list of accounts currently holding a specific Solana token, sorted by their current balance (descending).
  • /solana/tokens/holders-over-time - Returns a list of accounts holding a specific token on Solana, providing snapshots at specified block intervals within a given range.
  • /solana/tokens/security - Provides comprehensive security analysis for a token on Solana, including ownership concentration and holder distribution.