--- title: "Comprehensive per-mint snapshot" method: GET path: "/token/{mint}" tags: ["Tokens"] --- # Comprehensive per-mint snapshot `GET /token/{mint}` ## Request - Base URL: `https://madeonsol.com/api/v1` - URL: `https://madeonsol.com/api/v1/token/{mint}` - Auth: HTTP bearer Price (VWAP from our DEX firehose), market cap, 24h volume + trade count, `liquidity_to_mc_ratio` (thinness gauge), `launchpad` of origin (`pumpfun`/`launchlab`/`bags`, null when unknown), `launch_cohort_sol` + `launch_cohort_size` (total SOL the first-20 buyers deployed — a heavily-bought open leans dump-prone), `name`/`symbol`, `image_url` + `socials` {website, twitter, telegram, discord} + `description` (from the token URI JSON, resolved within minutes of first trade; null until resolved), `twitter_reuse` {handle, mints_same_handle, mints_same_url} (how many OTHER mints reuse this X handle / exact URL — null = unknown, not zero), `early_buyer_exit` {cohort, still_holding, sold, still_holding_pct} (first-20 buyers still holding vs sold, from confirmed swaps), deployer reputation, KOL smart-money activity, `first_seen_at` + `age_seconds`, and `is_blacklisted` + `blacklist_category` — all in one call. **ULTRA** adds wallet addresses inside `kol_activity.top_buyers[]`. Available on every tier (a free taster of the snapshot data); the filterable `/tokens` directory and the `/tokens/{mint}/*` analytics are PRO/ULTRA. ## Path parameters - `mint` string, required ## Query parameters - `include` string ## Response `200` OK - object - `token` object - `mint` string - `name` string, nullable - `symbol` string, nullable - `image_url` string, nullable: Off-chain metadata resolved from the token URI JSON; null until resolved - `socials` object - `website` string, nullable - `twitter` string, nullable - `telegram` string, nullable - `discord` string, nullable - `twitter_reuse` object, nullable: null = unknown (no twitter / socials unresolved), not zero - `handle` string, nullable - `mints_same_handle` integer - `mints_same_url` integer - `description` string, nullable - `price_usd` number, nullable - `price_sol` number, nullable - `market_cap` number, nullable - `vwap_price_usd` number, nullable - `vwap_price_sol` number, nullable - `vwap_status` 'ok' | 'unavailable' | 'no_price_reference' | 'implausible_vs_price': Why vwap_price_usd / vwap_price_sol are null, or ok. A 15-minute VWAP more than 1000x away from the price it is shipped with is withheld (implausible_vs_price) instead of served (2026-10-15, #652). - `fdv_usd` number, nullable - `liquidity_usd` number, nullable - `liquidity_to_mc_ratio` number, nullable - `primary_dex` string, nullable - `launchpad` 'pumpfun' | 'launchlab' | 'bags' | 'null', nullable - `primary_pool_address` string, nullable - `is_token_2022` boolean, nullable: null = no mc-tracker observation (unknown), never false - `transfer_fee_bps` integer, nullable: null = unknown (no observation) — NOT "no fee" - `mint_authority_revoked` boolean, nullable - `freeze_authority_revoked` boolean, nullable - `burn_detected` boolean, nullable: DEPRECATED meaning: `true` when the token MINT's on-chain supply decreased (a token burn, measured by mc-tracker's supply-drift monitor). It is NOT LP-burn evidence and never means liquidity cannot be removed. null = no mc-tracker observation (unknown). - `token_supply_burn_detected` boolean, nullable: The mint's supply decreased (token burn). Not LP evidence. - `lp_burn_status` 'verified' | 'not_verified' | 'unknown': LP burn/lock evidence: `verified` only with measured LP-token custody (lp_burnt_pct ≥ 99). No Solana writer populates LP custody yet, so today every token is `unknown`. A token-supply burn is never promoted to an LP claim. - `volume_24h_usd` number, nullable - `volume_24h_sol` number, nullable - `trades_24h` integer, nullable - `price_source` 'mc_tracker' | 'dex_stream' | 'null', nullable: Which pipeline produced price_usd/price_sol; null when there is no price - `price_observed_at` string, date-time, nullable: Last trade observed BY THE SELECTED price source — the price's own age anchor - `price_age_seconds` integer, nullable: Seconds since price_observed_at (null when the source carries no timestamp) - `price_is_stale` boolean, nullable: true when price_age_seconds > 900; null (unknown) when a price exists but its source has no observation time — never false without an observation; false when there is no price - `last_trade_at` string, date-time, nullable: Newest trade observed by ANY source (mc-tracker or dex-stream). Not a price-age anchor — use price_observed_at - `first_seen_at` string, date-time, nullable - `age_seconds` integer, nullable - `is_blacklisted` boolean, nullable: null = the blacklist lookup failed (unknown) — never "not blacklisted" - `blacklist_category` string, nullable - `launch_cohort_sol` number, nullable: Total SOL the first-20 buyers deployed on their first buy - `launch_cohort_size` integer, nullable: null = the cohort lookup failed; 0 = no cohort rows - `early_buyer_exit` object, nullable: First-20 buyer cohort exit status from confirmed swaps; null when the cohort is unknown - `cohort` integer - `still_holding` integer - `sold` integer - `still_holding_pct` number - `deployer` object, nullable: Creator + live reputation. Resolved from `deployer_tokens` (bonded) or `pending_deploys` (not yet bonded — ~98% of fresh launches). null ⇒ read `deployer_identity` for why (unknown creator vs failed lookup). `history_status` other than `established` means the bonding rate is not a track record yet (a first launch is "0 of 1", not a serial dumper). - `wallet` string - `address` string: Same value as wallet (contract name) - `tier` string - `bonding_rate` number - `total_deployed` integer - `total_bonded` integer - `recent_bond_rate` number - `identity_status` 'resolved' - `identity_source` 'deployer_tokens' | 'pending_deploys' - `history_status` 'new_in_our_index' | 'limited_history' | 'reputation_pending' | 'established' - `first_seen_at` string, date-time, nullable: First deploy OBSERVED in our capture — not the wallet's first launch anywhere - `observed_launch_count` integer - `resolved_outcome_count` integer: Resolved outcomes (bonds + dumps) we hold for this creator - `stats_computed_at` string, date-time, nullable - `deployer_identity` object: Always present. Explains a null `deployer`: `unknown` = both lookups succeeded and found no creator; `lookup_failed` = a lookup errored (retry — NOT "no deployer"). - `identity_status` 'resolved' | 'unknown' | 'lookup_failed' - `history_status` 'new_in_our_index' | 'limited_history' | 'reputation_pending' | 'established' | 'null', nullable - `address` string, nullable - `source` 'deployer_tokens' | 'pending_deploys' | 'null', nullable - `kol_activity` object: Complete 7-day aggregate over every tracked-KOL trade (SQL, not a row sample). `status: unavailable` = the aggregate read failed: every figure is null, never zero/neutral. - `status` 'ok' | 'unavailable' - `buying_kols` integer, nullable: Distinct KOL wallets with ≥1 buy in the window (exact) - `selling_kols` integer, nullable - `net_flow_sol` number, nullable - `signal` 'accumulating' | 'distributing' | 'neutral' | 'null', nullable - `top_buyers` object[]: Largest KOL buyers by SOL bought over the whole window (≤ 10, complete ranking) - `name` string - `wallet` string: ULTRA only - `sol_amount` number - `window_hours` integer - `window_start` string, date-time, nullable - `computed_at` string, date-time, nullable - `last_trade_at` string, date-time, nullable - `unique_kols` integer, nullable - `unique_wallets` integer, nullable - `buys` integer, nullable - `sells` integer, nullable - `buy_sol` number, nullable - `sell_sol` number, nullable - `counts_basis` 'complete_window' | 'null', nullable - `data_status` object: Per-block read status. `unavailable` = that lookup failed; its fields are null (unknown), never a neutral default like 0 KOLs or not-blacklisted. - `market` 'ok' | 'unavailable' - `deployer` 'ok' | 'unavailable' - `kol_activity` 'ok' | 'unavailable' - `first_seen` 'ok' | 'unavailable' - `blacklist` 'ok' | 'unavailable' - `metadata` 'ok' | 'unavailable' - `launch_cohort` 'ok' | 'unavailable' - `sniper_footprint` 'ok' | 'unavailable' - `volume_candles` 'ok' | 'unavailable' - `twitter_reuse` 'ok' | 'unavailable' - `mc_change_pct` object, nullable: Present only when history exists. Keys: 5m, 15m, 1h, 2h, 4h - `volume_usd` object, nullable: Present only when history exists. Keys: 5m, 15m, 1h, 2h, 4h - `mev_volume_pct` object, nullable: Present only when history exists. Keys: 5m, 15m, 1h, 2h, 4h - `history_age_seconds` integer, nullable: Present only when history exists - `as_of` string, date-time: Snapshot assembly time — NOT the observation time of any field (see price_observed_at, kol_activity.computed_at, deployer.stats_computed_at) - `buyer_quality` object: Present when include=buyer_quality — see /tokens/{mint}/buyer-quality - `deployer_profile` object: Present when include=deployer — see /deployer-hunter/{wallet} - `include_errors` object, nullable: Per-key errors for requested includes that failed. include=deployer: 404 when the token has no known creator, 503 (retryable) when the creator lookup failed (deployer_identity.identity_status = lookup_failed) - `included` string[], nullable ## Other responses - `400`: Invalid mint. Body includes `code: invalid_mint`, `reason` (specific cause), `received`, `received_length`, `expected_length`, `example`, and `docs` URL. - `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`: Temporarily unavailable — a Postgres statement timeout while the dataset is under load or maintenance (`statement_timeout`, with `X-RateLimit-*` and `_rid`), or the API-key lookup itself unavailable (`auth_backend_unavailable`, authentication stage: no `X-RateLimit-*`, no `_rid`, not counted as a failed authentication). Always carries `Retry-After`; honour it. --- [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/96ce84657f55?raw)