--- title: "Token buyer-quality score" method: GET path: "/tokens/{mint}/buyer-quality" tags: ["Tokens"] --- # Token buyer-quality score `GET /tokens/{mint}/buyer-quality` ## Request - Base URL: `https://madeonsol.com/api/v1` - URL: `https://madeonsol.com/api/v1/tokens/{mint}/buyer-quality` - Auth: HTTP bearer Composite 0-100 score for the top 20 early buyers of a token. Base = avg 7d winrate of non-bot buyers with ≥3 tokens; + KOL bonus, − bundle/bot penalty. 5-minute LRU cache per mint. A mint with no captured early buyers is NOT a 404: it returns a neutral placeholder (score 50, confidence insufficient_data, signal neutral, zeroed breakdown) with `note: "Insufficient buyer data"` and a `coverage` block that says whether the mint is outside the launchpad write-gate. `confidence` counts only buyers whose win rate actually fed the score (`breakdown.qualified_win_rate_wallets`); a cohort of wallets with history but no usable win rates is `insufficient_data`, not high confidence. For bulk scoring use `POST /tokens/batch/buyer-quality`. ## Path parameters - `mint` string, required ## Query parameters - `include_balances` boolean ## Response `200` OK - BuyerQuality - `mint` string - `score` number: 0-100 composite buyer-quality score - `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` 'positive' | 'neutral' | 'negative' - `breakdown` object - `alpha_wallet_count` integer - `kol_count` integer - `bundle_buyer_count` integer - `avg_historical_win_rate` number, nullable: null when no buyer's win rate qualified (confidence insufficient_data) - `bot_dominated` boolean - `wallets_with_history` integer: Buyers with ≥3 tokens of history (cohort identification — not predictive) - `qualified_win_rate_wallets` integer: Buyers whose win rate fed the score — the basis of confidence - `dump_cluster_count` integer: First-20 buyers on the rolling dump-cluster list (wallets whose 5+ recent first-20 appearances are exclusively on tokens that peaked <15 min after deploy; trailing 42d, refreshed daily). Out-of-sample: 3+ such wallets predicted a sub-15-min peak 94% of the time vs 61% base. Informational — does not move the score. - `recycled_early_buyer_count` integer: First-20 buyers with 5+ recent first-20 cohort appearances of any kind. The count alone predicts nothing; a heavily recycled cohort with dump_cluster_count 0 historically leans runner. - `cached_at` string, date-time - `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). - `note` string: Present only when no early-buyer data exists for the mint — the score is then a neutral 50 placeholder ("Insufficient buyer data"); check coverage to tell 'no early buyers captured' from 'mint outside the write-gate'. - `signal_stats` object: Present only when breakdown.dump_cluster_count ≥ 1 and the daily signal-performance snapshot has a bucket for it. The live, out-of-sample efficacy of that value, so the raw count is readable. - `dump_cluster_count` object - `value` integer: The token's own dump_cluster_count. - `bucket` 'k>=1' | 'k>=3' | 'k>=5': Most specific cumulative-threshold bucket the value qualifies for. - `outcome` 'dump' | 'runner': Outcome the hit rate is measured against. - `hit_rate` number: P(outcome | bucket), 0-1. - `base_rate` number: P(outcome | all tokens), 0-1. - `lift` number: hit_rate / base_rate. - `sample_n` integer - `window_days` integer - `as_of` string, date-time: Snapshot time of the signal_performance row. - `summary` string - `dump_cluster_held_now` object: Only with include_balances=true (PRO+, 2026-10-15, TR-09): the early buyers counted in dump_cluster_count and what they hold NOW from balances. Totals only when every member was read. - `cohort_size` integer - `members` integer: Dump-cluster members among the early buyers (= dump_cluster_count). - `held_now` object: Same shape as the bundle held_now of this chain: source, checked_at, wallets, verified_wallets, holding_wallets, complete, incomplete_reason, tokens_held_raw, tokens_held, held_pct_of_supply (ratio), supply_basis. - `wallets` object[] - `wallet` string - `balance_now` object, nullable - `note` string ## Other responses - `401`: Missing or invalid API key, or an expired free-tier key. Authentication-stage error: no `X-RateLimit-*` headers, no `_rid`. - `403`: include_balances=true needs PRO. - `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`: The API-key or subscription lookup could not be answered (authentication stage). Retryable and not your fault: it is never counted as a failed authentication. Honour `Retry-After`; no `X-RateLimit-*`, no `_rid`. --- [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)