@madeonsol/plugin-madeonsol 0.2.0 → 0.3.0

package/README.md

@@ -1,24 +1,36 @@
 # @madeonsol/plugin-madeonsol
 
-ElizaOS plugin for [MadeOnSol](https://madeonsol.com) — Solana KOL trading intelligence and deployer analytics via x402 micropayments.
+ElizaOS plugin for [MadeOnSol](https://madeonsol.com) — Solana KOL trading intelligence and deployer analytics.
+
+## Authentication
+
+Three options (in priority order):
+
+| Method | Setting | Best for |
+|---|---|---|
+| **MadeOnSol API key** (recommended) | `MADEONSOL_API_KEY` | Developers — [get a free key](https://madeonsol.com/developer) |
+| RapidAPI key | `RAPIDAPI_KEY` | RapidAPI subscribers |
+| x402 micropayments | `SVM_PRIVATE_KEY` | AI agents with Solana wallets |
 
 ## What it does
 
-Gives your ElizaOS agent access to MadeOnSol's x402-gated API endpoints. The agent pays per request with USDC on Solana — no API keys needed.
+Gives your ElizaOS agent access to MadeOnSol's Solana intelligence API.
 
-| Action | Endpoint | Price |
-|--------|----------|-------|
-| `GET_KOL_FEED` | Real-time KOL trade feed (946 wallets) | $0.005 USDC |
-| `GET_KOL_COORDINATION` | Multi-KOL convergence signals | $0.02 USDC |
-| `GET_KOL_LEADERBOARD` | KOL PnL/win-rate rankings | $0.005 USDC |
-| `GET_DEPLOYER_ALERTS` | Pump.fun elite deployer alerts | $0.01 USDC |
+| Action | Endpoint |
+|--------|----------|
+| `GET_KOL_FEED` | Real-time KOL trade feed (946 wallets) |
+| `GET_KOL_COORDINATION` | Multi-KOL convergence signals |
+| `GET_KOL_LEADERBOARD` | KOL PnL/win-rate rankings |
+| `GET_DEPLOYER_ALERTS` | Pump.fun elite deployer alerts |
 
 ## Install
 
 ```bash
-npm install @madeonsol/plugin-madeonsol @x402/fetch @x402/svm @x402/core @solana/kit @scure/base
+npm install @madeonsol/plugin-madeonsol
 ```
 
+> x402 peer deps (`@x402/fetch @x402/svm @x402/core @solana/kit @scure/base`) are only needed when using `SVM_PRIVATE_KEY`.
+
 ## Usage
 
 ```typescript
@@ -27,40 +39,31 @@ import { madeOnSolPlugin } from "@madeonsol/plugin-madeonsol";
 const agent = {
   plugins: [madeOnSolPlugin],
   settings: {
-    // Required for automatic x402 payments:
-    SVM_PRIVATE_KEY: "your_base58_solana_private_key",
-    // Optional:
-    MADEONSOL_API_URL: "https://madeonsol.com",
+    // Option 1: API key (simplest — get one free at madeonsol.com/developer)
+    MADEONSOL_API_KEY: "msk_your_api_key_here",
+
+    // Option 2: RapidAPI key
+    // RAPIDAPI_KEY: "your_rapidapi_key",
+
+    // Option 3: x402 micropayments (AI agents)
+    // SVM_PRIVATE_KEY: "your_base58_solana_private_key",
   },
 };
 ```
 
-The plugin's `init` function automatically:
-1. Creates a Solana signer from `SVM_PRIVATE_KEY`
-2. Registers the x402 payment scheme
-3. Wraps fetch with automatic 402 → pay → retry handling
-
 Your agent can then respond to queries like:
 - "What are KOLs buying right now?"
 - "Show me the KOL leaderboard this week"
 - "What tokens are multiple KOLs accumulating?"
 - "Any new deployer alerts from Pump.fun?"
 
-Without `SVM_PRIVATE_KEY`, the plugin runs in read-only mode and returns payment requirement info instead of data.
-
-## Wallet requirements
-
-The wallet needs:
-- ~0.01 SOL for transaction fees
-- USDC balance (even $0.10 covers 20+ requests)
-
 ## Discovery endpoint
 
 ```
 GET https://madeonsol.com/api/x402
 ```
 
-Returns all available endpoints, prices, and parameter docs. No payment required.
+Returns all available endpoints, prices, and parameter docs. No auth required.
 
 ## Also Available
 

package/dist/actions/deployer-alerts.js

@@ -24,7 +24,7 @@ export const deployerAlertsAction = {
         const result = await client.getDeployerAlerts({ limit });
         if (result.error) {
             callback?.({ text: result.status === 402
-                    ? "x402 payment required but no wallet configured. Set SVM_PRIVATE_KEY to enable automatic USDC payments."
+                    ? "Authentication required. Set MADEONSOL_API_KEY (free at madeonsol.com/developer), RAPIDAPI_KEY, or SVM_PRIVATE_KEY."
                     : `Error: ${result.error}` });
             return undefined;
         }

package/dist/actions/kol-coordination.js

@@ -24,7 +24,7 @@ export const kolCoordinationAction = {
         const result = await client.getKolCoordination({ period, limit: "10" });
         if (result.error) {
             callback?.({ text: result.status === 402
-                    ? "x402 payment required but no wallet configured. Set SVM_PRIVATE_KEY to enable automatic USDC payments."
+                    ? "Authentication required. Set MADEONSOL_API_KEY (free at madeonsol.com/developer), RAPIDAPI_KEY, or SVM_PRIVATE_KEY."
                     : `Error: ${result.error}` });
             return undefined;
         }

package/dist/actions/kol-feed.js

@@ -25,7 +25,7 @@ export const kolFeedAction = {
         const result = await client.getKolFeed({ limit: "10", ...(action ? { action } : {}) });
         if (result.error) {
             callback?.({ text: result.status === 402
-                    ? "x402 payment required but no wallet configured. Set SVM_PRIVATE_KEY to enable automatic USDC payments."
+                    ? "Authentication required. Set MADEONSOL_API_KEY (free at madeonsol.com/developer), RAPIDAPI_KEY, or SVM_PRIVATE_KEY."
                     : `Error: ${result.error}` });
             return undefined;
         }

package/dist/actions/kol-leaderboard.js

@@ -24,7 +24,7 @@ export const kolLeaderboardAction = {
         const result = await client.getKolLeaderboard({ period, limit: "10" });
         if (result.error) {
             callback?.({ text: result.status === 402
-                    ? "x402 payment required but no wallet configured. Set SVM_PRIVATE_KEY to enable automatic USDC payments."
+                    ? "Authentication required. Set MADEONSOL_API_KEY (free at madeonsol.com/developer), RAPIDAPI_KEY, or SVM_PRIVATE_KEY."
                     : `Error: ${result.error}` });
             return undefined;
         }

package/dist/client.d.ts

@@ -1,19 +1,21 @@
 /**
- * MadeOnSol x402 API client.
- * Uses @x402/fetch to automatically handle 402 → sign USDC → retry flow.
+ * MadeOnSol API client.
+ * Supports 3 auth modes: API key (simplest), RapidAPI key, or x402 micropayments.
  */
 export interface MadeOnSolClientOptions {
     baseUrl?: string;
-    /**
-     * A fetch function that handles x402 payments automatically.
-     * Created via wrapFetchWithPayment() from @x402/fetch.
-     * If not provided, uses plain fetch (requests will return 402).
-     */
+    /** MadeOnSol API key (get one free at madeonsol.com/developer). Preferred. */
+    apiKey?: string;
+    /** RapidAPI subscription key. */
+    rapidApiKey?: string;
+    /** x402 payment-enabled fetch (for AI agents with SVM_PRIVATE_KEY). */
     fetchFn?: typeof fetch;
 }
 export declare class MadeOnSolClient {
     private baseUrl;
     private fetchFn;
+    private authMode;
+    private authHeaders;
     constructor(options?: MadeOnSolClientOptions);
     query<T = unknown>(path: string, params?: Record<string, string | undefined>): Promise<{
         data?: T;
@@ -55,4 +57,34 @@ export declare class MadeOnSolClient {
         error?: string;
         status: number;
     }>;
+    private restRequest;
+    createWebhook(params: {
+        url: string;
+        events: string[];
+        filters?: Record<string, unknown>;
+    }): Promise<{
+        data?: unknown;
+        error?: string;
+        status: number;
+    }>;
+    listWebhooks(): Promise<{
+        data?: unknown;
+        error?: string;
+        status: number;
+    }>;
+    deleteWebhook(id: number): Promise<{
+        data?: unknown;
+        error?: string;
+        status: number;
+    }>;
+    testWebhook(webhookId: number): Promise<{
+        data?: unknown;
+        error?: string;
+        status: number;
+    }>;
+    getStreamToken(): Promise<{
+        data?: unknown;
+        error?: string;
+        status: number;
+    }>;
 }

package/dist/client.js

@@ -1,24 +1,47 @@
 /**
- * MadeOnSol x402 API client.
- * Uses @x402/fetch to automatically handle 402 → sign USDC → retry flow.
+ * MadeOnSol API client.
+ * Supports 3 auth modes: API key (simplest), RapidAPI key, or x402 micropayments.
  */
 const DEFAULT_BASE = "https://madeonsol.com";
+const RAPIDAPI_HOST = "madeonsol-solana-kol-tracker-tools-api.p.rapidapi.com";
 export class MadeOnSolClient {
     baseUrl;
     fetchFn;
+    authMode;
+    authHeaders;
     constructor(options = {}) {
         this.baseUrl = options.baseUrl || DEFAULT_BASE;
         this.fetchFn = options.fetchFn || globalThis.fetch;
+        this.authHeaders = {};
+        if (options.apiKey) {
+            this.authMode = "madeonsol";
+            this.authHeaders = { Authorization: `Bearer ${options.apiKey}` };
+        }
+        else if (options.rapidApiKey) {
+            this.authMode = "rapidapi";
+            this.authHeaders = { "x-rapidapi-key": options.rapidApiKey, "x-rapidapi-host": RAPIDAPI_HOST };
+        }
+        else if (options.fetchFn) {
+            this.authMode = "x402";
+        }
+        else {
+            this.authMode = "none";
+        }
     }
     async query(path, params) {
-        const url = new URL(path, this.baseUrl);
+        const apiPath = this.authMode === "x402" || this.authMode === "none"
+            ? path
+            : path.replace("/api/x402/", "/api/v1/");
+        const url = new URL(apiPath, this.baseUrl);
         if (params) {
             for (const [k, v] of Object.entries(params)) {
                 if (v !== undefined)
                     url.searchParams.set(k, v);
             }
         }
-        const res = await this.fetchFn(url.toString(), { method: "GET" });
+        const res = this.authMode === "x402"
+            ? await this.fetchFn(url.toString(), { method: "GET" })
+            : await this.fetchFn(url.toString(), { method: "GET", headers: this.authHeaders });
         if (res.status === 402) {
             const body = await res.json();
             return { error: `Payment required: ${JSON.stringify(body.accepts?.[0] || body)}`, status: 402 };
@@ -42,4 +65,38 @@ export class MadeOnSolClient {
     getDeployerAlerts(params) {
         return this.query("/api/x402/deployer-hunter/alerts", params);
     }
+    // ── Webhook management (requires API key or RapidAPI key with Pro/Ultra) ──
+    async restRequest(method, path, body) {
+        if (this.authMode !== "madeonsol" && this.authMode !== "rapidapi") {
+            return { error: "API key or RapidAPI key required for webhook/streaming features. Get a free key at madeonsol.com/developer", status: 401 };
+        }
+        const res = await this.fetchFn(`${this.baseUrl}/api/v1${path}`, {
+            method,
+            headers: {
+                "Content-Type": "application/json",
+                ...this.authHeaders,
+            },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "Unknown error");
+            return { error: text, status: res.status };
+        }
+        return { data: await res.json(), status: res.status };
+    }
+    createWebhook(params) {
+        return this.restRequest("POST", "/webhooks", params);
+    }
+    listWebhooks() {
+        return this.restRequest("GET", "/webhooks");
+    }
+    deleteWebhook(id) {
+        return this.restRequest("DELETE", `/webhooks/${id}`);
+    }
+    testWebhook(webhookId) {
+        return this.restRequest("POST", "/webhooks/test", { webhook_id: webhookId });
+    }
+    getStreamToken() {
+        return this.restRequest("POST", "/stream/token");
+    }
 }

package/dist/index.js

@@ -7,7 +7,7 @@ import { MadeOnSolClient } from "./client.js";
 export const MADEONSOL_CLIENT_KEY = "madeonsol:client";
 export const madeOnSolPlugin = {
     name: "madeonsol",
-    description: "Query Solana KOL trading intelligence and deployer analytics from MadeOnSol via x402 micropayments. Tracks 946 KOL wallets and 4000+ Pump.fun deployers.",
+    description: "Query Solana KOL trading intelligence and deployer analytics from MadeOnSol. Tracks 946 KOL wallets and 4000+ Pump.fun deployers.",
     actions: [
         kolFeedAction,
         kolCoordinationAction,
@@ -15,15 +15,23 @@ export const madeOnSolPlugin = {
         deployerAlertsAction,
     ],
     /**
-     * Initialize the x402 payment-enabled client.
-     * Requires SVM_PRIVATE_KEY in the runtime settings for automatic payments.
-     * Without it, the plugin still works but requests will return 402 payment info.
+     * Initialize the MadeOnSol client.
+     * Auth priority: MADEONSOL_API_KEY > RAPIDAPI_KEY > SVM_PRIVATE_KEY (x402).
+     * Get a free API key at madeonsol.com/developer — no wallet needed.
      */
     init: async (_config, runtime) => {
         const baseUrl = String(runtime.getSetting?.("MADEONSOL_API_URL") || "https://madeonsol.com");
+        const apiKey = runtime.getSetting?.("MADEONSOL_API_KEY");
+        const rapidApiKey = runtime.getSetting?.("RAPIDAPI_KEY");
         const privateKey = runtime.getSetting?.("SVM_PRIVATE_KEY");
         let fetchFn;
-        if (privateKey) {
+        if (apiKey) {
+            console.log("[madeonsol] Using MadeOnSol API key (Bearer auth)");
+        }
+        else if (rapidApiKey) {
+            console.log("[madeonsol] Using RapidAPI key");
+        }
+        else if (privateKey) {
             try {
                 const { wrapFetchWithPayment } = await import("@x402/fetch");
                 const { x402Client } = await import("@x402/core/client");
@@ -37,13 +45,13 @@ export const madeOnSolPlugin = {
                 console.log(`[madeonsol] x402 payments enabled, wallet: ${signer.address}`);
             }
             catch (err) {
-                console.warn("[madeonsol] x402 payment setup failed, running in read-only mode:", err);
+                console.warn("[madeonsol] x402 payment setup failed:", err);
             }
         }
         else {
-            console.log("[madeonsol] No SVM_PRIVATE_KEY — running in read-only mode (402 info only)");
+            console.log("[madeonsol] No auth configured. Set MADEONSOL_API_KEY (free at madeonsol.com/developer), RAPIDAPI_KEY, or SVM_PRIVATE_KEY.");
         }
-        const madeOnSolClient = new MadeOnSolClient({ baseUrl, fetchFn });
+        const madeOnSolClient = new MadeOnSolClient({ baseUrl, apiKey, rapidApiKey, fetchFn });
         runtime[MADEONSOL_CLIENT_KEY] = madeOnSolClient;
     },
 };

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@madeonsol/plugin-madeonsol",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "ElizaOS plugin for MadeOnSol — Solana KOL intelligence and deployer analytics via x402 micropayments",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist", "README.md"],
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": ""
+    "dev": "tsc --watch"
   },
   "peerDependencies": {
     "@elizaos/core": ">=1.0.0",

package/src/actions/deployer-alerts.ts

@@ -0,0 +1,67 @@
+import type { Action, IAgentRuntime, Memory, State, HandlerCallback } from "@elizaos/core";
+import { MadeOnSolClient } from "../client.js";
+import { MADEONSOL_CLIENT_KEY } from "../index.js";
+
+function getClient(runtime: IAgentRuntime): MadeOnSolClient {
+  return ((runtime as unknown as Record<string, unknown>)[MADEONSOL_CLIENT_KEY] as MadeOnSolClient) ?? new MadeOnSolClient();
+}
+
+export const deployerAlertsAction: Action = {
+  name: "GET_DEPLOYER_ALERTS",
+  description:
+    "Get real-time Pump.fun deployer alerts from MadeOnSol. Shows new token launches from tracked elite/good deployers with stats, market cap, and KOL buy enrichment.",
+  similes: [
+    "deployer alerts",
+    "pump fun launches",
+    "new token alerts",
+    "deployer tracker",
+    "elite deployer tokens",
+  ],
+
+  validate: async (_runtime: IAgentRuntime, message: Memory): Promise<boolean> => {
+    const text = (message.content?.text || "").toLowerCase();
+    return /\b(deployer|pump\.?fun|launch|new token)/i.test(text) && /\b(alert|track|monitor|latest|recent)/i.test(text);
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State,
+    _options?: unknown,
+    callback?: HandlerCallback,
+  ) => {
+    const client = getClient(runtime);
+    const text = (message.content?.text || "").toLowerCase();
+    const limit = text.match(/\b(\d+)\s*(alert|token|launch)/)?.[1] || "10";
+
+    const result = await client.getDeployerAlerts({ limit });
+
+    if (result.error) {
+      callback?.({ text: result.status === 402
+        ? "Authentication required. Set MADEONSOL_API_KEY (free at madeonsol.com/developer), RAPIDAPI_KEY, or SVM_PRIVATE_KEY."
+        : `Error: ${result.error}` });
+      return undefined;
+    }
+
+    const data = result.data as { alerts: Array<{ title: string; token_symbol: string; priority: string; market_cap_at_alert: number | null; deployers: { tier: string; bonding_rate: number | null }; kol_buys: { count: number; kols: string[] } | null }> };
+    const lines = (data.alerts || []).slice(0, 10).map((a) => {
+      const deployer = a.deployers as unknown as { tier: string; bonding_rate: number | null };
+      const mc = a.market_cap_at_alert ? `$${(a.market_cap_at_alert / 1000).toFixed(1)}k` : "?";
+      const kols = a.kol_buys ? `${a.kol_buys.count} KOLs buying` : "";
+      return `[${deployer?.tier}] ${a.token_symbol || "?"} — MC: ${mc}${kols ? ` | ${kols}` : ""}`;
+    });
+
+    callback?.({
+      text: `Deployer Alerts:\n${lines.join("\n") || "No recent alerts."}`,
+      content: data,
+    });
+    return undefined;
+  },
+
+  examples: [
+    [
+      { name: "user1", content: { text: "Show me the latest deployer alerts from Pump.fun" } },
+      { name: "assistant", content: { text: "Here are the latest deployer alerts..." } },
+    ],
+  ] as Action["examples"],
+};

package/src/actions/kol-coordination.ts

@@ -0,0 +1,64 @@
+import type { Action, IAgentRuntime, Memory, State, HandlerCallback } from "@elizaos/core";
+import { MadeOnSolClient } from "../client.js";
+import { MADEONSOL_CLIENT_KEY } from "../index.js";
+
+function getClient(runtime: IAgentRuntime): MadeOnSolClient {
+  return ((runtime as unknown as Record<string, unknown>)[MADEONSOL_CLIENT_KEY] as MadeOnSolClient) ?? new MadeOnSolClient();
+}
+
+export const kolCoordinationAction: Action = {
+  name: "GET_KOL_COORDINATION",
+  description:
+    "Get KOL convergence signals from MadeOnSol — tokens being accumulated by multiple KOLs simultaneously. Shows which tokens smart money is converging on.",
+  similes: [
+    "kol convergence",
+    "what tokens are kols accumulating",
+    "kol coordination",
+    "smart money convergence",
+    "multiple kols buying",
+  ],
+
+  validate: async (_runtime: IAgentRuntime, message: Memory): Promise<boolean> => {
+    const text = (message.content?.text || "").toLowerCase();
+    return /\b(kol|smart money)\b/.test(text) && /\b(converg|coordinat|accumul|same token|multiple)/i.test(text);
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State,
+    _options?: unknown,
+    callback?: HandlerCallback,
+  ) => {
+    const client = getClient(runtime);
+    const text = (message.content?.text || "").toLowerCase();
+    const period = text.includes("1h") ? "1h" : text.includes("7d") ? "7d" : text.includes("6h") ? "6h" : "24h";
+
+    const result = await client.getKolCoordination({ period, limit: "10" });
+
+    if (result.error) {
+      callback?.({ text: result.status === 402
+        ? "Authentication required. Set MADEONSOL_API_KEY (free at madeonsol.com/developer), RAPIDAPI_KEY, or SVM_PRIVATE_KEY."
+        : `Error: ${result.error}` });
+      return undefined;
+    }
+
+    const data = result.data as { coordination: Array<{ token_symbol: string; kol_count: number; signal: string; net_sol_flow: number }> };
+    const lines = (data.coordination || []).map(
+      (t) => `${t.token_symbol}: ${t.kol_count} KOLs ${t.signal} (${t.net_sol_flow > 0 ? "+" : ""}${t.net_sol_flow.toFixed(2)} SOL net)`
+    );
+
+    callback?.({
+      text: `KOL convergence signals (${period}):\n${lines.join("\n") || "No coordination signals found."}`,
+      content: data,
+    });
+    return undefined;
+  },
+
+  examples: [
+    [
+      { name: "user1", content: { text: "What tokens are multiple KOLs accumulating?" } },
+      { name: "assistant", content: { text: "Here are the KOL convergence signals..." } },
+    ],
+  ] as Action["examples"],
+};

package/src/actions/kol-feed.ts

@@ -0,0 +1,65 @@
+import type { Action, IAgentRuntime, Memory, State, HandlerCallback } from "@elizaos/core";
+import { MadeOnSolClient } from "../client.js";
+import { MADEONSOL_CLIENT_KEY } from "../index.js";
+
+function getClient(runtime: IAgentRuntime): MadeOnSolClient {
+  return ((runtime as unknown as Record<string, unknown>)[MADEONSOL_CLIENT_KEY] as MadeOnSolClient) ?? new MadeOnSolClient();
+}
+
+export const kolFeedAction: Action = {
+  name: "GET_KOL_FEED",
+  description:
+    "Get the real-time Solana KOL trade feed from MadeOnSol. Shows latest buys and sells from 946 tracked KOL wallets with deployer enrichment.",
+  similes: [
+    "kol trades",
+    "what are kols buying",
+    "solana kol feed",
+    "kol activity",
+    "smart money trades",
+    "what did kols trade",
+  ],
+
+  validate: async (_runtime: IAgentRuntime, message: Memory): Promise<boolean> => {
+    const text = (message.content?.text || "").toLowerCase();
+    return /\b(kol|smart money)\b/.test(text) && /\b(feed|trade|buy|sell|activit)/i.test(text);
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State,
+    _options?: unknown,
+    callback?: HandlerCallback,
+  ) => {
+    const client = getClient(runtime);
+    const text = (message.content?.text || "").toLowerCase();
+    const action = text.includes("buy") ? "buy" : text.includes("sell") ? "sell" : undefined;
+
+    const result = await client.getKolFeed({ limit: "10", ...(action ? { action } : {}) });
+
+    if (result.error) {
+      callback?.({ text: result.status === 402
+        ? "Authentication required. Set MADEONSOL_API_KEY (free at madeonsol.com/developer), RAPIDAPI_KEY, or SVM_PRIVATE_KEY."
+        : `Error: ${result.error}` });
+      return undefined;
+    }
+
+    const data = result.data as { trades: Array<{ kol_name: string; token_symbol: string; action: string; sol_amount: number; traded_at: string }> };
+    const lines = (data.trades || []).slice(0, 10).map(
+      (t) => `${t.kol_name || "Unknown"} ${t.action === "buy" ? "bought" : "sold"} ${t.token_symbol || "?"} for ${Number(t.sol_amount).toFixed(2)} SOL`
+    );
+
+    callback?.({
+      text: `Latest KOL trades:\n${lines.join("\n")}`,
+      content: data,
+    });
+    return undefined;
+  },
+
+  examples: [
+    [
+      { name: "user1", content: { text: "What are the latest KOL trades on Solana?" } },
+      { name: "assistant", content: { text: "Here are the latest KOL trades from MadeOnSol..." } },
+    ],
+  ] as Action["examples"],
+};

package/src/actions/kol-leaderboard.ts

@@ -0,0 +1,64 @@
+import type { Action, IAgentRuntime, Memory, State, HandlerCallback } from "@elizaos/core";
+import { MadeOnSolClient } from "../client.js";
+import { MADEONSOL_CLIENT_KEY } from "../index.js";
+
+function getClient(runtime: IAgentRuntime): MadeOnSolClient {
+  return ((runtime as unknown as Record<string, unknown>)[MADEONSOL_CLIENT_KEY] as MadeOnSolClient) ?? new MadeOnSolClient();
+}
+
+export const kolLeaderboardAction: Action = {
+  name: "GET_KOL_LEADERBOARD",
+  description:
+    "Get KOL performance rankings from MadeOnSol — top Solana KOLs ranked by PnL, volume, and win rate.",
+  similes: [
+    "kol leaderboard",
+    "best performing kols",
+    "top kol traders",
+    "kol rankings",
+    "who is the best kol",
+  ],
+
+  validate: async (_runtime: IAgentRuntime, message: Memory): Promise<boolean> => {
+    const text = (message.content?.text || "").toLowerCase();
+    return /\b(kol|smart money)\b/.test(text) && /\b(leaderboard|ranking|top|best|perform|pnl|win rate)/i.test(text);
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State,
+    _options?: unknown,
+    callback?: HandlerCallback,
+  ) => {
+    const client = getClient(runtime);
+    const text = (message.content?.text || "").toLowerCase();
+    const period = text.includes("today") ? "today" : text.includes("30d") || text.includes("month") ? "30d" : "7d";
+
+    const result = await client.getKolLeaderboard({ period, limit: "10" });
+
+    if (result.error) {
+      callback?.({ text: result.status === 402
+        ? "Authentication required. Set MADEONSOL_API_KEY (free at madeonsol.com/developer), RAPIDAPI_KEY, or SVM_PRIVATE_KEY."
+        : `Error: ${result.error}` });
+      return undefined;
+    }
+
+    const data = result.data as { leaderboard: Array<{ name: string; pnl_sol: number; buy_count: number; sell_count: number; win_rate: number | null }> };
+    const lines = (data.leaderboard || []).map(
+      (k, i) => `${i + 1}. ${k.name}: ${k.pnl_sol > 0 ? "+" : ""}${k.pnl_sol.toFixed(2)} SOL PnL (${k.buy_count}B/${k.sell_count}S${k.win_rate != null ? `, ${(k.win_rate * 100).toFixed(0)}% WR` : ""})`
+    );
+
+    callback?.({
+      text: `KOL Leaderboard (${period}):\n${lines.join("\n") || "No data for this period."}`,
+      content: data,
+    });
+    return undefined;
+  },
+
+  examples: [
+    [
+      { name: "user1", content: { text: "Show me the top performing KOLs this week" } },
+      { name: "assistant", content: { text: "Here are the top KOLs by PnL..." } },
+    ],
+  ] as Action["examples"],
+};

package/src/client.ts

@@ -0,0 +1,130 @@
+/**
+ * MadeOnSol API client.
+ * Supports 3 auth modes: API key (simplest), RapidAPI key, or x402 micropayments.
+ */
+
+const DEFAULT_BASE = "https://madeonsol.com";
+const RAPIDAPI_HOST = "madeonsol-solana-kol-tracker-tools-api.p.rapidapi.com";
+
+type AuthMode = "madeonsol" | "rapidapi" | "x402" | "none";
+
+export interface MadeOnSolClientOptions {
+  baseUrl?: string;
+  /** MadeOnSol API key (get one free at madeonsol.com/developer). Preferred. */
+  apiKey?: string;
+  /** RapidAPI subscription key. */
+  rapidApiKey?: string;
+  /** x402 payment-enabled fetch (for AI agents with SVM_PRIVATE_KEY). */
+  fetchFn?: typeof fetch;
+}
+
+export class MadeOnSolClient {
+  private baseUrl: string;
+  private fetchFn: typeof fetch;
+  private authMode: AuthMode;
+  private authHeaders: Record<string, string>;
+
+  constructor(options: MadeOnSolClientOptions = {}) {
+    this.baseUrl = options.baseUrl || DEFAULT_BASE;
+    this.fetchFn = options.fetchFn || globalThis.fetch;
+    this.authHeaders = {};
+
+    if (options.apiKey) {
+      this.authMode = "madeonsol";
+      this.authHeaders = { Authorization: `Bearer ${options.apiKey}` };
+    } else if (options.rapidApiKey) {
+      this.authMode = "rapidapi";
+      this.authHeaders = { "x-rapidapi-key": options.rapidApiKey, "x-rapidapi-host": RAPIDAPI_HOST };
+    } else if (options.fetchFn) {
+      this.authMode = "x402";
+    } else {
+      this.authMode = "none";
+    }
+  }
+
+  async query<T = unknown>(path: string, params?: Record<string, string | undefined>): Promise<{ data?: T; error?: string; status: number }> {
+    const apiPath = this.authMode === "x402" || this.authMode === "none"
+      ? path
+      : path.replace("/api/x402/", "/api/v1/");
+    const url = new URL(apiPath, this.baseUrl);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined) url.searchParams.set(k, v);
+      }
+    }
+
+    const res = this.authMode === "x402"
+      ? await this.fetchFn(url.toString(), { method: "GET" })
+      : await this.fetchFn(url.toString(), { method: "GET", headers: this.authHeaders });
+
+    if (res.status === 402) {
+      const body = await res.json();
+      return { error: `Payment required: ${JSON.stringify(body.accepts?.[0] || body)}`, status: 402 };
+    }
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "Unknown error");
+      return { error: text, status: res.status };
+    }
+
+    const data = await res.json() as T;
+    return { data, status: res.status };
+  }
+
+  getKolFeed(params?: { limit?: string; action?: string; kol?: string }) {
+    return this.query("/api/x402/kol/feed", params);
+  }
+
+  getKolCoordination(params?: { period?: string; min_kols?: string; limit?: string }) {
+    return this.query("/api/x402/kol/coordination", params);
+  }
+
+  getKolLeaderboard(params?: { period?: string; limit?: string }) {
+    return this.query("/api/x402/kol/leaderboard", params);
+  }
+
+  getDeployerAlerts(params?: { since?: string; limit?: string; offset?: string }) {
+    return this.query("/api/x402/deployer-hunter/alerts", params);
+  }
+
+  // ── Webhook management (requires API key or RapidAPI key with Pro/Ultra) ──
+
+  private async restRequest<T = unknown>(method: string, path: string, body?: unknown): Promise<{ data?: T; error?: string; status: number }> {
+    if (this.authMode !== "madeonsol" && this.authMode !== "rapidapi") {
+      return { error: "API key or RapidAPI key required for webhook/streaming features. Get a free key at madeonsol.com/developer", status: 401 };
+    }
+    const res = await this.fetchFn(`${this.baseUrl}/api/v1${path}`, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        ...this.authHeaders,
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "Unknown error");
+      return { error: text, status: res.status };
+    }
+    return { data: await res.json() as T, status: res.status };
+  }
+
+  createWebhook(params: { url: string; events: string[]; filters?: Record<string, unknown> }) {
+    return this.restRequest("POST", "/webhooks", params);
+  }
+
+  listWebhooks() {
+    return this.restRequest("GET", "/webhooks");
+  }
+
+  deleteWebhook(id: number) {
+    return this.restRequest("DELETE", `/webhooks/${id}`);
+  }
+
+  testWebhook(webhookId: number) {
+    return this.restRequest("POST", "/webhooks/test", { webhook_id: webhookId });
+  }
+
+  getStreamToken() {
+    return this.restRequest("POST", "/stream/token");
+  }
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+import type { Plugin, IAgentRuntime } from "@elizaos/core";
+import { kolFeedAction } from "./actions/kol-feed.js";
+import { kolCoordinationAction } from "./actions/kol-coordination.js";
+import { kolLeaderboardAction } from "./actions/kol-leaderboard.js";
+import { deployerAlertsAction } from "./actions/deployer-alerts.js";
+import { MadeOnSolClient } from "./client.js";
+
+/** Key used to store the initialized client on the runtime */
+export const MADEONSOL_CLIENT_KEY = "madeonsol:client";
+
+export const madeOnSolPlugin: Plugin = {
+  name: "madeonsol",
+  description:
+    "Query Solana KOL trading intelligence and deployer analytics from MadeOnSol. Tracks 946 KOL wallets and 4000+ Pump.fun deployers.",
+  actions: [
+    kolFeedAction,
+    kolCoordinationAction,
+    kolLeaderboardAction,
+    deployerAlertsAction,
+  ],
+
+  /**
+   * Initialize the MadeOnSol client.
+   * Auth priority: MADEONSOL_API_KEY > RAPIDAPI_KEY > SVM_PRIVATE_KEY (x402).
+   * Get a free API key at madeonsol.com/developer — no wallet needed.
+   */
+  init: async (_config: Record<string, string>, runtime: IAgentRuntime) => {
+    const baseUrl = String(runtime.getSetting?.("MADEONSOL_API_URL") || "https://madeonsol.com");
+    const apiKey = runtime.getSetting?.("MADEONSOL_API_KEY") as string | undefined;
+    const rapidApiKey = runtime.getSetting?.("RAPIDAPI_KEY") as string | undefined;
+    const privateKey = runtime.getSetting?.("SVM_PRIVATE_KEY") as string | undefined;
+
+    let fetchFn: typeof fetch | undefined;
+
+    if (apiKey) {
+      console.log("[madeonsol] Using MadeOnSol API key (Bearer auth)");
+    } else if (rapidApiKey) {
+      console.log("[madeonsol] Using RapidAPI key");
+    } else if (privateKey) {
+      try {
+        const { wrapFetchWithPayment } = await import("@x402/fetch");
+        const { x402Client } = await import("@x402/core/client");
+        const { ExactSvmScheme } = await import("@x402/svm/exact/client");
+        const { createKeyPairSignerFromBytes } = await import("@solana/kit");
+        const { base58 } = await import("@scure/base");
+
+        const signer = await createKeyPairSignerFromBytes(base58.decode(privateKey));
+        const client = new x402Client();
+        client.register("solana:*", new ExactSvmScheme(signer));
+        fetchFn = wrapFetchWithPayment(fetch, client);
+
+        console.log(`[madeonsol] x402 payments enabled, wallet: ${signer.address}`);
+      } catch (err) {
+        console.warn("[madeonsol] x402 payment setup failed:", err);
+      }
+    } else {
+      console.log("[madeonsol] No auth configured. Set MADEONSOL_API_KEY (free at madeonsol.com/developer), RAPIDAPI_KEY, or SVM_PRIVATE_KEY.");
+    }
+
+    const madeOnSolClient = new MadeOnSolClient({ baseUrl, apiKey, rapidApiKey, fetchFn });
+    (runtime as unknown as Record<string, unknown>)[MADEONSOL_CLIENT_KEY] = madeOnSolClient;
+  },
+};
+
+export default madeOnSolPlugin;
+export { MadeOnSolClient } from "./client.js";
+export { kolFeedAction, kolCoordinationAction, kolLeaderboardAction, deployerAlertsAction };

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/LICENSE

@@ -1 +0,0 @@
-MIT License