solana-agent-kit-plugin-madeonsol 1.5.0 → 1.7.0

package/README.md

@@ -4,6 +4,22 @@
 
 > Real-time Solana trading intelligence: track 1,000+ KOL wallets with <3s latency, score 6,700+ Pump.fun deployers by reputation, detect multi-KOL coordination signals, monitor any Solana wallet for swaps and transfers, and stream every DEX trade. Free tier: 200 requests/day at [madeonsol.com/developer](https://madeonsol.com/developer) — no credit card required.
 
+> **New in 1.7.0** *(2026-05-12)* — **Account introspection + filtered token directory.** Two new actions: `meAction` (`GET /me`) returns your tier, daily/burst quota state, remaining requests, and per-feature usage so the agent can self-throttle; `tokensListAction` (`GET /tokens`, PRO+) exposes the full filtered/sortable token directory with MC band, liquidity floor, recent-activity window, primary DEX, authority flags, computed 1h volume floor, MEV-share ceiling, and MC change deltas — defaults to `min_liq=2000` to skip dust. Token responses now carry velocity / MEV-share fields. `/token/{mint}` returns structured 400 errors (`code`, `reason`, `example`, `docs`) instead of bare 400s. Deprecated `avg_entry_mc_usd` removed from leaderboards.
+
+## Quick start (10 seconds)
+
+```bash
+npm install solana-agent-kit-plugin-madeonsol
+```
+
+```ts
+import { SolanaAgentKit } from "solana-agent-kit";
+import MadeOnSolPlugin from "solana-agent-kit-plugin-madeonsol";
+const agent = new SolanaAgentKit(privateKey, rpcUrl, { MADEONSOL_API_KEY: "msk_..." }); // free key: https://madeonsol.com/developer
+agent.use(MadeOnSolPlugin);
+const trades = await agent.methods.kolFeed(agent, { limit: 5, action: "buy" });
+```
+
 ## Authentication
 
 Two options (in priority order):
@@ -57,11 +73,14 @@ const events = await agent.methods.walletTrackerTrades(agent, { limit: 50 });
 | `MADEONSOL_DEPLOYER_ALERTS_ACTION` | "deployer alerts", "pump fun launches" |
 | `MADEONSOL_KOL_PNL_ACTION` | "kol pnl", "kol profit", "wallet pnl" |
 | `MADEONSOL_KOL_TRENDING_TOKENS_ACTION` | "kol trending tokens", "kol volume" |
+| `MADEONSOL_KOL_FIRST_TOUCHES_ACTION` | "kol first touch", "first kol buyer", "scout signal" — backtested first-mover signal (new in 1.3) |
 | `MADEONSOL_WALLET_TRACKER_WATCHLIST_ACTION` | "wallet watchlist", "tracked wallets" |
 | `MADEONSOL_WALLET_TRACKER_ADD_ACTION` | "track wallet", "watch wallet", "add to watchlist" |
 | `MADEONSOL_WALLET_TRACKER_REMOVE_ACTION` | "untrack wallet", "remove from watchlist" |
 | `MADEONSOL_WALLET_TRACKER_TRADES_ACTION` | "wallet tracker trades", "watchlist activity" |
 | `MADEONSOL_WALLET_TRACKER_SUMMARY_ACTION` | "wallet tracker summary", "tracked wallet stats" |
+| `MADEONSOL_ME_ACTION` | "my api account", "api quota", "remaining requests" — tier + quota introspection (new in 1.7) |
+| `MADEONSOL_TOKENS_LIST_ACTION` | "filter tokens", "tokens by market cap", "scan tokens" — filtered/sortable token directory, PRO+ (new in 1.7) |
 
 ## Additional methods (v1.0+)
 
@@ -72,7 +91,7 @@ These are exposed via `agent.methods.*` (no LLM action wrappers — call directl
 Scored from 47,000+ early-buyer records (wallets seen in the first 20 buyers of Pump.fun tokens).
 
 ```ts
-await agent.methods.alphaLeaderboard(agent, { limit: 100 });            // BASIC=25, PRO=100, ULTRA=500
+await agent.methods.alphaLeaderboard(agent, { limit: 100 });            // Free/Pro=100, ULTRA=500 + bot signals
 await agent.methods.alphaWallet(agent, { wallet: "WALLET" });           // ULTRA only — full breakdown + bot signals
 await agent.methods.alphaLinked(agent, { wallet: "WALLET" });           // ULTRA only — co-bought 3+ tokens within 2s
 ```
@@ -99,6 +118,65 @@ await agent.methods.copyTradeCreate(agent, {
 await agent.methods.copyTradeSignals(agent, { limit: 50 });             // up to 7 days
 ```
 
+### 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 of the triggering trade (pg_notify push, not polling). Delivered via WebSocket (`kol:coordination` channel, user-scoped) and/or HMAC-signed webhook. PRO=5 rules, ULTRA=20.
+
+```ts
+const res = await agent.methods.coordinationAlertsCreate(agent, {
+  name: "fresh pump cluster",
+  min_kols: 4,
+  window_minutes: 15,     // peak-density window (1-60)
+  min_score: 70,          // 0-100 composite score cutoff
+  include_majors: false,  // filter WIF/BONK/POPCAT
+  cooldown_min: 60,
+  score_jump_break: 10,
+  delivery_mode: "both",
+  webhook_url: "https://you.com/hooks/coord",
+});
+// store res.webhook_secret — shown ONCE
+
+await agent.methods.coordinationAlertsList(agent);
+await agent.methods.coordinationAlertsGet(agent, { rule_id: "uuid..." });
+await agent.methods.coordinationAlertsUpdate(agent, { rule_id: "uuid...", updates: { is_active: false } });
+await agent.methods.coordinationAlertsDelete(agent, { rule_id: "uuid..." });
+```
+
+The v1.1 `kolCoordination()` response also includes `peak_kols`, `peak_buys`, `exited_count`, and `coordination_score` (0-100). Pass `{ min_score, window_minutes, include_majors }` to filter.
+
+### KOL First-Touch Signal *(new in 1.3)*
+
+Every "first KOL buy on a token mint" event — when a tracked KOL is the first of the cohort to touch a token. 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).
+
+```ts
+// REST query — also exposed as MADEONSOL_KOL_FIRST_TOUCHES_ACTION for the agent
+const { events } = await agent.methods.kolFirstTouches(agent, {
+  preset: "scout",
+  min_scout_tier: "S",
+  limit: 20,
+});
+
+// Webhook subscription (Ultra only) — push delivery, HMAC-signed
+const res = await agent.methods.firstTouchSubscriptionsCreate(agent, {
+  name: "S-tier scouts on pump tokens",
+  filters: { min_scout_tier: "S", mint_suffix: "pump" },
+  delivery_mode: "webhook",
+  webhook_url: "https://you.com/hooks/scout",
+});
+// store res.webhook_secret — shown ONCE
+
+await agent.methods.firstTouchSubscriptionsList(agent);
+await agent.methods.firstTouchSubscriptionsGet(agent, { subscription_id: "uuid..." });
+await agent.methods.firstTouchSubscriptionsUpdate(agent, { subscription_id: "uuid...", updates: { is_active: false } });
+await agent.methods.firstTouchSubscriptionsDelete(agent, { subscription_id: "uuid..." });
+```
+
+ULTRA only for subscriptions — up to 10 active per user.
+
+> **Don't poll — push.** Median lead time before the second KOL is 12 seconds. WebSocket channel: `kol:first_touches` (PRO+).
+
 ### Rate-limit headers
 
 Every successful request populates a module-level `lastRateLimit` (limit / remaining / reset / requestId):
@@ -113,17 +191,18 @@ console.log(lastRateLimit); // { limit: "10000", remaining: "9999", reset: "..."
 
 | Tier | Price | Wallets tracked | Requests/day |
 |------|-------|-----------------|--------------|
-| BASIC | Free | 10 | 200 |
-| PRO | $49/mo | 50 | 10,000 |
-| ULTRA | $149/mo | 100 + WS events | 100,000 |
+| Free | $0 | 10 | 200 |
+| Pro | $49/mo | 50 | 10,000 |
+| Ultra | $149/mo | 100 + WS events | 100,000 |
 
-Get a key at [madeonsol.com/developer](https://madeonsol.com/developer).
+Free tier returns the full REST response shape on every endpoint — real wallets, TX signatures, full precision. Paid tiers unlock webhooks, WebSockets, rule engines, and ULTRA-only data depth. Get a key at [madeonsol.com/developer](https://madeonsol.com/developer).
 
 ## 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 |
 | MCP Server (Claude, Cursor) | [`mcp-server-madeonsol`](https://www.npmjs.com/package/mcp-server-madeonsol) |
 | ElizaOS | [`@madeonsol/plugin-madeonsol`](https://www.npmjs.com/package/@madeonsol/plugin-madeonsol) |

package/dist/actions/deployerAlerts.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+export declare const deployerAlertsAction: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        input: {
+            limit: number;
+        };
+        output: {
+            status: string;
+        };
+        explanation: string;
+    }[][];
+    schema: z.ZodObject<{
+        limit: z.ZodDefault<z.ZodNumber>;
+        offset: z.ZodDefault<z.ZodNumber>;
+        since: z.ZodOptional<z.ZodString>;
+        tier: z.ZodOptional<z.ZodEnum<["elite", "good", "moderate", "rising", "cold"]>>;
+    }, "strip", z.ZodTypeAny, {
+        limit: number;
+        offset: number;
+        since?: string | undefined;
+        tier?: "elite" | "good" | "moderate" | "rising" | "cold" | undefined;
+    }, {
+        limit?: number | undefined;
+        since?: string | undefined;
+        offset?: number | undefined;
+        tier?: "elite" | "good" | "moderate" | "rising" | "cold" | undefined;
+    }>;
+    handler: (agent: unknown, input: {
+        limit?: number;
+        offset?: number;
+        since?: string;
+        tier?: "elite" | "good" | "moderate" | "rising" | "cold";
+    }) => Promise<{
+        status: string;
+        result: any;
+        message?: undefined;
+    } | {
+        status: string;
+        message: string;
+        result?: undefined;
+    }>;
+};

package/dist/actions/deployerAlerts.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { deployerAlerts } from "../tools/index.js";
+export const deployerAlertsAction = {
+    name: "MADEONSOL_DEPLOYER_ALERTS_ACTION",
+    similes: ["deployer alerts", "pump fun launches", "new token alerts", "elite deployer tokens"],
+    description: "Get real-time alerts from elite Pump.fun deployers with KOL buy enrichment. Costs $0.01 USDC per request.",
+    examples: [
+        [{ input: { limit: 10 }, output: { status: "success" }, explanation: "Get the 10 most recent deployer alerts" }],
+    ],
+    schema: z.object({
+        limit: z.number().min(1).max(100).default(10).describe("Number of alerts"),
+        offset: z.number().min(0).default(0).describe("Pagination offset"),
+        since: z.string().optional().describe("ISO8601 timestamp to filter alerts after"),
+        tier: z
+            .enum(["elite", "good", "moderate", "rising", "cold"])
+            .optional()
+            .describe("Filter by deployer tier. PRO/ULTRA subscribers only — BASIC callers receive 403."),
+    }),
+    handler: async (agent, input) => {
+        try {
+            const data = await deployerAlerts(agent, input);
+            return { status: "success", result: data };
+        }
+        catch (err) {
+            return { status: "error", message: err.message };
+        }
+    },
+};

package/dist/actions/kolAlertsRecent.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+export declare const kolAlertsRecentAction: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        input: {
+            window: string;
+            limit: number;
+        };
+        output: {
+            status: string;
+        };
+        explanation: string;
+    }[][];
+    schema: z.ZodObject<{
+        window: z.ZodDefault<z.ZodEnum<["5m", "15m", "1h", "6h", "24h"]>>;
+        types: z.ZodOptional<z.ZodArray<z.ZodEnum<["consensus_cluster", "fresh_token_kol_buy", "heating_up"]>, "many">>;
+        min_severity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        limit: number;
+        window: "24h" | "1h" | "6h" | "5m" | "15m";
+        types?: ("consensus_cluster" | "fresh_token_kol_buy" | "heating_up")[] | undefined;
+        min_severity?: "high" | "medium" | "low" | undefined;
+    }, {
+        limit?: number | undefined;
+        types?: ("consensus_cluster" | "fresh_token_kol_buy" | "heating_up")[] | undefined;
+        window?: "24h" | "1h" | "6h" | "5m" | "15m" | undefined;
+        min_severity?: "high" | "medium" | "low" | undefined;
+    }>;
+    handler: (agent: unknown, input: {
+        window?: string;
+        types?: string[];
+        min_severity?: string;
+        limit?: number;
+    }) => Promise<{
+        status: string;
+        result: any;
+        message?: undefined;
+    } | {
+        status: string;
+        message: string;
+        result?: undefined;
+    }>;
+};

package/dist/actions/kolAlertsRecent.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { kolAlertsRecent } from "../tools/index.js";
+export const kolAlertsRecentAction = {
+    name: "MADEONSOL_KOL_ALERTS_RECENT_ACTION",
+    similes: ["kol alerts", "recent kol alerts", "kol signals", "live kol feed", "kol events"],
+    description: "Live KOL alert feed from MadeOnSol — consensus clusters, fresh-token KOL buys, and heating-up wallets unified into one stream. Sorted by detected_at DESC then severity.",
+    examples: [
+        [
+            { input: { window: "15m", limit: 20 }, output: { status: "success" }, explanation: "Show recent KOL alerts in the last 15 minutes" },
+        ],
+    ],
+    schema: z.object({
+        window: z.enum(["5m", "15m", "1h", "6h", "24h"]).default("15m").describe("Lookback window"),
+        types: z.array(z.enum(["consensus_cluster", "fresh_token_kol_buy", "heating_up"])).optional().describe("Filter to specific alert types"),
+        min_severity: z.enum(["low", "medium", "high"]).optional().describe("Minimum severity to include"),
+        limit: z.number().min(1).max(200).default(50).describe("Max alerts"),
+    }),
+    handler: async (agent, input) => {
+        try {
+            const data = await kolAlertsRecent(agent, input);
+            return { status: "success", result: data };
+        }
+        catch (err) {
+            return { status: "error", message: err.message };
+        }
+    },
+};

package/dist/actions/kolCompare.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+export declare const kolCompareAction: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        input: {
+            wallets: string[];
+        };
+        output: {
+            status: string;
+        };
+        explanation: string;
+    }[][];
+    schema: z.ZodObject<{
+        wallets: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        wallets: string[];
+    }, {
+        wallets: string[];
+    }>;
+    handler: (agent: unknown, input: {
+        wallets: string[];
+    }) => Promise<{
+        status: string;
+        result: any;
+        message?: undefined;
+    } | {
+        status: string;
+        message: string;
+        result?: undefined;
+    }>;
+};

package/dist/actions/kolCompare.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { kolCompare } from "../tools/index.js";
+export const kolCompareAction = {
+    name: "MADEONSOL_KOL_COMPARE_ACTION",
+    similes: ["compare kols", "compare wallets", "kol comparison", "side by side kols"],
+    description: "Side-by-side comparison of 2-5 Solana KOL wallets on MadeOnSol — strategy, winrates, ROI, PnL percentiles. PRO+ adds overlap tokens (bought by 2+ in last 30d). BASIC=2, PRO=4, ULTRA=5.",
+    examples: [
+        [
+            { input: { wallets: ["WalletA", "WalletB"] }, output: { status: "success" }, explanation: "Compare two KOL wallets side-by-side" },
+        ],
+    ],
+    schema: z.object({
+        wallets: z.array(z.string()).min(2).max(5).describe("2-5 wallet addresses"),
+    }),
+    handler: async (agent, input) => {
+        try {
+            const data = await kolCompare(agent, input);
+            return { status: "success", result: data };
+        }
+        catch (err) {
+            return { status: "error", message: err.message };
+        }
+    },
+};

package/dist/actions/kolCoordination.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+export declare const kolCoordinationAction: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        input: {
+            period: string;
+            min_kols: number;
+        };
+        output: {
+            status: string;
+        };
+        explanation: string;
+    }[][];
+    schema: z.ZodObject<{
+        period: z.ZodDefault<z.ZodEnum<["1h", "6h", "24h", "7d"]>>;
+        min_kols: z.ZodDefault<z.ZodNumber>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        period: "24h" | "1h" | "6h" | "7d";
+        min_kols: number;
+        limit: number;
+    }, {
+        period?: "24h" | "1h" | "6h" | "7d" | undefined;
+        min_kols?: number | undefined;
+        limit?: number | undefined;
+    }>;
+    handler: (agent: unknown, input: {
+        period?: string;
+        min_kols?: number;
+        limit?: number;
+    }) => Promise<{
+        status: string;
+        result: any;
+        message?: undefined;
+    } | {
+        status: string;
+        message: string;
+        result?: undefined;
+    }>;
+};

package/dist/actions/kolCoordination.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { kolCoordination } from "../tools/index.js";
+export const kolCoordinationAction = {
+    name: "MADEONSOL_KOL_COORDINATION_ACTION",
+    similes: ["kol convergence", "what tokens are kols accumulating", "kol coordination", "smart money convergence"],
+    description: "Get KOL convergence signals — tokens being accumulated by multiple KOLs simultaneously. Costs $0.02 USDC per request.",
+    examples: [
+        [{ input: { period: "24h", min_kols: 3 }, output: { status: "success" }, explanation: "Get tokens where 3+ KOLs are converging in the last 24 hours" }],
+    ],
+    schema: z.object({
+        period: z.enum(["1h", "6h", "24h", "7d"]).default("24h").describe("Time period"),
+        min_kols: z.number().min(2).max(50).default(3).describe("Minimum KOLs converging"),
+        limit: z.number().min(1).max(50).default(20).describe("Number of results"),
+    }),
+    handler: async (agent, input) => {
+        try {
+            const data = await kolCoordination(agent, input);
+            return { status: "success", result: data };
+        }
+        catch (err) {
+            return { status: "error", message: err.message };
+        }
+    },
+};

package/dist/actions/kolFeed.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+export declare const kolFeedAction: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        input: {
+            limit: number;
+            action: string;
+        };
+        output: {
+            status: string;
+        };
+        explanation: string;
+    }[][];
+    schema: z.ZodObject<{
+        limit: z.ZodDefault<z.ZodNumber>;
+        action: z.ZodOptional<z.ZodEnum<["buy", "sell"]>>;
+        kol: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit: number;
+        action?: "buy" | "sell" | undefined;
+        kol?: string | undefined;
+    }, {
+        limit?: number | undefined;
+        action?: "buy" | "sell" | undefined;
+        kol?: string | undefined;
+    }>;
+    handler: (agent: unknown, input: {
+        limit?: number;
+        action?: string;
+        kol?: string;
+    }) => Promise<{
+        status: string;
+        result: any;
+        message?: undefined;
+    } | {
+        status: string;
+        message: string;
+        result?: undefined;
+    }>;
+};

package/dist/actions/kolFeed.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { kolFeed } from "../tools/index.js";
+export const kolFeedAction = {
+    name: "MADEONSOL_KOL_FEED_ACTION",
+    similes: ["kol trades", "what are kols buying", "kol feed", "smart money trades", "kol activity"],
+    description: "Get real-time Solana KOL trades from 1,000+ tracked wallets via MadeOnSol x402 API. Costs $0.005 USDC per request.",
+    examples: [
+        [{ input: { limit: 10, action: "buy" }, output: { status: "success" }, explanation: "Fetch the 10 most recent KOL buy trades" }],
+    ],
+    schema: z.object({
+        limit: z.number().min(1).max(100).default(10).describe("Number of trades"),
+        action: z.enum(["buy", "sell"]).optional().describe("Filter by trade type"),
+        kol: z.string().optional().describe("Filter by KOL wallet address"),
+    }),
+    handler: async (agent, input) => {
+        try {
+            const data = await kolFeed(agent, input);
+            return { status: "success", result: data };
+        }
+        catch (err) {
+            return { status: "error", message: err.message };
+        }
+    },
+};

package/dist/actions/kolFirstTouches.d.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+export declare const kolFirstTouchesAction: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        input: {
+            preset: string;
+            limit: number;
+        };
+        output: {
+            status: string;
+        };
+        explanation: string;
+    }[][];
+    schema: z.ZodObject<{
+        limit: z.ZodDefault<z.ZodNumber>;
+        since: z.ZodOptional<z.ZodString>;
+        before: z.ZodOptional<z.ZodString>;
+        kol: z.ZodOptional<z.ZodString>;
+        min_kol_winrate_7d: z.ZodOptional<z.ZodNumber>;
+        min_scout_tier: z.ZodOptional<z.ZodEnum<["S", "A", "B", "C"]>>;
+        min_n_touches: z.ZodOptional<z.ZodNumber>;
+        strategy: z.ZodOptional<z.ZodEnum<["scalper", "day_trader", "swing_trader", "hodler", "mixed"]>>;
+        token_age_max_min: z.ZodOptional<z.ZodNumber>;
+        min_first_buy_sol: z.ZodOptional<z.ZodNumber>;
+        mint_suffix: z.ZodOptional<z.ZodString>;
+        preset: z.ZodOptional<z.ZodEnum<["scout", "fresh_launch"]>>;
+        include: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit: number;
+        before?: string | undefined;
+        since?: string | undefined;
+        kol?: string | undefined;
+        min_kol_winrate_7d?: number | undefined;
+        min_scout_tier?: "S" | "A" | "B" | "C" | undefined;
+        min_n_touches?: number | undefined;
+        strategy?: "scalper" | "day_trader" | "swing_trader" | "hodler" | "mixed" | undefined;
+        token_age_max_min?: number | undefined;
+        min_first_buy_sol?: number | undefined;
+        mint_suffix?: string | undefined;
+        preset?: "scout" | "fresh_launch" | undefined;
+        include?: string | undefined;
+    }, {
+        limit?: number | undefined;
+        before?: string | undefined;
+        since?: string | undefined;
+        kol?: string | undefined;
+        min_kol_winrate_7d?: number | undefined;
+        min_scout_tier?: "S" | "A" | "B" | "C" | undefined;
+        min_n_touches?: number | undefined;
+        strategy?: "scalper" | "day_trader" | "swing_trader" | "hodler" | "mixed" | undefined;
+        token_age_max_min?: number | undefined;
+        min_first_buy_sol?: number | undefined;
+        mint_suffix?: string | undefined;
+        preset?: "scout" | "fresh_launch" | undefined;
+        include?: string | undefined;
+    }>;
+    handler: (agent: unknown, input: {
+        limit?: number;
+        since?: string;
+        before?: string;
+        kol?: string;
+        min_kol_winrate_7d?: number;
+        min_scout_tier?: "S" | "A" | "B" | "C";
+        min_n_touches?: number;
+        strategy?: "scalper" | "day_trader" | "swing_trader" | "hodler" | "mixed";
+        token_age_max_min?: number;
+        min_first_buy_sol?: number;
+        mint_suffix?: string;
+        preset?: "scout" | "fresh_launch";
+        include?: string;
+    }) => Promise<{
+        status: string;
+        result: any;
+        message?: undefined;
+    } | {
+        status: string;
+        message: string;
+        result?: undefined;
+    }>;
+};

package/dist/actions/kolFirstTouches.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { kolFirstTouches } from "../tools/index.js";
+export const kolFirstTouchesAction = {
+    name: "MADEONSOL_KOL_FIRST_TOUCHES_ACTION",
+    similes: [
+        "kol first touch",
+        "first kol buyer",
+        "scout signal",
+        "smart money first buyer",
+        "kol scout alert",
+        "first buy by kol",
+    ],
+    description: "Get the most recent first-KOL-touch events on Solana tokens — the moment a tracked KOL was the first to buy a given mint. Filterable by scout tier (S/A/B/C from mv_kol_scout_score), KOL winrate, token age, mint suffix. Backtest: top scouts attract >=3 follow-on KOLs within 4h ~50% of the time vs ~14% baseline.",
+    examples: [
+        [
+            {
+                input: { preset: "scout", limit: 10 },
+                output: { status: "success" },
+                explanation: "Fetch 10 recent first-touch events from B-tier-or-better scouts on tokens younger than 60 minutes",
+            },
+        ],
+    ],
+    schema: z.object({
+        limit: z.number().min(1).max(100).default(20).describe("Number of events (1-100)"),
+        since: z.string().optional().describe("ISO timestamp — events strictly newer than this"),
+        before: z.string().optional().describe("ISO timestamp — events strictly older than this (pagination cursor)"),
+        kol: z.string().optional().describe("Single KOL wallet address (base58)"),
+        min_kol_winrate_7d: z.number().min(0).max(100).optional(),
+        min_scout_tier: z.enum(["S", "A", "B", "C"]).optional().describe("Scout tier S/A/B/C (S = highest)"),
+        min_n_touches: z.number().min(1).optional(),
+        strategy: z.enum(["scalper", "day_trader", "swing_trader", "hodler", "mixed"]).optional(),
+        token_age_max_min: z.number().min(1).optional().describe("Only events on tokens younger than N minutes"),
+        min_first_buy_sol: z.number().min(0).optional(),
+        mint_suffix: z.string().optional().describe("Suffix-filter the token mint (e.g. 'pump')"),
+        preset: z.enum(["scout", "fresh_launch"]).optional(),
+        include: z.string().optional().describe("Comma-separated includes — currently 'followers_4h'"),
+    }),
+    handler: async (agent, input) => {
+        try {
+            const data = await kolFirstTouches(agent, input);
+            return { status: "success", result: data };
+        }
+        catch (err) {
+            return { status: "error", message: err.message };
+        }
+    },
+};

package/dist/actions/kolLeaderboard.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+export declare const kolLeaderboardAction: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        input: {
+            period: string;
+            limit: number;
+        };
+        output: {
+            status: string;
+        };
+        explanation: string;
+    }[][];
+    schema: z.ZodObject<{
+        period: z.ZodDefault<z.ZodEnum<["today", "7d", "30d"]>>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        period: "7d" | "today" | "30d";
+        limit: number;
+    }, {
+        period?: "7d" | "today" | "30d" | undefined;
+        limit?: number | undefined;
+    }>;
+    handler: (agent: unknown, input: {
+        period?: string;
+        limit?: number;
+    }) => Promise<{
+        status: string;
+        result: any;
+        message?: undefined;
+    } | {
+        status: string;
+        message: string;
+        result?: undefined;
+    }>;
+};