> ## Documentation Index > Fetch the complete documentation index at: https://docs.metastreams.dev/llms.txt > Use this file to discover all available pages before exploring further. # A token's current holders, largest balance first, optionally narrowed to wallet classifications. > Pools and lockers rank here and carry their flag. `holderCount` stays the token's total under `flags`. ## OpenAPI ````yaml /specs/openapi.json get /v1/tokens/{chain}/{address}/holders openapi: 3.1.0 info: title: Metastreams API description: >- Click's B2B market-data API. Amounts are decimal strings, timestamps are Unix milliseconds, and every field name is camelCase. license: name: Proprietary identifier: Proprietary version: 1.0.0 servers: - url: https://{host} variables: host: default: api.metastreams.dev description: API host. security: - bearerKey: [] paths: /v1/tokens/{chain}/{address}/holders: get: tags: - tokens summary: >- A token's current holders, largest balance first, optionally narrowed to wallet classifications. description: >- Pools and lockers rank here and carry their flag. `holderCount` stays the token's total under `flags`. operationId: token_holders parameters: - name: chain in: path description: Chain the resource lives on. required: true schema: $ref: '#/components/schemas/SpotChain' - name: address in: path description: Token mint or contract address. required: true schema: type: string example: So11111111111111111111111111111111111111112 - name: limit in: query description: Rows to return, clamped to 1-150; 30 when absent. required: false schema: type: integer format: int32 maximum: 150 minimum: 1 - name: trader in: query description: Restrict to one holder wallet. required: false schema: type: string - name: flags in: query description: >- Wallet classifications to keep, comma-separated. Absent or empty keeps every holder. required: false schema: type: string example: bundler,insider - name: period in: query description: >- Span the trading figures cover: `cycle`, the open round trip, or `lifetime`, every round trip. `lifetime` when absent. required: false schema: $ref: '#/components/schemas/HolderPeriod' responses: '200': description: >- Current holders, largest balance first; an unknown token answers an empty list. headers: X-Credits-Cost: schema: type: integer description: >- Credits charged for this request. Zero on any non-2xx. Sent on a metered tier only. X-Credits-Remaining: schema: type: integer description: Credit balance after this request. Sent on a metered tier only. X-RateLimit-Remaining: schema: type: integer description: >- Requests left in the bucket this request spent from. Not sent with a 401. X-Request-ID: schema: type: string description: >- This request's trace ID. Echoed from the request, or generated when it sent none. content: application/json: schema: $ref: '#/components/schemas/UiTokenHolderList' '400': description: >- Unsupported chain, a malformed address or trader, an unknown flag or period, or a malformed parameter. headers: X-Credits-Cost: schema: type: integer description: >- Credits charged for this request. Zero on any non-2xx. Sent on a metered tier only. X-Credits-Remaining: schema: type: integer description: Credit balance after this request. Sent on a metered tier only. X-RateLimit-Remaining: schema: type: integer description: >- Requests left in the bucket this request spent from. Not sent with a 401. X-Request-ID: schema: type: string description: >- This request's trace ID. Echoed from the request, or generated when it sent none. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing or invalid API key. headers: X-Credits-Cost: schema: type: integer description: >- Credits charged for this request. Zero on any non-2xx. Sent on a metered tier only. X-Credits-Remaining: schema: type: integer description: Credit balance after this request. Sent on a metered tier only. X-RateLimit-Remaining: schema: type: integer description: >- Requests left in the bucket this request spent from. Not sent with a 401. X-Request-ID: schema: type: string description: >- This request's trace ID. Echoed from the request, or generated when it sent none. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '402': description: >- The organization's credits this billing period reach its plan's limit. headers: X-Credits-Cost: schema: type: integer description: >- Credits charged for this request. Zero on any non-2xx. Sent on a metered tier only. X-Credits-Remaining: schema: type: integer description: Credit balance after this request. Sent on a metered tier only. X-RateLimit-Remaining: schema: type: integer description: >- Requests left in the bucket this request spent from. Not sent with a 401. X-Request-ID: schema: type: string description: >- This request's trace ID. Echoed from the request, or generated when it sent none. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: The key is valid, but its plan excludes this endpoint. headers: X-Credits-Cost: schema: type: integer description: >- Credits charged for this request. Zero on any non-2xx. Sent on a metered tier only. X-Credits-Remaining: schema: type: integer description: Credit balance after this request. Sent on a metered tier only. X-RateLimit-Remaining: schema: type: integer description: >- Requests left in the bucket this request spent from. Not sent with a 401. X-Request-ID: schema: type: string description: >- This request's trace ID. Echoed from the request, or generated when it sent none. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. X-Credits-Cost: schema: type: integer description: >- Credits charged for this request. Zero on any non-2xx. Sent on a metered tier only. X-Credits-Remaining: schema: type: integer description: Credit balance after this request. Sent on a metered tier only. X-RateLimit-Remaining: schema: type: integer description: >- Requests left in the bucket this request spent from. Not sent with a 401. X-Request-ID: schema: type: string description: >- This request's trace ID. Echoed from the request, or generated when it sent none. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Unexpected server failure. headers: X-Credits-Cost: schema: type: integer description: >- Credits charged for this request. Zero on any non-2xx. Sent on a metered tier only. X-Credits-Remaining: schema: type: integer description: Credit balance after this request. Sent on a metered tier only. X-RateLimit-Remaining: schema: type: integer description: >- Requests left in the bucket this request spent from. Not sent with a 401. X-Request-ID: schema: type: string description: >- This request's trace ID. Echoed from the request, or generated when it sent none. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: Dependency down or maintenance. headers: X-Credits-Cost: schema: type: integer description: >- Credits charged for this request. Zero on any non-2xx. Sent on a metered tier only. X-Credits-Remaining: schema: type: integer description: Credit balance after this request. Sent on a metered tier only. X-RateLimit-Remaining: schema: type: integer description: >- Requests left in the bucket this request spent from. Not sent with a 401. X-Request-ID: schema: type: string description: >- This request's trace ID. Echoed from the request, or generated when it sent none. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: SpotChain: type: string description: >- Chain slug. One spelling per chain, in paths and bodies alike. Only a chain with spot data is published. enum: - solana - base - bsc - robinhood - arc HolderPeriod: type: string description: >- The span a holder row's trading figures cover: `lifetime`, every round trip, or `cycle`, the open one. `lifetime` when absent. enum: - cycle - lifetime UiTokenHolderList: type: object description: >- `GET /v1/tokens/{chain}/{address}/holders` response: current holders, largest balance first. required: - holders - holderCount - top10 properties: holderCount: type: integer format: int64 description: >- 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. minimum: 0 holders: type: array items: $ref: '#/components/schemas/UiSpotHolder' description: Holders the read returned, largest balance first. top10: $ref: '#/components/schemas/UiHolderCohortStats' description: >- Balance-weighted entry and exit prices across the first 10 holders; the filtered cohort under `flags`. ErrorEnvelope: type: object description: The complete error response body — every error is exactly this. required: - error properties: error: $ref: '#/components/schemas/ErrorDetail' description: The error. UiSpotHolder: type: object description: >- One wallet's holding and trading figures on one token. Volumes, token totals, trade counts, entry and exit prices and realized PnL cover the read's `period`. required: - address - balance - supplyPct - buyVolume - tokensBought - buyCount - sellVolume - tokensSold - sellCount - realizedPnl - remainingPct - funding properties: address: type: string description: Wallet address. avgEntryMarketCap: oneOf: - type: 'null' - $ref: '#/components/schemas/UiMoney' description: >- Size-weighted market cap across the wallet's buys; `null` when none was recorded. avgEntryPrice: oneOf: - type: 'null' - $ref: '#/components/schemas/UiMoney' description: >- Entry price per token over the period; `null` before the period's first buy. `cycle` reads the open position's cost basis, and `lifetime` averages every buy. avgExitMarketCap: oneOf: - type: 'null' - $ref: '#/components/schemas/UiMoney' description: >- Size-weighted market cap across the wallet's sells; `null` when none was recorded. avgExitPrice: oneOf: - type: 'null' - $ref: '#/components/schemas/UiMoney' description: >- Volume-weighted exit price over the period; `null` until the wallet sells in it. balance: $ref: '#/components/schemas/Decimal' description: Token units the wallet holds now. buyCount: type: integer format: int32 description: Buy trades over the period. minimum: 0 buyVolume: $ref: '#/components/schemas/UiMoney' description: Spent buying this token over the period. firstPurchaseAt: oneOf: - type: 'null' - $ref: '#/components/schemas/UnixMilliseconds' description: >- The wallet's first buy of this token; `null` for a wallet that only received transfers. flags: type: array items: type: string description: >- A flag the classifier put on the wallet. This is an open enumeration: the classifier learns new flags, so keep a value you do not recognize. examples: - bundler - sniper - insider - dev - fresh - whale - kol - liquidity_pool - locker - pro_trader - system - fomo - phishing funding: $ref: '#/components/schemas/UiWalletFunding' description: >- The wallet's first inbound funding. Always present; its status says whether the lookup has settled. identities: type: array items: $ref: '#/components/schemas/UiWalletIdentity' description: The wallet's resolved identities, one element per source. nativeBalance: oneOf: - type: 'null' - $ref: '#/components/schemas/Decimal' description: >- The wallet's balance of the chain's native asset; `null` until the chain reports one. platforms: type: array items: $ref: '#/components/schemas/UiPlatform' description: The wallet's trading-platform identities. rank: type: - integer - 'null' format: int64 description: >- 1-based rank in the requested ordering; a `flags` filter ranks within the filtered cohort. Absent on live `spot.holders` updates. minimum: 0 realizedPnl: $ref: '#/components/schemas/UiMoney' description: Profit or loss the wallet locked in by selling over the period. remainingPct: $ref: '#/components/schemas/Decimal' description: Share of its peak holdings the wallet still holds, 0-100. sellCount: type: integer format: int32 description: Sell trades over the period. minimum: 0 sellVolume: $ref: '#/components/schemas/UiMoney' description: Received from selling this token over the period. supplyPct: $ref: '#/components/schemas/Decimal' description: Share of total supply the wallet holds, 0-100. tokensBought: $ref: '#/components/schemas/Decimal' description: Token units bought over the period, including any sold since. tokensSold: $ref: '#/components/schemas/Decimal' description: Token units sold over the period. UiHolderCohortStats: type: object description: Balance-weighted entry and exit prices across a holder cohort. properties: avgEntryPrice: oneOf: - type: 'null' - $ref: '#/components/schemas/UiMoney' description: >- Balance-weighted entry price across the cohort; `null` when no holder has one. avgExitPrice: oneOf: - type: 'null' - $ref: '#/components/schemas/UiMoney' description: >- Balance-weighted exit price across the cohort; `null` when no holder has one. ErrorDetail: type: object description: The `error` object inside the envelope. required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' description: >- Stable, machine-readable. Clients switch on this, never on `message`. details: description: Optional; shape is fixed per code. message: type: string description: |- Human-readable, written for the integrating developer: `[What happened]. [What to do next — if actionable].` UiMoney: type: object description: >- A chain-denominated value with its USD equivalent. The enclosing object carries the `chain` that names `native`'s unit. required: - native properties: native: $ref: '#/components/schemas/Decimal' description: Value in the owning chain's gas asset. usd: oneOf: - type: 'null' - $ref: '#/components/schemas/Decimal' description: Value in USD; `null` when the native asset is unpriced. Decimal: type: string format: decimal description: An exact decimal, as a string. example: '123.456789' UnixMilliseconds: type: integer format: int64 description: An instant, as milliseconds since the Unix epoch. UiWalletFunding: type: object description: A wallet's first inbound funding. required: - status properties: address: type: - string - 'null' description: Funder wallet or exchange address. amount: oneOf: - type: 'null' - $ref: '#/components/schemas/Decimal' description: Amount received, denominated in `asset`. asset: type: - string - 'null' description: Asset the funding moved; `null` for the chain's native asset. sourceKind: oneOf: - type: 'null' - $ref: '#/components/schemas/FundingSourceKind' description: What the funder is (exchange, bridge, wallet, …). sourceLabel: type: - string - 'null' description: Display label for the funder, e.g. an exchange name. status: $ref: '#/components/schemas/FundingStatus' description: Whether the lookup has settled. symbol: type: - string - 'null' description: Display ticker of `asset`. timestamp: oneOf: - type: 'null' - $ref: '#/components/schemas/UnixMilliseconds' description: When the funding transfer occurred. tx: type: - string - 'null' description: The funding transaction's signature or hash. UiWalletIdentity: type: object description: One source's resolved profile for a trade's trader. required: - source properties: avatar: type: - string - 'null' description: >- CDN URL of the avatar to render; `null` until the picture is mirrored. displayName: type: - string - 'null' description: Human-readable name to render. farcaster: type: - string - 'null' description: The wallet's Farcaster handle, where the source links one. handle: type: - string - 'null' description: The wallet's handle on the source. source: $ref: '#/components/schemas/IdentitySource' description: Who resolved this identity. telegram: type: - string - 'null' description: The wallet's Telegram handle, where the source links one. twitter: type: - string - 'null' description: The wallet's bare X handle, where the source links one. UiPlatform: oneOf: - type: object description: >- fomo.family, the terminal that routed the trade. The trader's profile is the `fomoscan` element of `identities`. required: - platform properties: platform: type: string enum: - fomo - type: object description: >- A token's DexScreener listing; present only while its profile is paid. required: - isPaid - platform properties: isPaid: type: boolean description: Whether the token's DexScreener profile is paid. paidAt: oneOf: - type: 'null' - $ref: '#/components/schemas/UnixMilliseconds' description: Earliest profile payment time. platform: type: string enum: - dexScreener - type: object description: Axiom. required: - platform properties: platform: type: string enum: - axiom - type: object description: '"Banana Gun".' required: - platform properties: platform: type: string enum: - bananaGun - type: object description: Bloom. required: - platform properties: platform: type: string enum: - bloom - type: object description: '"BONKbot".' required: - platform properties: platform: type: string enum: - bonkbot - type: object description: BtcTurk. required: - platform properties: platform: type: string enum: - btcTurk - type: object description: BullX. required: - platform properties: platform: type: string enum: - bullX - type: object description: Click's own router, identified by its fee vault. required: - platform properties: platform: type: string enum: - click - type: object description: '"GMGN".' required: - platform properties: platform: type: string enum: - gmgn - type: object description: '"Lucky Block".' required: - platform properties: platform: type: string enum: - luckyBlock - type: object description: Maestro. required: - platform properties: platform: type: string enum: - maestro - type: object description: '"Manifold Trading".' required: - platform properties: platform: type: string enum: - manifoldTrading - type: object description: '"MEVX".' required: - platform properties: platform: type: string enum: - mevx - type: object description: Mintech. required: - platform properties: platform: type: string enum: - mintech - type: object description: Nighthawk. required: - platform properties: platform: type: string enum: - nighthawk - type: object description: Nova. required: - platform properties: platform: type: string enum: - nova - type: object description: '"OX.FUN".' required: - platform properties: platform: type: string enum: - oxFun - type: object description: Padre. required: - platform properties: platform: type: string enum: - padre - type: object description: PepeBoost. required: - platform properties: platform: type: string enum: - pepeBoost - type: object description: Phantom. required: - platform properties: platform: type: string enum: - phantom - type: object description: Photon. required: - platform properties: platform: type: string enum: - photon - type: object description: SexBotSolana. required: - platform properties: platform: type: string enum: - sexBotSolana - type: object description: Shuriken. required: - platform properties: platform: type: string enum: - shuriken - type: object description: '"SOL Sniper Bot".' required: - platform properties: platform: type: string enum: - solSniperBot - type: object description: '"Sol Trading Bot".' required: - platform properties: platform: type: string enum: - solTradingBot - type: object description: Trojan. required: - platform properties: platform: type: string enum: - trojan description: >- A platform attached to a token, a wallet, or a trade. The fieldless variants are trading terminals. Each doc gives the producer string its variant maps from. ErrorCode: type: string description: |- Every wire error code the API can return. Append-only: a new code is non-breaking, since clients fall back on the HTTP status for one they do not recognize, and a published code is never renamed or removed. enum: - UNAUTHORIZED - FORBIDDEN - VALIDATION_ERROR - UNSUPPORTED_CHAIN - NOT_FOUND - RATE_LIMITED - CREDITS_EXHAUSTED - INTERNAL_ERROR - SERVICE_UNAVAILABLE - RANGE_TOO_LARGE - INVALID_CREDENTIALS - ORIGIN_NOT_ALLOWED - NOT_ORG_MEMBER - MEMBERSHIP_INACTIVE - EMAIL_NOT_VERIFIED - EMAIL_TAKEN - ALREADY_MEMBER - INVITATION_ALREADY_SENT - INVITATION_ALREADY_ACCEPTED - LAST_ADMIN - CANNOT_REMOVE_SELF - KEY_LIMIT_REACHED - TOKEN_EXPIRED - PAYLOAD_TOO_LARGE - UNSUPPORTED_MEDIA_TYPE - IMAGE_TOO_LARGE FundingSourceKind: type: string description: Whether a known exchange or another wallet funded the creator. enum: - cex - wallet FundingStatus: type: string description: Whether the creator wallet's funding lookup has settled. enum: - unresolved - resolved IdentitySource: type: string description: >- Who resolved a trader's identity. The set grows; keep a value you do not recognize. enum: - codex - fomo - pump - gmgn - axiom - unknown securitySchemes: bearerKey: type: http scheme: bearer description: 'Send the API key as `Authorization: Bearer `.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.