Token Holder Distribution Over Time

This endpoint returns the distribution of token holders over a certain block range, at a certain interval, grouped by USD value tiers. It provides insights into how token ownership is distributed across different wallet value segments over time.

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://opabinia.cambrian.network/api/v1/solana/tokens/holder-distribution-over-time

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

Query Parameters

Response Field Descriptions

Examples

1. Token Distribution Analysis

This example demonstrates how to retrieve holder distribution data for the HeLp6NuQkmYB4pYWo2zYs22mESHXPQYzXbB8n4V98jwC token over a 1M block range with 500K block intervals.

curl -X GET "https://opabinia.cambrian.network/api/v1/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,
      66528.06130549808,
      6506
    ],
    [
      340000000,
      "2025-05-14T16:53:13+00:00",
      100,
      1000,
      660922.1813566074,
      1806
    ],
    [
      340000000,
      "2025-05-14T16:53:13+00:00",
      1000,
      10000,
      2883935.3708088435,
      950
    ],
    [
      340000000,
      "2025-05-14T16:53:13+00:00",
      10000,
      100000,
      6750601.965720494,
      244
    ],
    [
      340000000,
      "2025-05-14T16:53:13+00:00",
      100000,
      1000000,
      10750795.752125254,
      37
    ]
  ],
  "rows": 5
  // ... additional rows omitted for brevity
}

The response shows holder distribution across different USD value tiers at block 340000000. For example, there were 6,506 holders with holdings between $0-$100 USD, controlling a total of $66,528 USD worth of tokens, while only 37 holders had between $100K-$1M USD worth, controlling $10.75M USD total.

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/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://deep42.cambrian.network/api/v1/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–5 automatically.

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

Related Endpoints

• /api/v1/solana/tokens/holders - Returns current holders of a specific token sorted by balance
• /api/v1/solana/tokens/holders-over-time - Returns historical holder snapshots at specified block intervals
• /api/v1/solana/tokens/security - Comprehensive security analysis including holder distribution metrics
• /api/v1/solana/holder-token-balances - Token balances in USD for a specific wallet address
• /api/v1/solana/token-details - Comprehensive token details including holder information