madeonsol 2.2.0 → 2.2.1

package/README.md

@@ -84,6 +84,7 @@ const { tools } = await client.tools.search({ q: "trading", limit: 10 });
 - **DEX trade sniping** — subscribe to the all-DEX stream filtered by token or wallet
 - **Deployer sniper** — monitor `client.deployer.alerts()` for elite-tier launches
 - **Coordination detector** — flag tokens with `client.kol.coordination({ min_kols: 3 })`
+- **Scout signal** — track first-KOL-touch events filtered to S/A-tier scouts via `client.kol.firstTouches({ preset: "scout" })`
 - **Analytics dashboard** — combine leaderboard, PnL, and tool data
 - **Telegram/Discord bot** — pipe alerts via webhooks into chat
 - **Portfolio tracker** — use `client.kol.wallet()` to follow specific KOL positions
@@ -195,6 +196,55 @@ WebSocket delivery: subscribe to channel `kol:coordination` on `wss://madeonsol.
 
 ---
 
+#### `client.kol.firstTouches(params?)` *(new in 2.2)*
+
+Recent first-KOL-touch events on tokens — every time a tracked KOL was the first to buy a given mint. Filterable by **scout tier** (S/A/B/C from the per-KOL `mv_kol_scout_score` view), KOL winrate, token age, mint suffix, etc.
+
+**Backtested signal:** top scouts attract ≥3 follow-on KOLs within 4h ~50% of the time vs ~14% baseline (38d / 491k buys / 72,549 events). The full leaderboard is at [madeonsol.com/kol/scouts](https://madeonsol.com/kol/scouts).
+
+```ts
+// S-tier scouts on tokens younger than 1h
+const { events } = await client.kol.firstTouches({
+  preset: "scout",
+  min_scout_tier: "S",
+  limit: 20,
+});
+
+for (const e of events) {
+  console.log(e.first_kol.name, "scouted", e.token_symbol, `(scout_score=${e.first_kol.scout_score}%)`);
+}
+```
+
+Filter knobs: `since`, `before`, `limit`, `kol`, `min_kol_winrate_7d`, `min_scout_tier`, `min_n_touches`, `strategy`, `token_age_max_min`, `min_first_buy_sol`, `mint_suffix`, `preset` (`"scout"` or `"fresh_launch"`), `include` (e.g. `"followers_4h"`).
+
+> **Don't poll — push.** Median lead time before the second KOL is **12 seconds**, so REST polling will lose the swarm. Subscribe to the `kol:first_touches` WebSocket channel (PRO+) or, on Ultra, create an HMAC-signed webhook subscription via `client.firstTouchSubscriptions.create({...})`.
+
+Returns: `FirstTouchesResponse`
+
+---
+
+#### `client.firstTouchSubscriptions.*` *(Ultra)*
+
+Create push-delivery rules for first-touch events. Up to 10 active subscriptions per Ultra user.
+
+```ts
+const { subscription, webhook_secret } = await client.firstTouchSubscriptions.create({
+  name: "S-tier scouts on pump tokens",
+  filters: { min_scout_tier: "S", mint_suffix: "pump" },
+  delivery_mode: "webhook",
+  webhook_url: "https://my.bot/hooks/scout",
+});
+// store webhook_secret — shown once
+
+await client.firstTouchSubscriptions.list();
+await client.firstTouchSubscriptions.update(subscription.id, { is_active: false });
+await client.firstTouchSubscriptions.delete(subscription.id);
+```
+
+Same HMAC scheme as coordination alerts. WebSocket channel: `kol:first_touches`.
+
+---
+
 #### `client.kol.token(mint)`
 
 KOL buy/sell activity for a specific token mint.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "madeonsol",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Official SDK for the MadeOnSol Solana API — KOL wallet tracking, Pump.fun deployer intelligence, and tool directory",
   "type": "module",
   "main": "dist/index.js",