Token holders

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

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

const url = new URL(
  "https://api.metastreams.dev/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();

{
  "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.dev/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?limit=50" \
  -H "Authorization: Bearer $API_KEY"

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

const url = new URL(
  "https://api.metastreams.dev/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();

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

The current holders of one token, ranked by balance, largest first. Pools and lockers rank with the other wallets and carry their flag, liquidity_pool or locker. spot.holders streams the same rows.

Filters

flags takes a comma-separated list of wallet classifications, such as bundler,insider. A holder is kept when it carries at least one of them. A holder has no trade route, so fomo keeps wallets flagged fomo.
trader takes one wallet address, and keeps only that wallet’s row.
period picks the span of the trading figures. lifetime, the default, covers every round trip the wallet made on the token. cycle covers the open round trip: everything since the wallet last held none of the token.
limit sets how many rows return. It is 30 by default, and the API clamps it to 1–150 rather than refusing it.

Response

A response carries holders, holderCount and top10. It has no cursor: one read returns the largest holders, up to limit.

holders lists the rows. rank is 1-based. Under flags, it ranks within the kept wallets.
holderCount is the token’s total holder count. It does not change with limit or flags. It counts trading wallets only, so it can be lower than a list that includes pools.
top10 holds avgEntryPrice and avgExitPrice, weighted by balance, across the first 10 rows returned. Each is null when no row has one.

Volumes, token totals, trade counts, entry and exit prices and realizedPnl cover the period. balance, supplyPct, nativeBalance and funding describe the wallet now. With period=cycle, avgEntryPrice is the cost basis of the open position. A row leaves out flags, platforms and identities when they are empty. A row carries no value and no unrealized PnL. Price it from the token’s price, 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.dev/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?limit=50" \
  -H "Authorization: Bearer $API_KEY"

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

const url = new URL(
  "https://api.metastreams.dev/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();

{
  "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 the API key as Authorization: Bearer <key>.

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: cycle, the open round trip, or lifetime, every round trip. 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