# mcp-server-madeonsol

> **Unreleased ShredPrism migration (PR #420):** sniper becomes ULTRA/BUSINESS/ENTERPRISE API-key only. The keyless sniper route returns HTTP 410 without a new payment. Early observations are not proof of execution. The changes below describe the release candidate; package publication and source activation are still pending. Historical release notes describe earlier behavior.


[![npm version](https://img.shields.io/npm/v/mcp-server-madeonsol?style=flat-square)](https://www.npmjs.com/package/mcp-server-madeonsol)
[![npm downloads](https://img.shields.io/npm/dm/mcp-server-madeonsol?style=flat-square)](https://www.npmjs.com/package/mcp-server-madeonsol)
[![Smithery](https://img.shields.io/badge/Smithery-listed-blueviolet?style=flat-square)](https://smithery.ai/servers/madeonsol/solana-kol-intelligence)
[![Glama](https://glama.ai/mcp/servers/madeonsol/mcp-server-madeonsol/badges/score.svg)](https://glama.ai/mcp/servers/madeonsol/mcp-server-madeonsol)
[![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet?style=flat-square)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)

> ⚡ **[Install via Smithery](#install-via-smithery-one-line)** · 🤖 **[Use in Claude Desktop](#claude-desktop)** · 🖱️ **[Use in Cursor](#cursor)** · 📚 **[API docs](https://madeonsol.com/api-docs)** · 💰 **[Free API key](https://madeonsol.com/pricing)** · 🔎 **[On Glama](https://glama.ai/mcp/servers/madeonsol/mcp-server-madeonsol)**

MCP server for [MadeOnSol](https://madeonsol.com) Solana KOL intelligence API. Use from Claude Desktop, Cursor, or any MCP-compatible client.

<!-- Stats below are deliberate conservative floors kept in sync with the site's canonical labels (src/lib/constants.ts KOL_COUNT_LABEL / DEPLOYERS_PROFILED_LABEL / ALPHA_WALLETS_LABEL), rounded down from a live count measured on a known date and bumped only when the real count crosses the next threshold -- never the exact live number, which changes every minute. Do not replace with a live/volatile count. -->

> Real-time Solana trading intelligence: track 2,000+ KOL wallets with <3s latency on paid keys and x402 pay-per-call (free-tier live feeds are 5-min delayed), score 85K+ Pump.fun deployers, surface deshred deploy signals **~500ms before on-chain confirmation**, detect multi-KOL coordination, surface bundle-cohort holdings (which same-slot wallets still hold a token's supply), verify any wallet's CURRENT on-chain holdings straight from its token accounts, and stream every DEX trade across 9+ programs. Free tier: 200 requests/day across 40+ endpoints (live feeds 5-min delayed) — no signup payment. Get a key at [madeonsol.com/pricing](https://madeonsol.com/pricing).

> **Server update 2026-10-05 (no package change needed): realtime developer activity and USDC/USDT trade sizing.** The webhook event `dev:activity` (PRO+) and, on the Ultra DEX firehose socket, `dev_subscribe` → `dev:activity` + `dev:activity_enrichment` (same `id`) now deliver a token developer's `dev_sell`, `dev_buy`, `dev_token_transfer_out` and `dev_token_transfer_in` as they happen (a transfer is never a sell; PRO gets the developer's own events without identity fields; transfer coverage is partial, see `transfer_watch_coverage`). On `dex:trades`, a swap paid in USDC or USDT now carries `sol_amount` = the SOL equivalent of its stable leg (used by `dust`, `min_sol`, `max_sol`) plus the additive fields `sol_amount_basis` (`native_sol` | `stable_quote_equivalent` | `stable_quote_unconverted`) and `stable_quote`; `stable_quote_unconverted` means `sol_amount` 0 (size unknown). Details: [changelog](https://madeonsol.com/changelog).

> **Server update 2026-10-04 (no package change needed): copy-trade rules follow any valid source wallet.** `source_wallets` no longer have to be tracked KOL wallets: any valid Solana wallet fires, KOL membership is optional enrichment, and copy-trade sources do not use Wallet Tracker quota. Each rule reports `source_admission` (`any_wallet`) and `operational_state` (`eligible`, or an infrastructure state `monitoring_pending` / `monitoring_unavailable` / `source_capacity_unavailable`). `source_wallets_tracked` / `source_wallets_untracked` and the `untracked_source_wallets` warning are legacy fields, still filled. This supersedes the "signals fire only for tracked KOL wallets" wording in older notes below. Limits are unchanged: PRO 3 rules × 5 wallets, ULTRA 20 × 50, BUSINESS 100 × 250.

> **New in 3.6.0: deployer activity timeline.** `madeonsol_deployer_activity` binds `GET /deployer-hunter/{wallet}/activity` (PRO+, keyed `msk_` API only): one newest-first timeline of launches, the deployer's own dev buys/sells, creator transfers, fee claims, funding in and capital out, windowed on each event's own time (PRO 30 d, ULTRA 365 d, BUSINESS unbounded; page clamped to 100 / 100 / 500). History is online-only for now: the response says which families are complete and where the archive boundary is. PRO responses carry no identity block and no fee-payer address.

> **New in 3.3.0: token lock provenance.** Tool descriptions: Token lock rows carry `provider` (`identity` verified | compatible | unverified; `lock_url` always null on Solana, never constructed), `explorer` (Solana Explorer links), `price_usd`, `seconds_until_end`, `seconds_until_next_unlock` and, for Bonfida, the tranche `schedule` (server 2026-10-02). Additive only. `madeonsol_token_locks_feed` accepts `cursor` (strict keyset paging).

> **New in 3.2.0: paid tool calls recover a lost answer instead of paying again (PAY-05).** In x402 (keyless) mode a paid call whose answer is lost or pending is re-sent with the SAME proof and a payer-signed `PAYMENT-RECOVERY` header (bounded), and returns the server's stored answer. Tool results carry `_x402_payment` provenance (payment id, original/deferred, live/stored); a payment that cannot be completed returns a coded `x402_payment_error` that says not to pay again. A recovery retry never uses the `X402_MAX_*` budget. Against a server that does not offer recovery (older, or with recovery switched off) the result is the previous behaviour: a re-presented proof ends in the 409 `replay_detected` and is surfaced, never re-paid. No tool added or removed. **API-key users: no change.**

> **New in 3.1.1: tool descriptions match the API.** `madeonsol_token_risk` and `madeonsol_tokens_batch_risk` describe risk evidence for your own policy, not a verdict. `madeonsol_deployer_profile` names the real response: `is_deployer`, the nested `deployer` object (`total_tokens_deployed`, `total_bonded`, ...), `pump_stats`, `pump_tokens`, `launchpad_tokens`; an untracked wallet returns `is_deployer: false` and `deployer: null`. No tool added or removed.

> **New in 3.1.0 — copy-trade and Wallet Tracker tools match the API.** `madeonsol_copytrade_create` / `_update` accept up to 250 `source_wallets` (the BUSINESS per-rule limit; before, the tool refused anything over 50 before the server could answer). The server still enforces your own tier's limit (PRO 5, ULTRA 50, BUSINESS 250). Create, update and `madeonsol_copytrade_signals` gain the market-cap band `min_mc_usd` / `max_mc_usd`. The `only_action` description now states the real default (`buy`), and the tool descriptions say that signals fire only for tracked KOL wallets. `madeonsol_wallet_tracker_trades` gains `order` (`slot` | `block_time`) and the `before_slot` cursor, and its `action` filter is `buy` | `sell` only: `transfer_in` / `transfer_out` were always rejected by the API with 400. Use `event_type: "transfer"` for transfers. `madeonsol_copytrade_update` documents that a PATCH which sets a `webhook_url` on a rule without a signing secret returns `webhook_secret` once, and the copy-trade tools describe the `source_wallets_untracked` / `warnings[]` fields newer servers return. `madeonsol_test_webhook` gains an optional `event` (which subscribed event to sample).

> **New in 3.0.0 — BREAKING for x402 (keyless) mode only: five env vars are now required and startup FAILS instead of silently degrading (security fix, SDK-01).** Set `X402_PAY_TO`, `X402_FEE_PAYER`, `X402_MAX_AMOUNT_ATOMIC`, `X402_MAX_TOTAL_AMOUNT_ATOMIC` and `SVM_RPC_URL` alongside `SVM_PRIVATE_KEY`. Before, keyless mode signed whatever Solana USDC amount, recipient and fee payer a 402 challenge asked for. Now every challenge is checked BEFORE signing against a trusted merchant `payTo`, a trusted facilitator `feePayer` (which must differ from your wallet), the USDC mint, `solana:5eykt…` mainnet, the `exact` scheme, a per-call cap and a lifetime cap. Use the canonical values in the keyless section below; caps must be at least `20000` (0.02 USDC) per call to reach every endpoint. The budget is per client instance / process: not wallet-wide, not shared between processes, reset on a new instance or restart. Keyless requires the base URL exactly `https://madeonsol.com`. **API-key (`msk_`) users: no change, no new config.** HTTP mode still refuses wallet signers (SEC-02, unchanged).

> **New in 2.0.0 — BREAKING: HTTP mode now requires a separate token (security fix, SEC-02).** If you run this server with `MCP_TRANSPORT=http`, you must now also set `MCP_HTTP_TOKEN` (a random secret you generate) and send it as `Authorization: Bearer <token>` on **every** request, including `GET /health` and the server-card endpoint — previously, anything that could reach the bound port could call every tool using the operator's own API key with no authentication at all. HTTP mode is now hard-restricted to literal loopback (`127.0.0.1` / `::1`), rejects `Origin`/`X-Forwarded-*` headers and duplicate `Authorization`/`Host` headers outright, exposes only `POST /mcp` plus the two GET routes, and **refuses to start** if a wallet/payment signer is configured — HTTP mode can never carry a payer key. **If you use the default `stdio` transport (Claude Desktop, Cursor, most MCP clients), nothing changes — no action needed.** This is a single shared-operator-token fix, not a new multi-user or OAuth system; each HTTP caller still shares the operator's own MadeOnSol API key. Full writeup: `docs/audit/SEC02_PRIVATE_HTTP_MCP.md`.
>
> **New in 1.27.1 — the server now reports MCP `instructions`.** The `initialize` response's `instructions` field (operational guidance for the calling agent — distinct from this README/package description) was never set; directories that introspect the live server (Glama) reported "no recorded MCP instructions." No new tools; still 104 total.
>
> **New in 1.27.0 — top traders, sniper watchlist management, and two update tools (104 tools total).** Six additions found by an internal agentic-infra coverage audit. `madeonsol_token_top_traders` (`GET /tokens/{mint}/top-traders`, PRO/ULTRA) ranks a token's wallets by realized PnL or ROI, enriched with KOL/alpha-wallet identity — this endpoint already existed on the REST API and x402 rail but had no MCP tool. `madeonsol_sniper_watchlist_list` / `_add` / `_remove` (PRO+/ULTRA) manage your custom sniper-deploy watchlist (`madeonsol_sniper_recent(watchlist: true)` narrows to it) — previously only reachable via raw HTTP. `madeonsol_update_webhook` (PATCH) changes a webhook's URL, events, or active state without deleting and recreating it. `madeonsol_wallet_tracker_relabel` (PATCH) renames or clears a tracked wallet's label.
>
> **New in 1.26.0 — deployer reputation as-of a date, and creator-fee rewards.** Two new tools (PRO+, keyed `msk_` API only — no x402 route). `madeonsol_deployer_as_of` binds `GET /deployer-hunter/{wallet}/as-of`: the deployer's reputation exactly as it stood on `date` (default today, UTC) — the latest write-on-change snapshot at or before it, so an agent backtests without look-ahead bias. `snapshot.snapshot_date` can predate `date` (write-on-change); `snapshot.carried: true` marks that. No snapshot at or before `date` → `as_of: false, snapshot: null` — nothing is ever synthesized. `date` must be ≥ 2026-04-07 and not in the future. `madeonsol_deployer_rewards` binds `GET /deployer-hunter/{wallet}/rewards`: pump.fun creator-fee rewards, answered two ways that are never merged — `collected` (what actually reached the wallet: direct vault claims kept 90 days, social-handle claims, shareholder payouts on **any** token) and `attributed` (every payout on the tokens it **deployed**, split `to_self`/`to_others` + `redirected_pct`). Every money field is `{sol, usdc, usd}`; `usd` is `null` (never a silent 0) when a SOL amount exists and no SOL price was available. `top_tokens`/`top_recipients` (≤10, USD-sorted) show where attributed fees went. Works for non-deployers too (`is_deployer: false`, `attributed` empty).

> **New in 1.25.0 — token surges & revivals: momentum fires with the honest half attached.** The new `madeonsol_tokens_surges` tool binds `GET /tokens/surges` (PRO+, keyed `msk_` API only — no x402 route): every token momentum fire, newest first. Two kinds, one row shape. **`surge`** — a token < 30 min old whose market cap runs hard against its *launch* MC, in three tiers that each fire at most once per mint: `early` (≤10 min, ≥$12k, ≥3× launch), `strong` (≤30 min, ≥$30k, ≥6× launch **and** ≥2× the lowest sample of the last 3 min — it is climbing *now*), `breakout` (≤2 min, ≥$45k, ≥8×). A tier must be **sustained** (current tick *and* a sample ≥10 s older; nothing fires before 20 s of age) — a same-slot bundle marked to $475k at age 1 s is a spike, not a surge. **`revival`** — a token with no 1-minute trade candle for ≥24 h that starts trading again, confirmed **only by the tape** (≥5 buys, ≥$500 buy volume, MC ≥1.5× the pre-dormancy close), never by the price mark; `tier` is `null`. Hard gates on both: liquidity ≥$1.5k and ≥2 % of MC, and the MC gained must be **paid for** by buy volume (a price mark in a spoof pool moves MC on ~$0). Every row carries the burst `tape` (`source` candles / wallet_trades; `unique_buyers` only where the mint is in trade coverage — `wallet_data_available:false` otherwise, never an inferred zero), `kol` buyers, the first-20 `early_buyers` cohort (bundled / sold / sniper wallets), `deployer` reputation and `risk_flags[]` (`bundled_launch`, `few_buyers`, `wash_pattern`, `thin_liquidity`, `cold_deployer`, `sniper_heavy`, `early_buyers_exiting`, `sell_pressure`, `no_tape_trades`, `no_prior_price`, `mint_authority_active`, `transfer_fee` — empty means no flag raised, not verified clean). Rows ≥65 min old carry the +1 h `outcome`; `stats=1` prints per-(kind, tier) hit-rates (`up_1h_pct`, `median_peak_multiple`, `doubled_1h_pct`) — out-of-sample by construction. Filters `kind`, `tier`, `mint`, `launchpad`, `deployer_tier`, `min_mc_usd` / `max_mc_usd`, `min_buys`, `exclude_flags`, `only_clean`; cursors `since` / `before`. Pushed live on the new **`token:surges`** WS channel (events `token:surge` / `token:revival`; subscribe filters `kinds[]`, `tiers[]`, `launchpads[]`, `exclude_flags[]`, `min_mc_usd` / `max_mc_usd`, `deployer_tier[]`) and accepted by `madeonsol_create_webhook` as events `token:surge` / `token:revival` with the same filters. The response echoes the live thresholds in `definitions`.

> **New in 1.24.1 — stream tokens never expire.** `madeonsol_stream_token` (`POST /stream/token`) now returns the **same token on every call, forever**. It stops working only if your subscription lapses or you call the tool with `rotate: true` to replace it (the previous value keeps working for 60 s). `expires_at` and the new `next_refresh_at` are always `null` (kept for wire compatibility — do not schedule refreshes on them); the response gains `rotated` (boolean) and `lifetime` (string). The server never rotates on its own and never sends `token_refresh` unless you rotated; a `4001` close means "mint again" (lapsed or rotated), never a timer. Prefer `Authorization: Bearer <token>` on the WebSocket handshake — `?token=` still works and is masked in access logs.

> **New in 1.24.0 — token locks & vesting, upcoming unlocks, and pump.fun creator-fee sharing / claims.** Five new tools (all PRO+, keyed `msk_` API only — no x402 route). `madeonsol_token_locks` binds `GET /tokens/{mint}/locks`: every on-chain lock / vesting contract on a mint (Streamflow, Jupiter Lock, Bonfida vesting) with the schedule, the terms (`cancelable_by_sender` = the locker can pull it — funds are locked against the recipient, not the locker) and a live-derived view (`locked_*`, `claimable_*`, `next_unlock`) plus a `summary` with 7d / 30d forward unlock totals. `madeonsol_token_locks_feed` (`GET /tokens/locks`) is the cross-token feed of NEW contracts (cursor `pagination.next_since`, or push on WS channel **`token:locks`**), `madeonsol_token_unlocks` (`GET /tokens/unlocks`) lists upcoming unlock EVENTS (cliff / period / final / tranche) inside a 1h–90d window sorted by soonest / largest_usd / largest_pct. **LP locks are not included** — token/vesting locks only. `madeonsol_token_fee_shares` (`GET /tokens/{mint}/fee-shares`) decodes a pump.fun coin's on-chain `SharingConfig` — shareholders with `share_bps`, `is_admin`, `is_social_pda` (fees earmarked for an X identity: `social.platform` 2 = X, `user_id` = the numeric platform id, not the handle), `redirected_bps`, `is_default: true` = 100% to the creator — plus a distributions rollup and config history; `madeonsol_token_fee_claims` (`GET /tokens/fee-claims`) is the fee-event feed (`distribution` with per-address `payouts[]`, `social_claim`, `shares_created/updated/reset`, `creator_transferred`, `creator_claim` only when asked via `type=`), pushed on WS channel **`token:fee_claims`**. **Fee-event history starts 2026-08-17.** All base-unit amounts are digit **strings**; ui / usd / pct are `null` when decimals or price are unknown.

> **New in 1.23.0 — live holder census: exact holder count, labelled holders, and pools that are named, not just excluded.** The new `madeonsol_token_holders` tool binds `GET /tokens/{mint}/holders` (PRO+): every token account of the mint read from the ledger at `confirmed` and merged per owner, so `concentration.holder_count` is EXACT (distinct non-zero owners minus pools / bonding curves / burns) — never a trade-derived estimate; it is `null` only when the provider refuses the census for a mega-cap, in which case you get the top-20 view and `source.census_fallback_reason` says so. Each disclosed owner carries our labels (`deployer` / `kol` / `early_buyer` / `bundle` / `bot` / `dump_cluster` — empty means unknown to us, not clean), and `excluded[]` NAMES what was taken out of the circulating denominator: `reason` = `pool` (with `dex` + `pool_address`), `bonding_curve` (pump.fun / LaunchLab), `burn`, or `program_account` only when we genuinely cannot attribute the PDA; `pool_pct` / `burned_pct` / `program_pct` split the exclusion. Amounts are raw u64 **strings**. Disclosure: PRO ranks 1–10, ULTRA 1–50, BUSINESS 1–100 — the maths is tier-independent. Big tokens take 5–30 s upstream: you get `503 holder_scan_in_progress` with `retry_after_seconds: 20` while the scan finishes into the cache, and the retry is instant.

> **New in 1.22.0 — two prices on the trade tape, and the right one is now the default.** The trade tape now tells you what a trade actually cost. `price_sol`/`price_usd` on each trade are THIS trade's executed price — `sol_amount / token_amount`, reconciling exactly with the amounts on the same row and with the PnL endpoints. Because `sol_amount` is the wallet's net SOL movement, that is the trader's all-in effective rate: swap fee and any account rent included, not the pool mid. The market-cap tracker's canonical pool price moved to the new **`market_price_sol`/`market_price_usd`** fields — it is sampled once per token per pool update, so every trade in the same slot shares it. Until now `price_sol` carried that canonical value and disagreed with the row's own amounts by a **7.9% median** (p90 ~74%): a stale market price reads low in a pump and high in a dump, so anything you averaged out of the tape inherited the bias instead of cancelling it. Use `price_sol` for cost basis, fills and PnL; `market_price_sol` for a per-token series independent of trade size and direction. Both `madeonsol_token_trades` and `madeonsol_wallet_trades` carry all four fields, and both tool descriptions spell out which price to use so an agent does not average the wrong one.

> **New in 1.21.0 — the Deployer Hunter surface completed.** Seven new operations that existed on the API but had no SDK binding: `madeonsol_deployer_leaderboard`, `madeonsol_deployer_stats`, `madeonsol_deployer_profile`, `madeonsol_deployer_tokens`, `madeonsol_deployer_alert_stats`, `madeonsol_deployer_best_tokens` and `madeonsol_deployer_recent_bonds`. Read `bonding_rate` (lifetime) against `recent_bond_rate` (rolling) — the gap between them is the signal, not either number alone. `runner_rate` only means something once `labeled_tokens >= 3`, and an **untracked wallet returns a profile with zeroed counters, not a 404**, so check `total_deployed` before reading a 0% bond rate as a track record. Dependency ranges are now bounded to the versions actually tested (`@x402/*` `^2.x`, `@solana/kit` `^5.5.1`) instead of open-ended `>=0.0.1`, and the lazily-imported x402 peers are marked optional — a keyed install no longer pulls the whole Solana stack.

> **New in 1.20.0** — **Token depth / price impact + deployer self-activity on risk.** New tool `madeonsol_token_depth` (`GET /tokens/{mint}/depth`) — per-pool price-impact / slippage: "how much SOL moves this token's price N%", per pool (NOT router-optimal). Pass up to 8 SOL buy `sizes` (each >0 and ≤10000; default `[0.5, 1, 5, 10]`); every computable pool returns `spot_price_sol`, `fee_pct`, a `quotes[]` entry per size (`size_sol`, `tokens_out`, `avg_price_sol`, `price_impact_pct`), and `to_move_price` — the SOL required to move price **1% / 5% / 10%**. Constant-product AMMs are served from stream reserves (`source: "stream"` with `reserves_age_ms`); pump.fun/bonk bonding curves from a **live** read of the curve's virtual reserves (`source: "live_rpc"`). Pools that can't be priced honestly — concentrated CLMM/Orca/DLMM, Meteora-DBC curves, unclassified models — come back in `unsupported_pools[]` with a `reason` (e.g. `concentrated_liquidity_depth_not_supported`, `curve_graduated_use_amm_pool`) instead of a wrong number; `primary_pool` names the deepest computable pool, `found: false` means no pool with sufficient authoritative data for depth (see `unsupported_pools[].reason`; tracked pools may still be listed there). PRO/ULTRA only. And `madeonsol_token_risk` now returns a top-level **`dev` block** (deployer self-activity; `null` when the mint has no deployer-pipeline row): the create-tx self-buy snapshot (`buy_sol`, `buy_tokens`, `buy_supply_pct`), the post-create rollup (`bought_tokens_after` — catches the same-second-separate-tx dev buy the create snapshot reads as 0 — `sold_tokens`, `sold_sol`, `first_sell_at`/`last_sell_at`), **live on-chain holdings** (`holdings_tokens`, `holdings_supply_pct` — pump.fun 1B denominator, null elsewhere — `wallet_empty`: is the dev wallet empty NOW), and `transferred_out` (tokens left without a sell; `null` = unknown, never a guess), plus `as_of`. `deployer:alert` webhook/WS payloads gain `dev_buy_sol` + `dev_buy_supply_pct`.
>
> **New in 1.19.0** — **Batch wallet classification + token trade tape + bigger keyless catalog.** New tool `madeonsol_wallet_batch_classify` — reputation flags for 1–100 wallets in one call (counts as one request): per wallet `is_sniper` / `is_bundler` / `is_dumper` / `is_kol` (+ `kol_name`), `bot_confidence` (string enum `none`/`low`/`medium`/`high`, `null` when not alpha-tracked), and a `dump_cluster` block (`dump_cohorts`, `runner_cohorts`, `total_cohorts`, `as_of`). Flags are pump.fun-pipeline scoped — `false` = not observed, NOT verified clean; `is_bundler` is lifetime, `is_dumper` is a rolling 42d window. New tool `madeonsol_token_trades` — mint-scoped cursor-paginated trade tape (the backfill complement to the live firehose): `tx_signature`, `wallet_address`, `action`, `sol_amount`, `token_amount`, `price_sol`/`price_usd`, `early_buyer_rank`, `slot`, `block_time`, `traded_at`; filters `action` / `wallet` / `since`–`until` (default FULL history — capture starts 2026-04-12), plus a `coverage` honesty block. Both PRO/ULTRA. `madeonsol_wallet_stats` flags gain `is_sniper`/`is_bundler`/`is_dumper` + `dump_cluster`, and `bot_confidence` is now correctly typed as a string enum (it was documented as a number and always came back `null` due to a server bug — now returns real values). `madeonsol_token_risk` inputs and `madeonsol_sniper_recent` deploys gain the slot-window `sniper_footprint`/`footprint` rollup (`buys`, `buyers`, `sol`, `supply_pct`, `sniper_wallet_buys`, `data_available`, `as_of` — `null` = not observable, not zero). The **keyless x402 catalog grows 18 → 25 endpoints**: token candles ($0.01), almost-bonded ($0.01), top-traders ($0.02), cap-table ($0.02), sniper recent ($0.01), token flow ($0.01), deployer trajectory ($0.01) — `madeonsol_sniper_recent` and `madeonsol_deployer_trajectory` now work keyless via x402 too.
>
> **New in 1.18.0** — **Verified on-chain wallet holdings.** New tool `madeonsol_wallet_holdings` — the wallet's CURRENT holdings read straight from chain: its actual SPL + Token-2022 token accounts and SOL balance, each enriched with our `price_usd` / `value_usd` / `market_cap_usd` / `name` / `symbol` / `is_bonded`, plus `transfer_delta` (on-chain amount − trade-derived net position — exposes non-swap flows like airdrops, insider funding, and wallet-hopping). Distinct from `madeonsol_wallet_positions` (trade-derived FIFO): this is what the wallet *actually* holds right now. Params: `limit` (1–500, default 200), `min_value_usd` (default 0). Returns `{ address, sol_balance, holdings[], summary, verified_at, trade_window_days, cache_hit, ttl_seconds }`. ULTRA only.
>
> **New in 1.17.0** — **Bundle-cohort holdings.** New tool `madeonsol_token_bundle` — which same-slot "bundle" wallets bought a token and how much of supply they *still* hold (the incumbents' "current held %" rug/insider signal, from confirmed on-chain data). Returns a `bundle` block (`wallet_count`, `bundle_kind` atomic_tx/same_slot/none, `held_ratio`, `held_pct_of_supply` — the headline, net held / circulating supply, null if unknown — `fully_exited`, `buy_volume`, `tokens_held`) plus a `wallets[]` array (`rank`, `wallet`, `held_ratio`, `has_sold`, `atomic`, `is_kol`). BASIC get the bundle block only (empty `wallets[]`); PRO adds top-10 flags-only wallets; ULTRA returns the full cohort with enriched identities (`kol_name`, `win_rate`, `bot_confidence`, `tokens_held`).
>
> **New in 1.16.0** — **Batch risk scoring + live stream-session control.** New tool `madeonsol_tokens_batch_risk` — bulk rug-risk/safety scoring for up to 50 mints in one call, returning the same per-mint shape as `madeonsol_token_risk` (0–100 score, `band`, explainable `factors[]`, raw `inputs`) plus an `as_of` timestamp; untracked mints come back as `{ mint, error: "not_tracked" }` without failing the batch, and the whole call counts as one request against quota. Plus two WebSocket session tools: `madeonsol_stream_sessions_list` (list your live sessions — `id`, `service`, `tier`, `channels`, `connected_at`, `remote_ip`, `messages_sent`) and `madeonsol_stream_session_kill` (force-disconnect a session by id to free its connection slot, e.g. a ghost socket). PRO/ULTRA only.
>
> **New in 1.15.0** — **Almost-bonded discovery + trending sorts.** New tool `madeonsol_almost_bonded` — pre-bond pump.fun tokens near graduation, ranked by velocity (Δprogress/min): "95% and accelerating" beats "92% stalled". Each token carries `progress_pct`, `velocity_pct_per_min`, `eta_minutes`, `stalled`, `real_sol_reserves`, `market_cap_usd`, `liquidity_usd`, `authorities_revoked`, `deployer_tier`, and `age_minutes`. Params: `min_progress`, `max_progress`, `min_velocity_pct_per_min`, `max_age_minutes`, `deployer_tier`, `authority_revoked`, `min_liq`, `sort` (velocity_desc / progress_desc / eta_asc), `limit`. PRO/ULTRA only. Plus `madeonsol_tokens_list` gains four momentum sorts — `mc_change_5m_desc`, `mc_change_1h_desc`, `volume_1h_desc`, and `trending` (composite recent-volume × positive-momentum rank).
>
> **New in 1.14.0** — **Token trade flow.** New tool `madeonsol_token_flow` — a trade-flow aggregate (organic-vs-fake volume) over a `1h`/`24h` window: `unique_wallets` / `unique_buyers` / `unique_sellers`, `buy_count` / `sell_count` / `total_trades`, `buy_sol` / `sell_sol` / `net_sol` (sell − buy; positive = net SOL leaving the pool), and `trades_per_wallet` (wash-trading proxy). PRO/ULTRA only. Deployer alerts (`madeonsol_deployer_alerts`) now carry `deployers.deployer_sol_balance` — the deployer wallet's SOL balance at alert time (null for historical rows).
>
> **New in 1.13.0** — **Token OHLCV candles.** New tool `madeonsol_token_candles` — historical price candles (1m/5m/15m/1h/4h/1d) aggregated from the on-chain trade firehose. Each candle has `t/open/high/low/close/volume_usd/trades/market_cap_usd`. PRO returns OHLCV for the last 30 days; ULTRA adds buy/sell volume + count splits, net flow, MEV volume, open/close liquidity, high/low MC, and full history. PRO/ULTRA only.
>
> **New in 1.12.0** — **Token risk score.** New tool `madeonsol_token_risk` — a transparent 0–100 rug-risk/safety score (higher = riskier) with a `band` (safe/caution/danger), an explainable `factors[]` array, and the raw `inputs` (mint/freeze authority, liquidity, liq-to-MC ratio, transfer fee, launch cohort, deployer bond rate, KOL signal, blacklist). PRO/ULTRA only.
>
> **New in 1.11.0** — `madeonsol_tokens_list` gains three new filter params: `min_liq_mc_ratio`, `max_liq_mc_ratio`, and `deployer_tier`. Response items now include `liquidity_to_mc_ratio` and `deployer_tier`. New tool: `madeonsol_signal_performance` — evaluate signal efficacy (hit rate, sample size, median outcome) before acting on any signal. KOL leaderboard entries now include `median_hold_minutes_30d` and `percentile_early_entry_30d`.
>
> **New in 1.10.4** — Deployer alerts/profiles now expose `runner_rate` + `labeled_tokens` (fraction of a deployer's labeled tokens that ran vs dumped, gate on `labeled_tokens` ≥3) plus `avg_time_to_bond_minutes`.

> **New in 1.10.3** — **Dump-cluster detection.** `madeonsol_token_buyer_quality` breakdown now includes `dump_cluster_count` (3+ dump-cluster wallets in the first-20 → 94% historical dump rate vs 61% base) and `recycled_early_buyer_count`. Full breakdown is returned on all tiers. Also: the API now pushes every pump.fun graduation in real time (`token:graduations` WS channel).

> **New in 1.10** — **Deshred Sniper Alerts.** `madeonsol_sniper_recent` surfaces pump.fun deploys from shred-level data ~500ms before on-chain confirmation. PRO: elite/good deployers. ULTRA: all tiers + custom watchlist. Use `sniper:deploys` WebSocket or `sniper:deploy` webhook for live push.
>
> **New in 1.9** — **Price alerts, scout leaderboard, coordination history.** `madeonsol_price_alerts_*` CRUD (PRO=5, ULTRA=25). `madeonsol_scout_leaderboard` ranks top scouts by first-touch follow-on rate. `madeonsol_coordination_history` and `madeonsol_peak_history` expose the historical record. `madeonsol_wallet_stats` now returns `derived`: win_rate, roi, verdict, biggest_miss.
>
> **New in 1.8** — **Universal Wallet API.** `madeonsol_wallet_stats`, `madeonsol_wallet_pnl`, `madeonsol_wallet_positions`, `madeonsol_wallet_trades` — FIFO cost-basis PnL and cursor-paginated raw trades for any Solana wallet. PRO+. Cache hits don't count against quota.
>
> **New in 1.7.0** *(2026-05-12)* — Two new tools: **`madeonsol_me`** (account/quota introspection — read tier, remaining requests, and per-feature usage without parsing rate-limit headers) and **`madeonsol_tokens_list`** (PRO+ filtered, sortable token directory — MC band, liquidity floor, primary DEX, authority/safety flags, plus computed 1h volume / MEV-share / MC-change deltas). Token responses now expose **velocity / MEV-share** fields. Token directory defaults to **`min_liq=2000`** to skip phantom-MC dust — pass `min_liq=0` to opt out. `/token/{mint}` now returns **structured 400 errors** (`code` / `reason` / `example` / `docs`) instead of plain strings. Deprecated `avg_entry_mc_usd` field fully removed from KOL/alpha leaderboards.

> **New in 4.0.0 (breaking):** the sniper tool requires an ULTRA, BUSINESS or ENTERPRISE API key; in keyless (x402) mode it is refused before any payment because the server retired the keyless sniper endpoint on 2026-10-06 (HTTP 410, nothing charged).

## Install via Smithery (one line)

[Smithery](https://smithery.ai/servers/madeonsol/solana-kol-intelligence) is the easiest path — it writes the config for you and handles the install:

```bash
npx -y smithery mcp add madeonsol/solana-kol-intelligence
```

Smithery prompts for your `MADEONSOL_API_KEY` ([free at madeonsol.com/pricing](https://madeonsol.com/pricing)) and wires up Claude Desktop or your chosen MCP client. Restart the client and ask: *"What are KOLs buying right now?"*

You can also browse tools from the CLI:

```bash
npx -y smithery tool get madeonsol/solana-kol-intelligence madeonsol_kol_feed
```

## Quick start — manual config (10 seconds)

```bash
npm install -g mcp-server-madeonsol
```

Add to `claude_desktop_config.json` or Cursor MCP settings (free tier at https://madeonsol.com/pricing):

```json
{ "mcpServers": { "madeonsol": { "command": "mcp-server-madeonsol", "env": { "MADEONSOL_API_KEY": "msk_..." } } } }
```

Restart Claude Desktop and ask: *"What are KOLs buying right now?"*

## AI agent quickstart (x402 / pay-per-call)

Building an autonomous agent? Skip the signup. Configure a **funded Solana wallet** and an explicit payment budget. Paid tool calls authorize micropayments within that budget over [x402](https://x402.org) — no API key, no account, no rate-limit dance.

```json
{
  "mcpServers": {
    "madeonsol": {
      "command": "mcp-server-madeonsol",
      "env": {
        "SVM_PRIVATE_KEY": "<base58 solana private key>",
        "X402_PAY_TO": "GLu63pRCYrp4BJu5P5ciYKxgeZFW9c8TJ8jWzK3TB9AR",
        "X402_FEE_PAYER": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4",
        "X402_MAX_AMOUNT_ATOMIC": "20000",
        "X402_MAX_TOTAL_AMOUNT_ATOMIC": "1000000",
        "SVM_RPC_URL": "https://<your-trusted-solana-rpc>"
      }
    }
  }
}
```

How it works:

- The wallet behind `SVM_PRIVATE_KEY` settles each request as a **USDC micropayment on Solana** (~$0.005–$0.02 per call, settled on-chain). No subscription; the configured authorization budget bounds spending.
- Read `/api/x402` for the current keyless catalog and prices. Sniper is API-key only.
- The free **`madeonsol_discovery`** tool needs no auth and returns every endpoint with its exact per-call price — call it first to see what each tool costs.
- Install the x402 peer deps alongside the server (only required for this mode):

  ```bash
  npm install -g mcp-server-madeonsol @x402/fetch @x402/svm @x402/core @solana/kit @scure/base
  ```

> **Data only.** MadeOnSol returns trading *intelligence* — it never trades, signs swaps, or takes custody of funds. The only thing your wallet ever pays for is the per-call data fee.

Prefer a fixed monthly bill, free tier, or no wallet? Use the developer path below.

## Required payment policy (breaking keyless upgrade)

Keyless Solana payments require an explicit trusted merchant, facilitator and authorization budget. API-key mode is unchanged and takes precedence over a configured wallet.

Only exact payments in mainnet USDC are permitted. Set the two addresses from your trusted operator configuration, independently of a server challenge. `SVM_RPC_URL` must be your trusted HTTPS RPC; there is no public RPC fallback. The agent wallet cannot also be the facilitator fee payer.

| Setting | Meaning |
|---|---|
| `X402_PAY_TO` | Trusted merchant wallet receiving USDC |
| `X402_FEE_PAYER` | Trusted facilitator wallet paying transaction fees |
| `X402_MAX_AMOUNT_ATOMIC` | Maximum per payment, as a positive integer string |
| `X402_MAX_TOTAL_AMOUNT_ATOMIC` | Lifetime authorization allowance, as a positive integer string |
| `SVM_RPC_URL` | Explicit trusted HTTPS Solana RPC URL |

USDC uses 6 decimals: `20000` = 0.02 USDC and `1000000` = 1 USDC. Choose limits that cover the endpoints you intend to use; these examples are not a price guarantee.

**Canonical MadeOnSol values (Solana mainnet USDC).** Pinned here (GitHub + npm README) so you do not have to take them from a 402:
- merchant `payTo` / `X402_PAY_TO`: `GLu63pRCYrp4BJu5P5ciYKxgeZFW9c8TJ8jWzK3TB9AR` (also shown on https://madeonsol.com/x402 and https://madeonsol.com/.well-known/x402)
- facilitator `feePayer` / `X402_FEE_PAYER`: `2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4`. This is the fee payer of **PayAI**, the third-party facilitator MadeOnSol's Solana rail uses. If PayAI rotates it, keyless calls fail closed (the client refuses to sign) until you update this value; a MadeOnSol release will announce the new one.
- prices: Solana legs are 5000–20000 atomic (0.005–0.02 USDC), so `maxAmountAtomic` / `X402_MAX_AMOUNT_ATOMIC` must be at least `20000` to reach every endpoint.

The budget is per client instance / process: not wallet-wide, not shared between processes, reset when a new instance or process starts. Keyless mode requires the base URL exactly `https://madeonsol.com`.


The allowance is reserved before concurrent calls can approve/sign. An unsigned denial releases it; entering payment creation retains it even if RPC, signing or the paid response fails. It measures **authorized attempts, not settled spend**. There is no automatic refund or payment replay. A timeout cannot undo a proof already sent.

The allowance is per server process; restarting starts a new allowance. Reuse the running process. Multiple MCP servers or other clients sharing a wallet need an external shared budget. Missing/invalid keyless settings stop startup; wallet signing remains restricted to stdio. The payment attempt timeout defaults to 30 seconds.

## Authentication

Two options (in priority order):

| Method | Env var | Best for |
|---|---|---|
| **MadeOnSol API key** (recommended) | `MADEONSOL_API_KEY` | Developers — [get a free key](https://madeonsol.com/pricing) |
| x402 micropayments | `SVM_PRIVATE_KEY` | AI agents with Solana wallets |

> **v1.0 breaking change:** RapidAPI auth (`RAPIDAPI_KEY`) has been removed. The MadeOnSol RapidAPI marketplace was retired on 2026-04-19. Get a free `msk_` key at [madeonsol.com/pricing](https://madeonsol.com/pricing).

## Install

```bash
npm install -g mcp-server-madeonsol
```

> x402 peer deps (`@x402/fetch @x402/svm @x402/core @solana/kit @scure/base`) are only needed when using `SVM_PRIVATE_KEY`.

## Configure

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "madeonsol": {
      "command": "mcp-server-madeonsol",
      "env": {
        "MADEONSOL_API_KEY": "msk_your_api_key_here"
      }
    }
  }
}
```

### Cursor

Add to MCP settings with the same command and env vars.


## Private HTTP transport (SEC-02)

Stdio remains the default for Claude Desktop, Cursor and other local MCP clients. HTTP now requires an explicit private-operator configuration; previously unauthenticated HTTP launch settings will fail closed.

1. Set `MADEONSOL_API_KEY` to the operator's `msk_` key.
2. Generate a separate random access token, for example `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"`, and store it as `MCP_HTTP_TOKEN`. Do not reuse the upstream API key or put either credential in a URL.
3. Set `MCP_TRANSPORT=http`, `HOST=127.0.0.1` (default, or `::1`) and optionally `PORT` (default `3100`). Non-loopback bindings, missing credentials and any `SVM_PRIVATE_KEY` or `RHC_PAYER_KEY` are refused before startup. Solana wallet/x402 mode remains available through stdio.
4. Connect to `http://127.0.0.1:3100/mcp` with `Authorization: Bearer <MCP_HTTP_TOKEN>` on **every request**, plus the normal MCP `Content-Type` and `Accept` headers. Use stdio if the client cannot attach headers. The local token is checked by the MCP adapter; only `MADEONSOL_API_KEY` is sent upstream.

Only `POST /mcp`, `GET /health` and `GET /.well-known/mcp/server-card.json` are exposed, all authenticated. `/` and arbitrary paths are no longer MCP endpoints. The adapter is stateless: it does not issue session IDs, rejects supplied `Mcp-Session-Id`, and returns 405 for GET/DELETE on `/mcp`. Host must be the selected loopback literal with its port, or `localhost` with that exact port. Browser Origin headers, forwarded/proxy headers and cross-origin requests are rejected; no CORS access is granted.

Limits: 256 KiB uncompressed JSON bodies, 8 KiB headers, a 10-second body-upload deadline, and 16 active authenticated requests. Oversized or malformed inputs are rejected before tool dispatch. This is not an overall tool-execution deadline; an upstream action already submitted may continue after a disconnect.

Everyone holding the local token acts as the **same operator**, including access to that operator's mutation tools. This is not a multi-user/OAuth server: do not put it behind a public proxy, share it with untrusted users or expose a funded signer. Separate users require isolated processes/credentials or a future transport that authenticates each principal and maps their own credentials. Restart with a new `MCP_HTTP_TOKEN` to rotate access.

The Docker image uses the same loopback restriction and requires both environment credentials. Its healthcheck authenticates without putting the token in the URL. It does not support a publicly published Docker port; use stdio or a client in the same trusted network namespace.

## Tools

### KOL Intelligence

| Tool | Description |
|---|---|
| `madeonsol_kol_feed` | Real-time KOL trade feed (1,000+ wallets) |
| `madeonsol_kol_coordination` | Multi-KOL convergence signals (v1.1) — peak-density window, exit detection, 0-100 score |
| `madeonsol_kol_first_touches` | First-KOL-touch events — backtested scout signal. Filter by scout tier, winrate, token age, mint suffix |
| `madeonsol_kol_leaderboard` | KOL PnL and win rate rankings (180 days of history; periods: today, 7d, 30d, 90d, 180d) |
| `madeonsol_kol_pairs` | KOL affinity matrix — which KOLs co-trade the same tokens |
| `madeonsol_kol_hot_tokens` | KOL momentum tokens — accelerating buy interest |
| `madeonsol_kol_trending_tokens` | Tokens ranked by KOL buy volume (5m–12h windows). ULTRA adds full KOL wallet addresses. |
| `madeonsol_kol_pnl` | Deep per-wallet PnL: equity curve, risk metrics, closed positions. ULTRA adds open positions (tokens bought but not yet sold). |
| `madeonsol_kol_timing` | KOL entry/exit timing profile — available on all tiers |

### Deployer Hunter

| Tool | Description |
|---|---|
| `madeonsol_deployer_alerts` | Pump.fun deployer launches with KOL enrichment. Filter by tier (elite/good/moderate/rising/cold). ULTRA unlocks full pagination. Each alert's `deployers` now includes `deployer_sol_balance` — the deployer wallet's SOL balance at alert time (null for historical rows). |
| `madeonsol_deployer_trajectory` | Deployer skill curve — streaks, rolling bond rate, trend — available on all tiers |
| `madeonsol_deployer_history` | A pump.fun deployer's daily reputation time-series (`bonding_rate`, `recent_bond_rate`, `tier`, `avg_peak_mc` per day) — backtest deployer signals at launch time without look-ahead bias. `limit` 1–365 (default 90) |

### Early sniper observations (ULTRA/BUSINESS/ENTERPRISE)

Pre-confirm pump.fun deploy feed reconstructed from shred-level (**deshred**) data — launches surface **~500ms before they confirm on-chain**. Pro sees elite/good deployers; Ultra sees every tier.

| Tool | Description |
|---|---|
| `madeonsol_sniper_recent` | Early deploy observations for ULTRA/BUSINESS/ENTERPRISE API keys. No x402; no guaranteed lead time. Observations are not proof of execution. |
| `madeonsol_sniper_by_deployer` | Deshred deploys for a single deployer wallet (Ultra) |

### Wallet Tracker

| Tool | Description |
|---|---|
| `madeonsol_wallet_tracker_watchlist` | List your tracked wallets and remaining capacity (Pro: 50, Ultra: 100, Business: 500; the Free tier has no wallet tracker) |
| `madeonsol_wallet_tracker_add` | Add a wallet to your watchlist |
| `madeonsol_wallet_tracker_remove` | Remove a wallet from your watchlist |
| `madeonsol_wallet_tracker_trades` | Historical swap/transfer events for watched wallets (120-day retention). Returns `events[]` + `next_cursor` / `next_cursor_slot`. `action` is `buy` or `sell` (swaps only; transfers have `action: null`, select them with `event_type: transfer`). `order` = `slot` (default) or `block_time`; page with `before_slot` or the legacy `before` |
| `madeonsol_wallet_tracker_summary` | Per-wallet stats: swap counts, SOL bought/sold, last event |

### Universal Wallet *(new in 1.8 — any wallet, not just curated KOLs, PRO+)*

| Tool | Description |
|---|---|
| `madeonsol_wallet_stats` | Aggregate 90d stats + cross-product flags (is_kol, is_alpha_tracked + bot_confidence `none`/`low`/`medium`/`high`, is_deployer + tokens_deployed, **new 1.19:** is_sniper / is_bundler / is_dumper + `dump_cluster` cohorts) — quick sizing-up of an unknown wallet |
| `madeonsol_wallet_batch_classify` | **New 1.19** · Bulk reputation flags for 1–100 wallets in one call — is_sniper/is_bundler/is_dumper/is_kol + kol_name, bot_confidence, dump_cluster. Pump.fun-pipeline scoped: `false` = not observed, not verified clean |
| `madeonsol_wallet_pnl` | Full FIFO cost-basis PnL: realized + unrealized SOL, profit factor, max drawdown, avg + median hold minutes, daily UTC PnL curve, closed + open positions hydrated with live mc-tracker prices |
| `madeonsol_wallet_positions` | Open positions only — lighter slice of /pnl. Shares the same cache. |
| `madeonsol_wallet_holdings` | **New 1.18** · Verified CURRENT on-chain holdings (real SPL + Token-2022 accounts + SOL) enriched with price/MC/name, plus `transfer_delta` vs trade-derived position. ULTRA only. |
| `madeonsol_wallet_trades` | Cursor-paginated raw trades with action / token / since-until filters |

Cached server-side with dynamic TTL (5min / 1h / 24h based on last activity). Cost basis observable only inside the 90-day window.

### Alpha Wallet Intelligence

Scored from 1.5M+ early-buyer records (wallets seen in the first 20 buyers of Pump.fun tokens).

| Tool | Tier | Description |
|---|---|---|
| `madeonsol_alpha_leaderboard` | All | Top profitable early-buyer wallets. Up to 100 on Free/Pro; ULTRA unlocks 500 + bot signals |
| `madeonsol_alpha_wallet` | ULTRA | Full per-token breakdown + bot_signals array |
| `madeonsol_alpha_linked` | ULTRA | Wallets behaviorally linked (co-bought 3+ tokens within 2s) |

### Token Quality

| Tool | Tier | Description |
|---|---|---|
| `madeonsol_tokens_list` | PRO+ | Filtered, sortable token directory — MC band, liquidity floor, primary DEX, authority/safety flags, computed 1h volume / MEV-share / MC-change deltas, plus momentum sorts (`mc_change_5m_desc`, `mc_change_1h_desc`, `volume_1h_desc`, `trending`). Default `min_liq=2000` skips phantom-MC dust. |
| `madeonsol_almost_bonded` | PRO+ | Pre-bond pump.fun tokens near graduation, ranked by velocity (Δprogress/min) — `progress_pct`, `velocity_pct_per_min`, `eta_minutes`, `stalled`, `deployer_tier`, `age_minutes` |
| `madeonsol_token_cap_table` | PRO+ | First non-deployer early buyers, enriched with PnL/KOL/bot flags. PRO=10, ULTRA=20 |
| `madeonsol_token_buyer_quality` | All | 0–100 buyer-quality score + full breakdown (5-min cached) |
| `madeonsol_token_risk` | PRO+ | Transparent 0–100 risk score (evidence, not a verdict) with `band`, explainable `factors[]`, and raw `inputs` (**new 1.19:** `inputs.sniper_footprint` — slot-window snipe rollup, `null` = not observable; **new 1.20:** top-level `dev` block — deployer self-buy at create, sells rollup, live on-chain holdings, `wallet_empty`, `transferred_out`) |
| `madeonsol_token_bundle` | All | Bundle-cohort holdings — which same-slot bundle wallets bought a token and how much of supply they still hold (`held_pct_of_supply` headline, plus `bundle_kind`, `held_ratio`, `fully_exited`). BASIC: bundle block only. PRO: top-10 flags. ULTRA: full cohort + identities |
| `madeonsol_token_pools` | PRO+ | Per-venue liquidity map — every DEX pool a token trades in (pump.fun/PumpSwap/Raydium/Meteora/Orca) with per-pool `liquidity_usd`, `is_active` (live vs parked), plus a `summary` (pool/DEX counts, `total_liquidity_usd`, `primary_pool`, `top_pool_share_pct` concentration) |
| `madeonsol_token_depth` | **New 1.20** · PRO+ | Per-pool price impact / slippage — `quotes[]` per SOL buy size (`tokens_out`, `avg_price_sol`, `price_impact_pct`) + `to_move_price` (SOL to move price 1%/5%/10%). `sizes` max 8, default `[0.5, 1, 5, 10]`; unsupported pools (CLMM/DLMM/DBC) flagged with a `reason` |
| `madeonsol_token_holders` | **New** · PRO+ | Live holder census + concentration — who holds NOW (vs `madeonsol_token_cap_table` = who bought first). `concentration.holder_count` is EXACT (mint-scoped `getProgramAccounts` census merged per owner; `null` only when the provider refuses a mega-cap → top-20 fallback with `source.census_fallback_reason`, never trade-estimated). Each disclosed owner labelled `deployer` / `kol` / `early_buyer` / `bundle` / `bot` / `dump_cluster` (empty = unknown, not clean). Pools / bonding curves / burns EXCLUDED from the circulating denominator and NAMED in `excluded[]` (`reason`: `pool` + `dex` + `pool_address`, `bonding_curve`, `burn`, `program_account`); `amount_raw` is a raw u64 STRING. Disclosure PRO 10 / ULTRA 50 / BUSINESS 100. Big tokens: first call may be HTTP 503 `holder_scan_in_progress` (`retry_after_seconds: 20`) — scan continues + cached, retry is instant |
| `madeonsol_token_locks` | **New 1.24** · PRO+ | Token locks & vesting on a mint — every Streamflow / Jupiter Lock / Bonfida contract: `program`, `kind` (lock / vesting), derived `status`, sender / recipient, schedule (`start_at` / `cliff_at` / `end_at`, `period_seconds`), terms (`cancelable_by_sender` — the locker can pull it), live `locked_*` / `claimable_*` / `next_unlock`, plus `summary` (locked / deposited totals, `unlocking_7d_*` / `unlocking_30d_*`, nearest `next_unlock`, `active_cancelable_by_sender`). Filters `status`, `program`, `limit` ≤500. Base-unit amounts are STRINGS; ui/usd/pct `null` when unknown. **LP locks not included** |
| `madeonsol_token_locks_feed` | **New 1.24** · PRO+ | Cross-token feed of NEW lock / vesting contracts, newest first — same row shape + `token {symbol, price_usd, market_cap_usd}`. Cursors `since` / `before` (`pagination.next_since` / `next_before`); filters `mint`, `sender`, `recipient`, `program`, `kind`, `status`, `min_usd`, `min_pct_of_supply`, `include_estimated` (backfilled Jupiter rows). Push: WS channel `token:locks` (event `token:lock`) |
| `madeonsol_token_unlocks` | **New 1.24** · PRO+ | Upcoming unlock EVENTS across all active contracts inside `within` = 1h–90d — one entry per contract = its next `event` (cliff / period / final / tranche) with `amount_*` + `window_amount_*` (total release over the window), `token`, `lock`. `sort` soonest / largest_usd / largest_pct; filters `mint`, `program`, `kind`, `min_usd`, `min_pct_of_supply`; `limit` ≤200, `offset` |
| `madeonsol_token_fee_shares` | **New 1.24** · PRO+ | pump.fun creator-fee `SharingConfig` on a coin — `shareholders[]` (`share_bps`, `is_admin`, `is_social_pda` + `social {platform (2 = X), user_id, lifetime_claimed}`, `received_*`), `redirected_bps`, `social_bps`, `is_default` (100% to creator), `source` stream / chain; `distributions` rollup (recipients, past_recipients), `history[]`, `recent_distributions[]`. Amounts in quote base units (lamports) as STRINGS. **Event history starts 2026-08-17** |
| `madeonsol_token_fee_claims` | **New 1.24** · PRO+ | pump.fun fee-event feed, newest first — `type` distribution (with `payouts[]` per shareholder) / social_claim (X identity → wallet, `mint` null) / shares_created / shares_updated / shares_reset / creator_transferred / creator_claim (excluded unless `type=` asks). Filters `type` (comma list), `mint`, `recipient`, `actor`, `social_platform`, `social_user_id`, `min_sol`, `since` / `before`. Push: WS channel `token:fee_claims` (event `token:fee_claim`). **History starts 2026-08-17** |
| `madeonsol_tokens_surges` | **New 1.25** · PRO+ | Token momentum fires, newest first — `kind` `surge` (token < 30 min old vs its LAUNCH MC; `tier` `early` ≤10 min ≥$12k ≥3× · `strong` ≤30 min ≥$30k ≥6× and ≥2× the 3-min low · `breakout` ≤2 min ≥$45k ≥8×; each once per mint, sustained ≥10 s) or `revival` (no trade candle ≥24 h, then ≥5 buys / ≥$500 buy volume / ≥1.5× the pre-dormancy MC on the tape — never a price mark; `tier` null). Each row: burst `tape` (`unique_buyers` null outside trade coverage), `kol`, `early_buyers` (bundled / sold / sniper), `deployer`, `risk_flags[]` (empty = no flag raised, not verified clean), and `outcome` (+1 h MC / peak / low) once ≥65 min old. `stats=1` = per-(kind, tier) hit-rates over `days`. Filters `kind`, `tier`, `mint`, `launchpad`, `deployer_tier`, `min_mc_usd` / `max_mc_usd`, `min_buys`, `exclude_flags` (comma list), `only_clean`; cursors `since` / `before`; `limit` ≤200. Push: WS channel `token:surges` (events `token:surge` / `token:revival`) + webhook registry. Retention 60 d |
| `madeonsol_tokens_batch_risk` | PRO+ | Bulk risk scoring (evidence, not a verdict) for up to 50 mints — same shape as `madeonsol_token_risk` + `as_of`. Untracked mints return `{ mint, error: "not_tracked" }` without failing the batch; counts as one request |
| `madeonsol_token_candles` | PRO+ | Historical OHLCV candles (1m–1d). PRO=OHLCV 30d; ULTRA=+net flow, liquidity delta, MEV volume, full history |
| `madeonsol_token_flow` | PRO+ | Trade-flow aggregate (organic-vs-fake volume) over a 1h/24h `window` — unique wallets/buyers/sellers, buy/sell counts + SOL, `net_sol`, `trades_per_wallet` wash-trading proxy |
| `madeonsol_token_trades` | **New 1.19** · PRO+ | Mint-scoped trade tape — cursor-paginated raw trades for one token (action / wallet / since–until filters, default FULL history). History starts 2026-04-12; `coverage` block marks scope |

### Copy-Trade Rules (PRO+)

Server-side rules that fire signals when a source wallet trades. Delivered via webhook (HMAC-signed) and/or WebSocket. Limits: PRO 3 rules × 5 source wallets, ULTRA 20 × 50, BUSINESS 100 × 250 (Enterprise follows Business). The server enforces your tier's limit. Any valid Solana wallet can be a source, KOL or not (server behaviour since 2026-10-04; KOL membership is optional enrichment and copy-trade sources do not use Wallet Tracker quota). Each rule reports `source_admission` (`any_wallet`) and `operational_state` (`eligible`, or an infrastructure state: `monitoring_pending`, `monitoring_unavailable`, `source_capacity_unavailable`). A source trade older than 10 s by chain time is not executed, and each trade produces at most one signal per rule. `only_action` defaults to `buy`. `min_mc_usd` / `max_mc_usd` restrict a rule (or the signals query) to a market-cap band on the source trade; when a bound is set, trades with an unknown market cap are dropped.

| Tool | Description |
|---|---|
| `madeonsol_copytrade_list` | List your rules |
| `madeonsol_copytrade_create` | Create a rule (optional `min_mc_usd` / `max_mc_usd`). Returns `webhook_secret` once — store it |
| `madeonsol_copytrade_get` | Get one rule |
| `madeonsol_copytrade_update` | Update fields or toggle `is_active`; `null` clears an MC bound |
| `madeonsol_copytrade_delete` | Delete permanently |
| `madeonsol_copytrade_signals` | Recent fired signals (up to 7 days). Filters `subscription_id`, `since`, `limit`, `min_mc_usd` / `max_mc_usd` |

### KOL Coordination Alerts (PRO/ULTRA — v1.1 push signals)

Real-time push alerts when a KOL cluster co-buys the same token. Fires within ~1s (pg_notify push). Delivered via WebSocket (`kol:coordination` channel, user-scoped) and/or HMAC-signed webhook.

| Tool | Description |
|---|---|
| `madeonsol_coordination_alerts_list` | List your rules (PRO=5, ULTRA=20) |
| `madeonsol_coordination_alerts_create` | Create a rule. Returns `webhook_secret` once — store it |
| `madeonsol_coordination_alerts_get` | Get one rule |
| `madeonsol_coordination_alerts_update` | Update fields or toggle `is_active` |
| `madeonsol_coordination_alerts_delete` | Delete permanently |

### KOL Scout Signal — first KOL touches *(new in 1.3)*

Every "first KOL buy on a token mint" event. Filterable by **scout tier** (S/A/B/C from `mv_kol_scout_score`), KOL winrate, token age, mint suffix.

**Backtest:** S-tier scouts attract ≥3 follow-on KOLs within 4h ~50% of the time vs ~14% baseline (38d / 491k buys / 72,549 events). Public leaderboard at [madeonsol.com/kol/scouts](https://madeonsol.com/kol/scouts).

| Tool | Description |
|---|---|
| `madeonsol_kol_first_touches` | Recent first-KOL-touch events. Filters: `min_scout_tier`, `min_kol_winrate_7d`, `token_age_max_min`, `mint_suffix`, `preset`, etc. |
| `madeonsol_first_touch_subscriptions_list` | List your first-touch webhook subscriptions — ULTRA |
| `madeonsol_first_touch_subscriptions_create` | Create a webhook rule (HMAC-signed). Returns `webhook_secret` once — store it. Up to 10/user — ULTRA |
| `madeonsol_first_touch_subscriptions_get` | Get one subscription — ULTRA |
| `madeonsol_first_touch_subscriptions_update` | Update fields or toggle `is_active` — ULTRA |
| `madeonsol_first_touch_subscriptions_delete` | Delete permanently — ULTRA |

> **Don't poll — push.** Median lead time before the second KOL is 12 seconds. WebSocket channel: `kol:first_touches` (PRO+).

### Price Alerts *(new in 1.9)*

CRUD for token dip/recovery price alerts. Fires when a token's market cap crosses your threshold. PRO=5 rules, ULTRA=25.

| Tool | Description |
|---|---|
| `madeonsol_price_alerts_list` | List your price alert rules |
| `madeonsol_price_alerts_create` | Create a dip/recovery alert. Returns `webhook_secret` once — store it |
| `madeonsol_price_alerts_get` | Get one alert rule by ID |
| `madeonsol_price_alerts_update` | Update fields or toggle `is_active` |
| `madeonsol_price_alerts_delete` | Delete permanently |

### Scout Leaderboard & KOL Consensus *(new in 1.9)*

| Tool | Tier | Description |
|---|---|---|
| `madeonsol_scout_leaderboard` | PRO+ | Top scout-tier KOLs ranked by first-touch follow-on rate, win rate, and ROI |
| `madeonsol_kol_consensus` | PRO+ | Tokens with the strongest KOL agreement signal — weighted by scout score and recent PnL |
| `madeonsol_peak_history` | PRO+ | Historical peak-density windows for a token — every coordination spike with KOL breakdown |
| `madeonsol_coordination_history` | PRO+ | Global coordination event log with token, KOL count, score, and outcome |

### Wallet Derived Stats *(new in 1.9)*

`madeonsol_wallet_stats` now returns a `stats` object with derived fields: `win_rate` (0-1), `roi`, `verdict` ("strong" | "profitable" | "neutral" | "losing"), and `biggest_miss` (token with the highest post-exit gain the wallet missed).

### Streaming & Webhooks

| Tool | Description |
|---|---|
| `madeonsol_stream_token` | Get your WebSocket token for KOL/deployer streaming and DEX trade stream — PRO/ULTRA. **Never expires** (1.24.1): same token on every call; `rotate: true` replaces it (old value works 60 s more); `expires_at` / `next_refresh_at` always `null`. Channels now also include `token:locks` (new lock/vesting contracts, event `token:lock`), `token:fee_claims` (pump.fun fee events, event `token:fee_claim`) and `token:surges` (**new 1.25** — token momentum fires, events `token:surge` / `token:revival`, with `risk_flags[]`; subscribe filters `kinds[]`, `tiers[]`, `launchpads[]`, `exclude_flags[]`, `min_mc_usd` / `max_mc_usd`, `deployer_tier[]`) |
| `madeonsol_stream_sessions_list` | List your live WebSocket sessions — `id`, `service`, `tier`, `channels`, `connected_at`, `remote_ip`, `messages_sent` — PRO/ULTRA |
| `madeonsol_stream_session_kill` | Evict a live WebSocket session by id to free its connection slot (e.g. a ghost socket) — PRO/ULTRA |
| `madeonsol_create_webhook` | Register a webhook for real-time push notifications — PRO/ULTRA |
| `madeonsol_list_webhooks` | List your registered webhooks — PRO/ULTRA |
| `madeonsol_delete_webhook` | Delete a webhook by ID — PRO/ULTRA |
| `madeonsol_test_webhook` | Send a test payload to verify a webhook — PRO/ULTRA |

### General

| Tool | Description |
|---|---|
| `madeonsol_discovery` | List all endpoints and prices (free, no auth) |
| `madeonsol_me` | Inspect your account — tier, daily/burst quota state, remaining requests, subscription expiry, per-feature usage (webhooks, copy-trade wallets, coordination rules, etc.). Self-throttle without parsing rate-limit headers. |

## Tiers

| Tier | Price | Wallets tracked | Requests/day |
|------|-------|-----------------|--------------|
| BASIC (free) | $0 | 10 | 200 |
| PRO | €43/mo (€430/yr) ≈ $49 | 50 | 10,000 |
| ULTRA | €131/mo (€1310/yr) ≈ $149 | 100 + WS events | 100,000 |
| BUSINESS | €400/mo (€4000/yr) ≈ $449 | 500 + WS events | 500,000 |

Free tier returns the full REST response shape on 40+ endpoints — real wallets, TX signatures, full precision — with live feeds delayed 5 minutes (delayed responses carry `delay`/`as_of` and an `X-Data-Delay` header). Paid tiers are real-time and unlock webhooks, WebSockets, rule engines, and ULTRA-only data depth; x402 pay-per-call is always real-time. Get a key at [madeonsol.com/pricing](https://madeonsol.com/pricing).

## Also Available

| Platform | Package |
|---|---|
| TypeScript SDK | [`madeonsol`](https://www.npmjs.com/package/madeonsol) on npm |
| Rust SDK | [`madeonsol`](https://crates.io/crates/madeonsol) on crates.io |
| Python (LangChain, CrewAI) | [`madeonsol-x402`](https://pypi.org/project/madeonsol-x402/) on PyPI |
| ElizaOS | [`@madeonsol/plugin-madeonsol`](https://www.npmjs.com/package/@madeonsol/plugin-madeonsol) |
| Solana Agent Kit | [`solana-agent-kit-plugin-madeonsol`](https://www.npmjs.com/package/solana-agent-kit-plugin-madeonsol) |

## License

MIT