---
title: "Token cap table"
method: GET
path: "/tokens/{mint}/cap-table"
tags: ["Tokens"]
---

# Token cap table

`GET /tokens/{mint}/cap-table`

## Request

- Base URL: `https://madeonsol.com/api/v1`
- URL: `https://madeonsol.com/api/v1/tokens/{mint}/cap-table`
- Auth: HTTP bearer

The token's early buyers with classification (KOL, human, bundle) AND their outcome on this token — `realized_pnl_sol`, `total_sol_bought`/`total_sol_sold`, `first_sell_at`, and `still_holding` — so you can read whether the smart early money profited and has already exited. PRO returns the top 10, ULTRA the full 20 (mv_early_buyer_pnl excludes rank-1, the deployer's own buy). Cohort scope: first 20 buyers (deployer excluded) of launches our deployer pipeline recorded at creation and tracked from that launch; mints admitted later (bags/LaunchLab persist-set, revived curves, restart-loaded history) have no early-buyer cohort, and buyers during an ingest gap are missing.

## Path parameters

- `mint` string, required

## Query parameters

- `limit` integer
- `verify_current_balances` boolean
- `include_scout_scores` boolean

## Response `200`

OK

- object
  - `mint` string
  - `buyers` object[]
    - `rank` integer
    - `wallet` string
    - `first_buy_sol` number
    - `first_buy_at` string, date-time, nullable
    - `realized_pnl_sol` number, nullable: Realized SOL PnL for this wallet on this token (FIFO cost-basis from confirmed trades).
    - `total_sol_bought` number, nullable
    - `total_sol_sold` number, nullable
    - `first_sell_at` string, date-time, nullable: When this early buyer first sold; null if never sold.
    - `still_holding` boolean: True if the wallet has not sold (first_sell_at is null).
    - `balance_now` object: Only with verify_current_balances=true.
      - `amount_raw` string
      - `decimals` integer, nullable
      - `amount` string
      - `holding` boolean
      - `token_accounts` integer
      - `slot` integer
    - `holding_status` 'verified_nonzero' | 'verified_zero': Only with verify_current_balances=true: the balance, unlike still_holding (swap ledger).
    - `exited_without_sell` boolean: Only with verify_current_balances=true: zero balance although no sell is on the swap ledger (moved out by transfer or sold off-ledger).
    - `scout_score` object, nullable: Only with include_scout_scores=true; KOL buyers only, as of first_buy_at.
      - `as_of` string, date-time
      - `first_touches_30d` integer
      - `avg_followers_4h` number, nullable
      - `swarm_3plus_pct` number, nullable
      - `swarm_5plus_pct` number, nullable
      - `scout_tier` 'S' | 'A' | 'B' | 'C', nullable
    - `is_bundle` boolean
    - `is_kol` boolean
    - `kol_name` string, nullable
    - `bot_confidence` string, nullable
    - `historical_win_rate` number, nullable: Wallet's all-time win rate (0–1), from mv_alpha_wallets.
    - `historical_pnl_sol` number, nullable
    - `historical_tokens` integer, nullable
  - `summary` object
    - `known_alpha_wallets` integer
    - `known_kols` integer
    - `bundle_buyers` integer
    - `buyer_quality_score` number: 0–100 composite quality of the early-buyer cohort.
    - `confidence` 'insufficient_data' | 'low' | 'medium' | 'high': Confidence in the PREDICTIVE inputs: counts only buyers whose win rate fed the score (≥3 tokens of history, not bot-flagged, not zero-cost-dump dominated). insufficient_data = none did — the score is the neutral-50 default plus penalties. 1 → low, 5+ → medium, 11+ → high.
    - `signal` string
    - `cohort_size` integer: Early buyers scored (≤20).
    - `still_holding` integer: Cohort members with no confirmed sell on a tracked venue (swap-ledger scoped — a plain transfer out still reads as holding).
    - `sold` integer
    - `still_holding_pct` number
  - `scout_scores_status` 'ok' | 'unavailable' | 'timeout' | 'error': Only with include_scout_scores=true. unavailable = migration 500 not applied.
  - `scout_scores_note` string: Only with include_scout_scores=true.
  - `onchain_balance_verification` object: Only with verify_current_balances=true, after EVERY scored buyer was read. Reads are not pinned to one slot (slot_min/slot_max).
    - `source` string
    - `checked_at` string, date-time
    - `slot_min` integer
    - `slot_max` integer
    - `verified_wallets` integer
    - `complete` boolean
    - `verified_still_holding` integer
    - `verified_exited` integer
    - `exited_without_sell` integer
    - `note` string
  - `ranks_completeness` object: Whether early-buyer ranks 1..20 can be trusted for this mint (COV-20). `observed_from_launch` = no firehose gap overlaps launch→last ranked buy; `gap_overlap` = a recorded ingest gap overlaps that window, so a true early buyer may be missing and later ranks shifted; `not_verified` = the check could not run; `no_ranks` = nothing ranked. Ranks are assigned to the first PERSISTED buys at or above the storage floor (`rank_basis`), so they are not necessarily the first on-chain buyers.
    - `ranks_complete` 'observed_from_launch' | 'gap_overlap' | 'not_verified' | 'no_ranks'
    - `rank_basis` 'first_persisted_buys_at_or_above_floor'
    - `window` object, nullable
      - `from` string, date-time
      - `to` string, date-time
    - `gaps_overlapping` integer
    - `open_slots` integer: Ranks 1..20 not yet assigned
    - `gaps_in_open_slots` integer: Recorded gaps after the last ranked buy (affect only the open slots)
  - `coverage` TradeCoverage: Coverage disclosure for endpoints backed by our persisted trade capture (`token_trades` / early-buyer data). Capture starts 2026-04-12 and persistence is gated to the launchpad pipeline (pump.fun, LaunchLab/bonk, bags) — it is NOT a full Solana trade history. Three separate answers (2026-09-21): `data_observed`/`in_scope` = at least one persisted row (presence, not completeness — a brand-new in-scope mint with no trades yet also reads false), `eligibility` = whether the CURRENT gate admits the subject, `completeness` = always `not_verified`. When no rows exist, zero/empty values mean 'not captured' (see eligibility for why), never 'no activity'.
    - `history_start` integer: Epoch seconds of the first persisted trade (2026-04-12).
    - `scope` string
    - `in_scope` boolean, nullable: Kept for compatibility — same value as data_observed: true = we hold ≥1 persisted trade for this subject · false = none persisted (see eligibility for why — a brand-new in-scope mint also reads false) · null = probe unavailable
    - `data_observed` boolean, nullable
    - `eligibility` 'eligible' | 'lapsed' | 'excluded' | 'unknown' | 'admitted_previously' | 'not_applicable' | 'null', nullable: Resolved against the EFFECTIVE production capture settings (refreshed every few minutes; if they cannot be confirmed the answer narrows, never widens). eligible = admitted by the current gate · lapsed = launched via our pipeline, capture window closed under the current settings · excluded = blacklisted · unknown = no evidence the gate admits it (most likely outside the launchpad pipeline; basis capture_state_unavailable = settings could not be confirmed, no claim either way) · admitted_previously = persisted rows prove past admission, current status not established · not_applicable = wallet subjects · null = lookup failed
    - `eligibility_basis` string, nullable: Evidence behind eligibility (e.g. unresolved_launch, recently_bonded, revived_curve, pipeline_known, launchlab_pool, bags_vanity_mint, launchpad_proven, resolved_launch, bonded_over_7d, revival_expired, blacklisted, persisted_rows, capture_state_unavailable, lookup_failed)
    - `completeness` 'not_verified'
    - `size_floor` object: Persistence size floor of the same write path (added 2026-09-30). Buys under 0.05 SOL (under $3.50 when paid in USDC/USDT) are not stored; sells that receive SOL are kept at any size. Live streams, prices and candles are not subject to it.
      - `min_sol` number
      - `min_stable_usd` number
      - `applies_to` string
    - `note` string: How to read the values (always present since 2026-09-21: eligibility-specific when no rows exist, a completeness caveat when they do).

## Other responses

- `401`: Missing or invalid API key, or an expired free-tier key. Authentication-stage error: no `X-RateLimit-*` headers, no `_rid`.
- `403`: Forbidden. One of: the key's tier is below this endpoint's or parameter's gate (`tier_required` with an `upgrade` block); the public demo key used outside its allow-list (`demo_key_endpoint_not_allowed`); an invalid or revoked key; an origin-restricted key called from a disallowed origin (`code` `origin_not_allowed` / `origin_required`). `X-RateLimit-*` headers are present only on `tier_required`.
- `429`: Too many requests. Every 429 carries `Retry-After`. A quota 429 (`rate_limit_exceeded`, with `X-RateLimit-*`), a heavy-query concurrency 429 (`error_kind` `concurrency`/`capacity`), or the per-IP authentication-failure block (30 failed auths/min; plain `error` + `retry_after_seconds`, no `X-RateLimit-*`).
- `500`: Unexpected server error from the route (`Internal server error`, with `_rid`). Safe to retry with backoff. A failed API-key lookup is a 503 `auth_backend_unavailable`, never a 500.
- `503`: current_balance_verification_unavailable: with verify_current_balances=true, at least one balance read failed (retry_after_seconds).

---

[API](https://skmtc.dev/madeonsol/apis/madeonsol-api.md) · [All operations](https://skmtc.dev/madeonsol/apis/madeonsol-api/llms.txt) · [OpenAPI document](https://skmtc.dev/madeonsol/apis/madeonsol-api/revisions/d9531a28d83b?raw)