Token Holders Over Time

This endpoint returns historical token holder balances for a Solana token across specified time periods. It provides a comprehensive view of how token holders and their balances have changed over time, sampled at configurable block intervals.

Business Value

• Portfolio Tracking: Monitor token distribution patterns and concentration levels over time
• Historical Analysis: Analyze token holder behavior and balance changes for research and investment decisions
• Liquidity Assessment: Understand how token ownership has evolved to assess market dynamics
• Risk Management: Track large holder movements and concentration risks for better portfolio management
• Market Intelligence: Gain insights into token adoption and distribution patterns for competitive analysis

Endpoint Details

URL:

https://opabinia.cambrian.network/api/v1/solana/tokens/holders-over-time

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

Query Parameters

Parameter	Type	Required	Default	Description
token_address	string	Yes	-	The program ID (mint address) of the token
interval	integer	Yes	-	Block interval for sampling balances (minimum 1)
start_block	integer	Yes	-	Starting block number for the time range
end_block	integer	Yes	-	Ending block number for the time range

Response Field Descriptions

Response Field	Type	Description
blockNumber	UInt64	The block number when the balance was recorded
blockTime	DateTime	UTC timestamp of the block when balance was recorded
account	FixedString(44)	Solana account address holding the token
balanceUi	Float64	Token balance in human-readable format (with decimals)
balanceRaw	UInt64	Raw token balance (smallest denomination)

Examples

1. Historical Holder Analysis for Wrapped SOL

This example demonstrates retrieving token holder balances over a 5 million block range for Wrapped SOL (wSOL), sampled every 1 million blocks.

curl -X GET "https://opabinia.cambrian.network/api/v1/solana/tokens/holders-over-time?token_address=So11111111111111111111111111111111111111112&interval=1000000&start_block=330000000&end_block=335000000" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "columns": [
    {"name": "blockNumber", "type": "UInt64"},
    {"name": "blockTime", "type": "DateTime('UTC')"},
    {"name": "account", "type": "FixedString(44)"},
    {"name": "balanceUi", "type": "Float64"},
    {"name": "balanceRaw", "type": "UInt64"}
  ],
  "data": [
    [331000000, "2025-04-03T09:49:45+00:00", "3SdrFTt4Ye5yppzpT9axNMj8W1x71nDYXdjv7vDuBpnR", 6948.248447521, 6948248447521],
    [331000000, "2025-04-03T09:49:45+00:00", "3ghzHYHC7nXx11DEq7aGNHwTyT3SWmCs1B2Ay7HB8ZCk", 2266.728012968, 2266728012968],
    [331000000, "2025-04-03T09:49:45+00:00", "rS2oaqvZzQavgsLsQ59mxCpbWqmbZFPqJ1o9xLtJDzA", 1853.103134163, 1853103134163],
    [331000000, "2025-04-03T09:49:45+00:00", "5x8wDXPoSU8ZL5x5qPLatqhXFTLdKaf687sRHeyiE4hM", 1590.0, 1590000000000],
    [331000000, "2025-04-03T09:49:45+00:00", "CJaWa5cusn5tL49d3i1wjFFS25NtMg1dd2uL1JWJph87", 556.919985925, 556919985925]
  ],
  "rows": 5
  // ... additional rows omitted for brevity
}

This response shows token holder balances sampled at block 331,000,000 (April 3, 2025). The data reveals the largest holders at that point in time, with balances ranging from over 6,948 wSOL down to 556 wSOL among the top holders shown.

2. Long-term Holder Trend Analysis

This example shows how to analyze long-term holder trends by using a larger interval to capture major distribution changes.

curl -X GET "https://opabinia.cambrian.network/api/v1/solana/tokens/holders-over-time?token_address=So11111111111111111111111111111111111111112&interval=2500000&start_block=325000000&end_block=335000000" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "columns": [
    {"name": "blockNumber", "type": "UInt64"},
    {"name": "blockTime", "type": "DateTime('UTC')"},
    {"name": "account", "type": "FixedString(44)"},
    {"name": "balanceUi", "type": "Float64"},
    {"name": "balanceRaw", "type": "UInt64"}
  ],
  "data": [
    [331000000, "2025-04-03T09:49:45+00:00", "3SdrFTt4Ye5yppzpT9axNMj8W1x71nDYXdjv7vDuBpnR", 6948.248447521, 6948248447521],
    [331000000, "2025-04-03T09:49:45+00:00", "3ghzHYHC7nXx11DEq7aGNHwTyT3SWmCs1B2Ay7HB8ZCk", 2266.728012968, 2266728012968],
    [331000000, "2025-04-03T09:49:45+00:00", "rS2oaqvZzQavgsLsQ59mxCpbWqmbZFPqJ1o9xLtJDzA", 1853.103134163, 1853103134163],
    [331000000, "2025-04-03T09:49:45+00:00", "5x8wDXPoSU8ZL5x5qPLatqhXFTLdKaf687sRHeyiE4hM", 1590.0, 1590000000000],
    [331000000, "2025-04-03T09:49:45+00:00", "CJaWa5cusn5tL49d3i1wjFFS25NtMg1dd2uL1JWJph87", 556.919985925, 556919985925]
  ],
  "rows": 5
  // ... additional rows omitted for brevity
}

By using a larger interval (2.5 million blocks), this query captures holder balance changes over a 10 million block range, ideal for identifying long-term accumulation or distribution patterns among major token holders.

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/holders-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/holders-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 - Get current token holders and their balances