@aicoin/aicoin-mcp 1.0.3 → 1.0.5

package/README.md

@@ -6,7 +6,7 @@ AiCoin MCP Server — real-time crypto market data & exchange trading for any AI
 
 ## Quick Start
 
-Works out of the box — a free API key is built in (10 req/min, IP rate-limited).
+Works out of the box — a free API key is built in (15 req/min, IP rate-limited).
 
 ### Claude Code
 
@@ -137,12 +137,13 @@ Exchange API keys are stored locally only and never sent to AiCoin servers.
 
 ## API Tiers
 
-| Tier | Price | Rate Limit | Features |
-|------|-------|------------|----------|
-| Basic | Free | 10 req/min | Market data, news, K-lines, indexes |
-| Normal | ¥99/mo | 60 req/min | + Funding rate, liquidation, OI |
-| Premium | ¥299/mo | 120 req/min | + Depth, whale tracking, order flow |
-| Professional | ¥999/mo | 300 req/min | + Full depth, all features |
+| Tier | Price | Rate Limit | Monthly Quota | Features |
+|------|-------|------------|---------------|----------|
+| Free | $0 | 15 req/min | 20K | Market, coin & special data |
+| Basic | $29/mo | 30 req/min | 20K | + Content data |
+| Standard | $79/mo | 80 req/min | 500K | + Content data |
+| Advanced | $299/mo | 300 req/min | 1.5M | + Content data, commercial use |
+| Professional | $699/mo | 1200 req/min | 3.5M | + Content data, commercial use |
 
 Upgrade at [aicoin.com/opendata](https://www.aicoin.com/opendata). Your existing key is automatically upgraded.
 

package/build/index.js

@@ -741,7 +741,7 @@ function generateSignature(accessKeyId, accessSecret) {
 // src/client/api.ts
 var DOMAIN = process.env.AICOIN_BASE_URL || "https://open.aicoin.com";
 var TIMEOUT_MS = 3e4;
-var UPGRADE_GUIDE = "\n\n--- How to fix ---\nYour current API tier does not have access to this endpoint. Please upgrade your plan.\n1. Visit https://www.aicoin.com/opendata to purchase or upgrade\n2. Tiers: Basic(free) | Normal(\xA599) | Premium(\xA5299) | Professional(\xA5999)\n3. Set AICOIN_ACCESS_KEY_ID and AICOIN_ACCESS_SECRET in your MCP config\n4. Restart your MCP client";
+var UPGRADE_GUIDE = "\n\n--- How to fix ---\nYour current API tier does not have access to this endpoint. Please upgrade your plan.\n1. Visit https://www.aicoin.com/opendata to purchase or upgrade\n2. Tiers: Free($0) | Basic($29/mo) | Standard($79/mo) | Advanced($299/mo) | Professional($699/mo)\n3. Set AICOIN_ACCESS_KEY_ID and AICOIN_ACCESS_SECRET in your MCP config\n4. Restart your MCP client";
 var AUTH_GUIDE = "\n\n--- How to fix ---\nAn API key is required to access this endpoint.\n1. Visit https://www.aicoin.com/opendata to register and create an API key\n2. Set AICOIN_ACCESS_KEY_ID and AICOIN_ACCESS_SECRET in your MCP config\n3. Restart your MCP client";
 function throwApiError(status, body, path) {
   let msg = `API ${status}: ${body}`;
@@ -1109,6 +1109,72 @@ function registerContentTools(server2) {
       }
     }
   );
+  server2.tool(
+    "twitter",
+    "Twitter/X crypto tweets.\n\u2022 latest \u2014 latest crypto tweets, cursor-paginated\n\u2022 search \u2014 search tweets by keyword. Requires: keyword\n\u2022 members \u2014 search Twitter KOL/users. Requires: word\n\u2022 interaction_stats \u2014 tweet engagement stats. Requires: flash_ids (POST)",
+    {
+      action: z4.enum(["latest", "search", "members", "interaction_stats"]).describe(
+        "latest: latest crypto tweets; search: search by keyword; members: search KOL/users; interaction_stats: tweet engagement"
+      ),
+      keyword: z4.string().optional().describe("REQUIRED for search. Search keyword"),
+      word: z4.string().optional().describe("REQUIRED for members. User search keyword"),
+      flash_ids: z4.string().optional().describe(
+        'REQUIRED for interaction_stats. Comma-separated tweet flash IDs, e.g. "123,456,789" (max 50)'
+      ),
+      language: z4.string().optional().describe("For latest/search: language filter (cn, en)"),
+      last_time: z4.string().optional().describe("For latest/search: cursor for pagination (last item timestamp)"),
+      page_size: z4.string().optional().describe("For latest/search: page size, default 20"),
+      page: z4.string().optional().describe("For members: page number, default 1"),
+      size: z4.string().optional().describe("For members: page size, default 20"),
+      ...maxItemsParam
+    },
+    async ({ action, keyword, word, flash_ids, language, last_time, page_size, page, size, _max_items }) => {
+      try {
+        switch (action) {
+          case "latest": {
+            const params = {};
+            if (language) params.language = language;
+            if (last_time) params.last_time = last_time;
+            if (page_size) params.page_size = page_size;
+            return okList(
+              await apiGet("/api/upgrade/v2/content/twitter/latest", params),
+              parseMax(_max_items, 20)
+            );
+          }
+          case "search": {
+            if (!keyword) return err("keyword is required for search action");
+            const params = { keyword };
+            if (language) params.language = language;
+            if (last_time) params.last_time = last_time;
+            if (page_size) params.page_size = page_size;
+            return okList(
+              await apiGet("/api/upgrade/v2/content/twitter/search", params),
+              parseMax(_max_items, 20)
+            );
+          }
+          case "members": {
+            if (!word) return err("word is required for members action");
+            const params = { word };
+            if (page) params.page = page;
+            if (size) params.size = size;
+            return okList(
+              await apiGet("/api/upgrade/v2/content/twitter/members", params),
+              parseMax(_max_items, 20)
+            );
+          }
+          case "interaction_stats": {
+            if (!flash_ids) return err("flash_ids is required for interaction_stats action");
+            const ids = flash_ids.split(",").map((s) => Number(s.trim())).filter((n) => !isNaN(n));
+            if (ids.length === 0) return err("flash_ids must contain valid numeric IDs");
+            if (ids.length > 50) return err("flash_ids max 50 items");
+            return ok(await apiPost("/api/upgrade/v2/content/twitter/interaction-stats", { flash_ids: ids }));
+          }
+        }
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
 }
 
 // src/tools/markets.ts
@@ -1632,15 +1698,17 @@ function registerHyperliquidTools(server2) {
   );
   server2.tool(
     "hl_liquidation",
-    "Hyperliquid liquidation data. All actions support optional coin filter.\n\u2022 history \u2014 liquidation history\n\u2022 stats \u2014 aggregate stats\n\u2022 stats_by_coin \u2014 per-coin stats\n\u2022 top_positions \u2014 top liquidated positions",
+    "Hyperliquid liquidation data. All actions support optional coin filter.\n\u2022 history \u2014 liquidation history\n\u2022 stats \u2014 aggregate stats\n\u2022 stats_by_coin \u2014 per-coin stats\n\u2022 top_positions \u2014 top liquidated positions. Requires: coin + interval",
     {
       action: z7.enum(["history", "stats", "stats_by_coin", "top_positions"]).describe(
         "history: liquidation history; stats: aggregate stats; stats_by_coin: per-coin stats; top_positions: top liquidated"
       ),
-      coin: z7.string().optional().describe("Optional. Coin filter in uppercase, e.g. BTC"),
+      coin: z7.string().optional().describe("Optional. Coin filter in uppercase, e.g. BTC. REQUIRED for top_positions"),
+      interval: z7.string().optional().describe("REQUIRED for top_positions. Interval: 4h, 1d"),
+      limit: z7.string().optional().describe("Optional for top_positions. Max results"),
       ...maxItemsParam
     },
-    async ({ action, coin, _max_items }) => {
+    async ({ action, coin, interval, limit, _max_items }) => {
       try {
         const params = {};
         if (coin) params.coin = coin;
@@ -1654,11 +1722,16 @@ function registerHyperliquidTools(server2) {
             return ok(await apiGet("/api/upgrade/v2/hl/liquidations/stat"));
           case "stats_by_coin":
             return ok(await apiGet("/api/upgrade/v2/hl/liquidations/stat-by-coin", params));
-          case "top_positions":
+          case "top_positions": {
+            if (!coin) return err("coin is required for top_positions action");
+            if (!interval) return err('interval is required for top_positions action (e.g. "4h", "1d")');
+            const tpParams = { coin, interval };
+            if (limit) tpParams.limit = limit;
             return okList(
-              await apiGet("/api/upgrade/v2/hl/liquidations/top-positions", params),
+              await apiGet("/api/upgrade/v2/hl/liquidations/top-positions", tpParams),
               parseMax(_max_items, 50)
             );
+          }
         }
       } catch (e) {
         return err(e);
@@ -1799,7 +1872,7 @@ function registerHyperliquidTools(server2) {
   );
   server2.tool(
     "hl_fills",
-    "Hyperliquid trade fills.\n\u2022 by_address \u2014 fills by wallet. Requires: address\n\u2022 by_oid \u2014 fills by order ID. Requires: oid\n\u2022 by_twapid \u2014 fills by TWAP ID. Requires: twapid\n\u2022 top_trades \u2014 top trades, no required params",
+    "Hyperliquid trade fills.\n\u2022 by_address \u2014 fills by wallet. Requires: address\n\u2022 by_oid \u2014 fills by order ID. Requires: oid\n\u2022 by_twapid \u2014 fills by TWAP ID. Requires: twapid\n\u2022 top_trades \u2014 top trades. Requires: interval + coin",
     {
       action: z7.enum(["by_address", "by_oid", "by_twapid", "top_trades"]).describe(
         "by_address: fills by wallet; by_oid: fills by order ID; by_twapid: fills by TWAP ID; top_trades: top trades"
@@ -1807,8 +1880,8 @@ function registerHyperliquidTools(server2) {
       address: z7.string().optional().describe("REQUIRED for by_address. Wallet address (0x...)"),
       oid: z7.string().optional().describe("REQUIRED for by_oid. Order ID"),
       twapid: z7.string().optional().describe("REQUIRED for by_twapid. TWAP ID"),
-      coin: z7.string().optional().describe("Optional. Coin filter in uppercase, e.g. BTC"),
-      interval: z7.string().optional().describe("Optional for top_trades. Interval: 4h, 1d"),
+      coin: z7.string().optional().describe("Optional. Coin filter in uppercase, e.g. BTC. REQUIRED for top_trades"),
+      interval: z7.string().optional().describe("REQUIRED for top_trades. Interval: 4h, 1d"),
       limit: z7.string().optional().describe("Max results"),
       ...maxItemsParam
     },
@@ -1834,9 +1907,9 @@ function registerHyperliquidTools(server2) {
             return ok(await apiGet(`/api/upgrade/v2/hl/fills/twapid/${twapid}`));
           }
           case "top_trades": {
-            const params = {};
-            if (coin) params.coin = coin;
-            if (interval) params.interval = interval;
+            if (!coin) return err("coin is required for top_trades action");
+            if (!interval) return err('interval is required for top_trades action (e.g. "4h", "1d")');
+            const params = { coin, interval };
             if (limit) params.limit = limit;
             return okList(
               await apiGet("/api/upgrade/v2/hl/fills/top-trades", params),
@@ -1984,9 +2057,10 @@ function registerHyperliquidTools(server2) {
       window: z7.string().optional().describe('REQUIRED for portfolio ONLY. Time window: "day", "week", "month", "allTime". NOT used by max_drawdown/net_flow'),
       period: z7.string().optional().describe("Optional for pnls. Period in days: 0=allTime, 1, 7, 30"),
       days: z7.string().optional().describe("REQUIRED for max_drawdown, net_flow. Number of days: 7, 30, 90. NOT used by portfolio"),
+      scope: z7.string().optional().describe('Optional for max_drawdown. Scope: "perp" (default), "all"'),
       ...maxItemsParam
     },
-    async ({ action, address, window: win, period, days, _max_items }) => {
+    async ({ action, address, window: win, period, days, scope, _max_items }) => {
       try {
         switch (action) {
           case "portfolio": {
@@ -2006,7 +2080,8 @@ function registerHyperliquidTools(server2) {
           }
           case "max_drawdown": {
             if (!days) return err("days is required for max_drawdown action");
-            return ok(await apiGet(`/api/upgrade/v2/hl/max-drawdown/${address}`, { days }));
+            const params = { days, scope: scope || "perp" };
+            return ok(await apiGet(`/api/upgrade/v2/hl/max-drawdown/${address}`, params));
           }
           case "net_flow": {
             if (!days) return err("days is required for net_flow action");
@@ -2099,12 +2174,13 @@ Visit https://www.aicoin.com/opendata to manage your API keys.
 ## Step 3: Create API Key
 Click "Create Key" and select your desired tier:
 
-| Tier | Price | Rate Limit | Features |
-|------|-------|------------|----------|
-| Basic | Free | 10 req/min | Market data, news, basic indicators |
-| Normal | \xA599/mo | 60 req/min | + Funding rate, liquidation data |
-| Premium | \xA5299/mo | 120 req/min | + Depth data, whale tracking |
-| Professional | \xA5999/mo | 300 req/min | + Full depth, all features |
+| Tier | Price | Rate Limit | Monthly Quota | Features |
+|------|-------|------------|---------------|----------|
+| Free | $0 | 15 req/min | 20K | Market, coin & special data |
+| Basic | $29/mo | 30 req/min | 20K | + Content data |
+| Standard | $79/mo | 80 req/min | 500K | + Content data |
+| Advanced | $299/mo | 300 req/min | 1.5M | + Content data, commercial use |
+| Professional | $699/mo | 1200 req/min | 3.5M | + Content data, commercial use |
 
 ## Step 4: Configure MCP Server
 After creating the key, you will get two values:
@@ -2139,18 +2215,15 @@ ${endpoint ? `Endpoint: ${endpoint}` : ""}
 
 ## API Tier Comparison
 
-| Feature | Basic (Free) | Normal (\xA599) | Premium (\xA5299) | Professional (\xA5999) |
-|---------|:---:|:---:|:---:|:---:|
-| Market tickers & K-lines | \u2705 | \u2705 | \u2705 | \u2705 |
-| News & flash | \u2705 | \u2705 | \u2705 | \u2705 |
-| Index data | \u2705 | \u2705 | \u2705 | \u2705 |
-| Funding rate history | \u274C | \u2705 | \u2705 | \u2705 |
-| Liquidation data | \u274C | \u2705 | \u2705 | \u2705 |
-| OI history | \u274C | \u2705 | \u2705 | \u2705 |
-| Whale order tracking | \u274C | \u274C | \u2705 | \u2705 |
-| Depth data | \u274C | \u274C | \u2705 | \u2705 |
-| Strategy signals | \u274C | \u274C | \u274C | \u2705 |
-| Full depth & grouped | \u274C | \u274C | \u274C | \u2705 |
+| Feature | Free ($0) | Basic ($29) | Standard ($79) | Advanced ($299) | Professional ($699) |
+|---------|:---:|:---:|:---:|:---:|:---:|
+| Market data | \u2705 | \u2705 | \u2705 | \u2705 | \u2705 |
+| Coin data | \u2705 | \u2705 | \u2705 | \u2705 | \u2705 |
+| Special data | \u2705 | \u2705 | \u2705 | \u2705 | \u2705 |
+| Content data | \u274C | \u2705 | \u2705 | \u2705 | \u2705 |
+| Rate limit | 15/min | 30/min | 80/min | 300/min | 1200/min |
+| Monthly quota | 20K | 20K | 500K | 1.5M | 3.5M |
+| Commercial use | \u274C | \u274C | \u274C | \u2705 | \u2705 |
 
 ## How to Upgrade
 1. Visit https://www.aicoin.com/opendata
@@ -2289,6 +2362,21 @@ var FreqtradeClient = class {
           );
         }
         if (res.status === 503) {
+          const endpoint = url.pathname.replace("/api/v1/", "");
+          const devEndpoints = [
+            "strategies",
+            "strategy/",
+            "available_pairs",
+            "backtest",
+            "pair_history",
+            "freqaimodels"
+          ];
+          const isDev = devEndpoints.some((e) => endpoint.startsWith(e));
+          if (isDev) {
+            throw new Error(
+              `This endpoint requires webserver mode (503). Freqtrade separates "trade" and "webserver" modes: strategy/backtest/candle-analysis endpoints are only available in webserver mode. To use this feature, restart Freqtrade with: freqtrade webserver --config user_data/config.json. Note: webserver mode and trade mode cannot run simultaneously.`
+            );
+          }
           throw new Error(
             `Bot is not in the correct state (503). This usually means the bot was started in webserver-only mode without a strategy. Use ft_info action=config to check the current state. If "state" is empty and "strategy" is null, restart Freqtrade with a strategy: freqtrade trade --strategy <name> --config user_data/config.json`
           );
@@ -3009,7 +3097,7 @@ ${roiStr}
 }
 
 // src/tools/freqtrade-dev.ts
-import { readFile, writeFile, access, mkdir } from "fs/promises";
+import { readFile, writeFile, readdir, access, mkdir } from "fs/promises";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 var __pkgroot = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -3033,7 +3121,7 @@ async function fileExists(path) {
 function registerFreqtradeDevTools(server2) {
   server2.tool(
     "ft_backtest",
-    "Freqtrade backtesting.\n- start: start a backtest (requires strategy, optional params)\n- status: get current backtest progress/results\n- abort: abort running backtest\n- delete: clear backtest state\n- history: list all backtest history entries\n- history_result: get specific result (requires filename & strategy)",
+    "Freqtrade backtesting.\n- start: start a backtest (requires strategy, optional params)\n- status: get current backtest progress/results\n- abort: abort running backtest\n- delete: clear backtest state\n- history: list all backtest history entries\n- history_result: get specific result (requires filename & strategy)\nNOTE: Requires Freqtrade in webserver mode (freqtrade webserver). Not available in trade mode.",
     {
       action: z10.enum(["start", "status", "abort", "delete", "history", "history_result"]).describe("Backtest action"),
       strategy: z10.string().optional().describe("Strategy class name (required for start & history_result)"),
@@ -3093,7 +3181,7 @@ function registerFreqtradeDevTools(server2) {
   );
   server2.tool(
     "ft_candles",
-    "Freqtrade K-line / candle data.\n- live: live candlestick data (pair + timeframe required)\n- analyzed: historical data with strategy indicators (pair + timeframe + strategy required)\n- available: list available pairs with downloaded data",
+    'Freqtrade K-line / candle data.\n- live: live candlestick data (pair + timeframe required)\n- analyzed: historical data with strategy indicators (pair + timeframe + strategy required)\n- available: list available pairs with downloaded data\nNOTE: "analyzed" and "available" require Freqtrade in webserver mode. "live" works in trade mode.',
     {
       action: z10.enum(["live", "analyzed", "available"]).describe("Candle data query type"),
       pair: z10.string().optional().describe("Trading pair, e.g. BTC/USDT (for live & analyzed)"),
@@ -3164,13 +3252,28 @@ function registerFreqtradeDevTools(server2) {
     },
     async ({ action, strategy, name, template, timeframe, stoploss, roi, overwrite }) => {
       try {
-        const client = getFreqtradeClient();
         switch (action) {
-          case "list":
-            return ok(await client.strategies());
+          case "list": {
+            const userDataPath = getUserDataPath();
+            const strategiesDir = join(userDataPath, "strategies");
+            try {
+              const files = await readdir(strategiesDir);
+              const strategies = files.filter((f) => f.endsWith(".py") && !f.startsWith("__") && f !== "aicoin_provider.py").map((f) => f.replace(/\.py$/, ""));
+              return ok({ strategies });
+            } catch {
+              return ok({ strategies: [], note: `No strategies directory found at ${strategiesDir}` });
+            }
+          }
           case "get": {
             if (!strategy) return err("strategy name is required for get action");
-            return ok(await client.strategy(strategy));
+            const userDataPath = getUserDataPath();
+            const filePath = join(userDataPath, "strategies", `${strategy}.py`);
+            try {
+              const code = await readFile(filePath, "utf-8");
+              return ok({ strategy, code });
+            } catch {
+              return err(`Strategy file not found: ${filePath}`);
+            }
           }
           case "create": {
             if (!name) return err("name is required for create action");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicoin/aicoin-mcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "AiCoin MCP Server - unified crypto market data & trading via AiCoin API + CCXT",
   "main": "build/index.js",
   "type": "module",