Token holders

curl "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?limit=50" \
  -H "Authorization: Bearer $API_KEY"

curl "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?flags=bundler,insider" \
  -H "Authorization: Bearer $API_KEY"

const url = new URL(
  "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders",
);
url.searchParams.set("limit", "50");
url.searchParams.set("period", "cycle");

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { holders, holderCount, top10 } = await response.json();

use serde_json::Value;

let page: Value = reqwest::Client::new()
    .get("https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders")
    .query(&[("limit", "50"), ("period", "cycle")])
    .bearer_auth(std::env::var("API_KEY")?)
    .send()
    .await?
    .error_for_status()?
    .json()
    .await?;
let holders = &page["holders"];

{
  "holders": [
    {
      "rank": 7,
      "address": "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5",
      "nativeBalance": "412.7",
      "balance": "20500000000",
      "supplyPct": "0.0231",
      "buyVolume": { "native": "2500", "usd": "450000" },
      "tokensBought": "25000000000",
      "buyCount": 14,
      "sellVolume": { "native": "598.5", "usd": "108000" },
      "tokensSold": "4500000000",
      "sellCount": 3,
      "firstPurchaseAt": 1781250000000,
      "avgEntryPrice": { "native": "0.0000001", "usd": "0.000018" },
      "avgExitPrice": { "native": "0.000000133", "usd": "0.000024" },
      "avgEntryMarketCap": { "native": "8880000", "usd": "1598400000" },
      "avgExitMarketCap": { "native": "11810400", "usd": "2131200000" },
      "realizedPnl": { "native": "148.5", "usd": "27000" },
      "remainingPct": "82",
      "funding": {
        "status": "resolved",
        "address": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
        "amount": "500",
        "asset": null,
        "symbol": "SOL",
        "sourceKind": "cex",
        "sourceLabel": "Binance",
        "timestamp": 1781200000000,
        "tx": "3nVq8Fz1kT7pR2mWcX9sLdHfA4jEuY6gVnX1oB5iC0wQ2rT8yU3iO7pA1sD4fG6h"
      },
      "flags": ["whale"],
      "platforms": [{ "platform": "photon" }],
      "identities": [
        {
          "source": "gmgn",
          "displayName": "Bonk Whale",
          "handle": "bonkwhale",
          "twitter": "bonkwhale",
          "telegram": null,
          "farcaster": null,
          "avatar": null
        }
      ]
    }
  ],
  "holderCount": 982114,
  "top10": {
    "avgEntryPrice": { "native": "0.000000094", "usd": "0.0000169" },
    "avgExitPrice": { "native": "0.000000128", "usd": "0.0000231" }
  }
}

{
  "holders": [],
  "holderCount": 0,
  "top10": { "avgEntryPrice": null, "avgExitPrice": null }
}

GET

tokens

{chain}

{address}

holders

curl "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?limit=50" \
  -H "Authorization: Bearer $API_KEY"

curl "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?flags=bundler,insider" \
  -H "Authorization: Bearer $API_KEY"

const url = new URL(
  "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders",
);
url.searchParams.set("limit", "50");
url.searchParams.set("period", "cycle");

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { holders, holderCount, top10 } = await response.json();

use serde_json::Value;

let page: Value = reqwest::Client::new()
    .get("https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders")
    .query(&[("limit", "50"), ("period", "cycle")])
    .bearer_auth(std::env::var("API_KEY")?)
    .send()
    .await?
    .error_for_status()?
    .json()
    .await?;
let holders = &page["holders"];

{
  "holders": [
    {
      "rank": 7,
      "address": "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5",
      "nativeBalance": "412.7",
      "balance": "20500000000",
      "supplyPct": "0.0231",
      "buyVolume": { "native": "2500", "usd": "450000" },
      "tokensBought": "25000000000",
      "buyCount": 14,
      "sellVolume": { "native": "598.5", "usd": "108000" },
      "tokensSold": "4500000000",
      "sellCount": 3,
      "firstPurchaseAt": 1781250000000,
      "avgEntryPrice": { "native": "0.0000001", "usd": "0.000018" },
      "avgExitPrice": { "native": "0.000000133", "usd": "0.000024" },
      "avgEntryMarketCap": { "native": "8880000", "usd": "1598400000" },
      "avgExitMarketCap": { "native": "11810400", "usd": "2131200000" },
      "realizedPnl": { "native": "148.5", "usd": "27000" },
      "remainingPct": "82",
      "funding": {
        "status": "resolved",
        "address": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
        "amount": "500",
        "asset": null,
        "symbol": "SOL",
        "sourceKind": "cex",
        "sourceLabel": "Binance",
        "timestamp": 1781200000000,
        "tx": "3nVq8Fz1kT7pR2mWcX9sLdHfA4jEuY6gVnX1oB5iC0wQ2rT8yU3iO7pA1sD4fG6h"
      },
      "flags": ["whale"],
      "platforms": [{ "platform": "photon" }],
      "identities": [
        {
          "source": "gmgn",
          "displayName": "Bonk Whale",
          "handle": "bonkwhale",
          "twitter": "bonkwhale",
          "telegram": null,
          "farcaster": null,
          "avatar": null
        }
      ]
    }
  ],
  "holderCount": 982114,
  "top10": {
    "avgEntryPrice": { "native": "0.000000094", "usd": "0.0000169" },
    "avgExitPrice": { "native": "0.000000128", "usd": "0.0000231" }
  }
}

{
  "holders": [],
  "holderCount": 0,
  "top10": { "avgEntryPrice": null, "avgExitPrice": null }
}

Returns the current holders of a token, ranked by balance, largest first. Pools and lockers are ranked alongside other wallets and carry the liquidity_pool or locker flag. The spot.holders stream delivers the same rows.

Filters

flags takes a comma-separated list of wallet classifications, such as bundler,insider. A holder is included when it has at least one of them.
trader takes one wallet address and returns only that wallet’s row.
period sets the span of the trading figures. lifetime, the default, covers every round trip the wallet made on the token. cycle covers the current round trip, from the time the wallet last had a zero balance.
limit sets the number of rows returned. The default is 30, and out-of-range values are clamped to 1–150 rather than rejected.

Response

A response contains holders, holderCount and top10. There is no cursor; a single request returns the largest holders, up to limit.

holders lists the rows. rank is 1-based and, when flags is set, ranks within the matching wallets.
holderCount is the token’s total number of holders and is not affected by limit or flags. It counts trading wallets only, so it can be lower than a list that includes pools.
top10 contains avgEntryPrice and avgExitPrice, weighted by balance, across the first 10 rows returned. Each is null when no row has a value.

Volumes, token totals, trade counts, entry and exit prices and realizedPnl cover the selected period. balance, supplyPct, nativeBalance and funding reflect the wallet’s current state. With period=cycle, avgEntryPrice is the cost basis of the open position. flags, platforms and identities are omitted from a row when empty. Rows do not include a value or unrealized PnL. Calculate them from the token’s price, available from Token details or spot.tokens:

The value is balance times the token’s price.
The unrealized PnL is the value minus balance times avgEntryPrice.

An unknown token returns 200 with an empty holders list and a holderCount of 0, not a 404.

Errors

Code	When
`UNSUPPORTED_CHAIN`	`chain` is not a supported slug
`VALIDATION_ERROR`	A malformed address or `trader`, a `trader` that does not match the chain’s format, an unknown flag or period, or an unknown parameter

curl "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?limit=50" \
  -H "Authorization: Bearer $API_KEY"

curl "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?flags=bundler,insider" \
  -H "Authorization: Bearer $API_KEY"

const url = new URL(
  "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders",
);
url.searchParams.set("limit", "50");
url.searchParams.set("period", "cycle");

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { holders, holderCount, top10 } = await response.json();

use serde_json::Value;

let page: Value = reqwest::Client::new()
    .get("https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders")
    .query(&[("limit", "50"), ("period", "cycle")])
    .bearer_auth(std::env::var("API_KEY")?)
    .send()
    .await?
    .error_for_status()?
    .json()
    .await?;
let holders = &page["holders"];

{
  "holders": [
    {
      "rank": 7,
      "address": "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5",
      "nativeBalance": "412.7",
      "balance": "20500000000",
      "supplyPct": "0.0231",
      "buyVolume": { "native": "2500", "usd": "450000" },
      "tokensBought": "25000000000",
      "buyCount": 14,
      "sellVolume": { "native": "598.5", "usd": "108000" },
      "tokensSold": "4500000000",
      "sellCount": 3,
      "firstPurchaseAt": 1781250000000,
      "avgEntryPrice": { "native": "0.0000001", "usd": "0.000018" },
      "avgExitPrice": { "native": "0.000000133", "usd": "0.000024" },
      "avgEntryMarketCap": { "native": "8880000", "usd": "1598400000" },
      "avgExitMarketCap": { "native": "11810400", "usd": "2131200000" },
      "realizedPnl": { "native": "148.5", "usd": "27000" },
      "remainingPct": "82",
      "funding": {
        "status": "resolved",
        "address": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
        "amount": "500",
        "asset": null,
        "symbol": "SOL",
        "sourceKind": "cex",
        "sourceLabel": "Binance",
        "timestamp": 1781200000000,
        "tx": "3nVq8Fz1kT7pR2mWcX9sLdHfA4jEuY6gVnX1oB5iC0wQ2rT8yU3iO7pA1sD4fG6h"
      },
      "flags": ["whale"],
      "platforms": [{ "platform": "photon" }],
      "identities": [
        {
          "source": "gmgn",
          "displayName": "Bonk Whale",
          "handle": "bonkwhale",
          "twitter": "bonkwhale",
          "telegram": null,
          "farcaster": null,
          "avatar": null
        }
      ]
    }
  ],
  "holderCount": 982114,
  "top10": {
    "avgEntryPrice": { "native": "0.000000094", "usd": "0.0000169" },
    "avgExitPrice": { "native": "0.000000128", "usd": "0.0000231" }
  }
}

{
  "holders": [],
  "holderCount": 0,
  "top10": { "avgEntryPrice": null, "avgExitPrice": null }
}

Authorizations

Authorization

string

header

required

Send an API key, or a session token a key minted, as Authorization: Bearer <credential>. A browser opening /v1/stream offers its session token in Sec-WebSocket-Protocol instead.

Path Parameters

chain

enum<string>

required

Chain the resource lives on. Chain slug. One spelling per chain, in paths and bodies alike. Only a chain with spot data is published.

Available options:

solana,

base,

bsc,

robinhood,

arc

address

string

required

Token mint or contract address.

Query Parameters

limit

integer<int32>

Rows to return, clamped to 1-150; 30 when absent.

Required range: 1 <= x <= 150

trader

string

Restrict to one holder wallet.

flags

string

Wallet classifications to keep, comma-separated. Absent or empty keeps every holder.

period

enum<string>

Span the trading figures cover; lifetime when absent. The span a holder row's trading figures cover: lifetime, every round trip, or cycle, the open one. lifetime when absent.

Available options:

cycle,

lifetime

Response

Current holders, largest balance first; an unknown token answers an empty list.

GET /v1/tokens/{chain}/{address}/holders response: current holders, largest balance first.

holderCount

integer<int64>

required

The token's own holder total, whatever the limit and any flags filter. It counts trading wallets only, so it can run below a full listing that includes pool vaults.

Required range: x >= 0

holders

object[]

required

Holders the read returned, largest balance first.

Show child attributes

top10

object

required

Balance-weighted entry and exit prices across the first 10 holders; the filtered cohort under flags.

Show child attributes

REST

Streams

Filters

Response

Errors

Authorizations

Path Parameters

Query Parameters

Response

​Filters

​Response

​Errors

Authorizations

Path Parameters

Query Parameters

Response

Filters

Response

Errors