solana-agent-kit-plugin-madeonsol 0.2.1 → 0.3.1

package/README.md

@@ -1,13 +1,25 @@
 # solana-agent-kit-plugin-madeonsol
 
-[Solana Agent Kit](https://github.com/sendaifun/solana-agent-kit) plugin for [MadeOnSol](https://madeonsol.com) — Solana KOL intelligence and deployer analytics via x402 micropayments.
+[Solana Agent Kit](https://github.com/sendaifun/solana-agent-kit) plugin for [MadeOnSol](https://madeonsol.com) — Solana KOL intelligence and deployer analytics.
+
+## Authentication
+
+Three options (in priority order):
+
+| Method | Config key | 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 |
 
 ## Install
 
 ```bash
-npm install solana-agent-kit-plugin-madeonsol @x402/fetch @x402/svm @x402/core @solana/kit @scure/base
+npm install solana-agent-kit-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
@@ -15,7 +27,14 @@ import { SolanaAgentKit } from "solana-agent-kit";
 import MadeOnSolPlugin from "solana-agent-kit-plugin-madeonsol";
 
 const agent = new SolanaAgentKit(privateKey, rpcUrl, {
-  SVM_PRIVATE_KEY: "your_solana_private_key_base58",
+  // Option 1: API key (simplest)
+  MADEONSOL_API_KEY: "msk_your_api_key_here",
+
+  // Option 2: RapidAPI key
+  // RAPIDAPI_KEY: "your_rapidapi_key",
+
+  // Option 3: x402 micropayments
+  // SVM_PRIVATE_KEY: "your_solana_private_key_base58",
 });
 
 agent.use(MadeOnSolPlugin);
@@ -29,18 +48,12 @@ const trades = await agent.methods.kolFeed(agent, { limit: 10, action: "buy" });
 
 ## Actions
 
-| Action | Price | Triggers on |
-|---|---|---|
-| `MADEONSOL_KOL_FEED_ACTION` | $0.005 | "kol trades", "what are kols buying" |
-| `MADEONSOL_KOL_COORDINATION_ACTION` | $0.02 | "kol convergence", "tokens kols accumulating" |
-| `MADEONSOL_KOL_LEADERBOARD_ACTION` | $0.005 | "top kols", "kol rankings", "best kol" |
-| `MADEONSOL_DEPLOYER_ALERTS_ACTION` | $0.01 | "deployer alerts", "pump fun launches" |
-
-## Config
-
-Set `SVM_PRIVATE_KEY` in your agent config for automatic x402 USDC payments. The wallet needs SOL (fees) and USDC on Solana mainnet.
-
-With `RAPIDAPI_KEY`, webhook and streaming methods are also available. Ultra subscribers get the **DEX Trade Stream** — a real-time WebSocket feed of all Solana DEX trades via `wss://madeonsol.com/ws/v1/dex-stream`.
+| Action | Triggers on |
+|---|---|
+| `MADEONSOL_KOL_FEED_ACTION` | "kol trades", "what are kols buying" |
+| `MADEONSOL_KOL_COORDINATION_ACTION` | "kol convergence", "tokens kols accumulating" |
+| `MADEONSOL_KOL_LEADERBOARD_ACTION` | "top kols", "kol rankings", "best kol" |
+| `MADEONSOL_DEPLOYER_ALERTS_ACTION` | "deployer alerts", "pump fun launches" |
 
 ## Also Available
 

package/dist/tools/index.d.ts

@@ -1,8 +1,11 @@
 /**
- * Tool functions — pure logic that calls MadeOnSol x402 API.
+ * Tool functions — pure logic that calls MadeOnSol API.
+ * Auth priority: MADEONSOL_API_KEY > RAPIDAPI_KEY > SVM_PRIVATE_KEY (x402).
  * These are called by Action handlers and can also be used directly via agent.methods.
  */
 type Agent = any;
+export declare function initAuth(agent: Agent): Promise<void>;
+/** @deprecated Use initAuth instead */
 export declare function initPaidFetch(agent: Agent): Promise<typeof fetch>;
 export declare function kolFeed(agent: Agent, params?: {
     limit?: number;
@@ -23,6 +26,23 @@ export declare function deployerAlerts(agent: Agent, params?: {
     since?: string;
     offset?: number;
 }): Promise<any>;
+export declare function kolPairs(agent: Agent, params?: {
+    period?: string;
+    min_shared?: number;
+    limit?: number;
+}): Promise<any>;
+export declare function kolHotTokens(agent: Agent, params?: {
+    period?: string;
+    min_kols?: number;
+    limit?: number;
+}): Promise<any>;
+export declare function kolTiming(agent: Agent, params: {
+    wallet: string;
+    period?: string;
+}): Promise<any>;
+export declare function deployerTrajectory(agent: Agent, params: {
+    wallet: string;
+}): Promise<any>;
 export declare function createWebhook(agent: Agent, params: {
     url: string;
     events: string[];

package/dist/tools/index.js

@@ -1,71 +1,120 @@
 /**
- * Tool functions — pure logic that calls MadeOnSol x402 API.
+ * Tool functions — pure logic that calls MadeOnSol API.
+ * Auth priority: MADEONSOL_API_KEY > RAPIDAPI_KEY > SVM_PRIVATE_KEY (x402).
  * These are called by Action handlers and can also be used directly via agent.methods.
  */
 const BASE_URL = "https://madeonsol.com";
-async function query(paidFetch, path, params) {
-    const url = new URL(path, BASE_URL);
+const RAPIDAPI_HOST = "madeonsol-solana-kol-tracker-tools-api.p.rapidapi.com";
+let _authMode = null;
+let _authHeaders = {};
+let _paidFetch = null;
+function getConfig(agent, key) {
+    return agent.config?.[key] || agent.config?.OTHER_API_KEYS?.[key];
+}
+export async function initAuth(agent) {
+    if (_authMode)
+        return;
+    const apiKey = getConfig(agent, "MADEONSOL_API_KEY");
+    const rapidApiKey = getConfig(agent, "RAPIDAPI_KEY");
+    const privateKey = getConfig(agent, "SVM_PRIVATE_KEY");
+    if (apiKey) {
+        _authMode = "madeonsol";
+        _authHeaders = { Authorization: `Bearer ${apiKey}` };
+        _paidFetch = fetch;
+        console.log("[madeonsol] Using MadeOnSol API key (Bearer auth)");
+    }
+    else if (rapidApiKey) {
+        _authMode = "rapidapi";
+        _authHeaders = { "x-rapidapi-key": rapidApiKey, "x-rapidapi-host": RAPIDAPI_HOST };
+        _paidFetch = fetch;
+        console.log("[madeonsol] Using RapidAPI key");
+    }
+    else if (privateKey) {
+        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));
+        _paidFetch = wrapFetchWithPayment(fetch, client);
+        _authMode = "x402";
+        console.log(`[madeonsol] x402 payments enabled, wallet: ${signer.address}`);
+    }
+    else {
+        _authMode = "none";
+        _paidFetch = fetch;
+        console.warn("[madeonsol] No auth configured. Set MADEONSOL_API_KEY (free at madeonsol.com/developer), RAPIDAPI_KEY, or SVM_PRIVATE_KEY.");
+    }
+}
+/** @deprecated Use initAuth instead */
+export async function initPaidFetch(agent) {
+    await initAuth(agent);
+    return _paidFetch;
+}
+async function query(path, params) {
+    const apiPath = _authMode === "x402" || _authMode === "none"
+        ? path
+        : path.replace("/api/x402/", "/api/v1/");
+    const url = new URL(apiPath, BASE_URL);
     if (params) {
         for (const [k, v] of Object.entries(params)) {
             if (v !== undefined)
                 url.searchParams.set(k, String(v));
         }
     }
-    const res = await paidFetch(url.toString());
+    const res = _authMode === "x402"
+        ? await _paidFetch(url.toString())
+        : await fetch(url.toString(), { headers: _authHeaders });
     if (!res.ok) {
         const body = await res.text().catch(() => "");
         throw new Error(`MadeOnSol API error ${res.status}: ${body}`);
     }
     return res.json();
 }
-let _paidFetch = null;
-export async function initPaidFetch(agent) {
-    if (_paidFetch)
-        return _paidFetch;
-    const privateKey = agent.config?.SVM_PRIVATE_KEY || agent.config?.OTHER_API_KEYS?.SVM_PRIVATE_KEY;
-    if (!privateKey) {
-        console.warn("[madeonsol] No SVM_PRIVATE_KEY in agent config — x402 payments disabled");
-        _paidFetch = fetch;
-        return _paidFetch;
-    }
-    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));
-    _paidFetch = wrapFetchWithPayment(fetch, client);
-    return _paidFetch;
-}
 export async function kolFeed(agent, params = {}) {
-    const f = await initPaidFetch(agent);
-    return query(f, "/api/x402/kol/feed", params);
+    await initAuth(agent);
+    return query("/api/x402/kol/feed", params);
 }
 export async function kolCoordination(agent, params = {}) {
-    const f = await initPaidFetch(agent);
-    return query(f, "/api/x402/kol/coordination", params);
+    await initAuth(agent);
+    return query("/api/x402/kol/coordination", params);
 }
 export async function kolLeaderboard(agent, params = {}) {
-    const f = await initPaidFetch(agent);
-    return query(f, "/api/x402/kol/leaderboard", params);
+    await initAuth(agent);
+    return query("/api/x402/kol/leaderboard", params);
 }
 export async function deployerAlerts(agent, params = {}) {
-    const f = await initPaidFetch(agent);
-    return query(f, "/api/x402/deployer-hunter/alerts", params);
+    await initAuth(agent);
+    return query("/api/x402/deployer-hunter/alerts", params);
+}
+export async function kolPairs(agent, params = {}) {
+    await initAuth(agent);
+    return query("/api/x402/kol/pairs", params);
+}
+export async function kolHotTokens(agent, params = {}) {
+    await initAuth(agent);
+    return query("/api/x402/kol/tokens/hot", params);
 }
-// ── Webhook & Streaming (RapidAPI key required) ──
+export async function kolTiming(agent, params) {
+    const qs = params.period ? `?period=${params.period}` : "";
+    return restQuery(agent, "GET", `/kol/${params.wallet}/timing${qs}`);
+}
+export async function deployerTrajectory(agent, params) {
+    return restQuery(agent, "GET", `/deployer-hunter/${params.wallet}/trajectory`);
+}
+// ── Webhook & Streaming (requires API key or RapidAPI key) ──
 async function restQuery(agent, method, path, body) {
-    const apiKey = agent.config?.RAPIDAPI_KEY || agent.config?.OTHER_API_KEYS?.RAPIDAPI_KEY;
-    if (!apiKey)
-        throw new Error("RAPIDAPI_KEY required for webhook/streaming features");
+    await initAuth(agent);
+    if (_authMode !== "madeonsol" && _authMode !== "rapidapi") {
+        throw new Error("API key or RapidAPI key required for webhook/streaming features. Get a free key at madeonsol.com/developer");
+    }
     const res = await fetch(`${BASE_URL}/api/v1${path}`, {
         method,
         headers: {
             "Content-Type": "application/json",
-            "x-rapidapi-key": apiKey,
-            "x-rapidapi-host": "madeonsol-solana-kol-tracker-tools-api.p.rapidapi.com",
+            ..._authHeaders,
         },
         ...(body ? { body: JSON.stringify(body) } : {}),
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-agent-kit-plugin-madeonsol",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Solana Agent Kit plugin for MadeOnSol — KOL intelligence and deployer analytics via x402 micropayments",
   "type": "module",
   "main": "dist/index.js",