@aicoin/opendata-mcp 1.0.29 → 2.0.0

package/README.md

@@ -1,166 +1,62 @@
-# AiCoin OpenData MCP Server
+# @aicoin/opendata-mcp
 
-Crypto market data, news, and analytics via AiCoin Open API.
+AiCoin OpenData MCP Server — real-time crypto market data & analytics for any AI assistant.
 
-## Features
+**30 tools** · Market data · K-lines · Funding rates · Liquidations · Order flow · Hyperliquid analytics · News
 
-- 100+ data tools across 5 modules (coins, contents, markets, features, hyperliquid)
-- HmacSHA1 auto-signing for all API requests
-- Covers real-time tickers, K-lines, news, whale tracking, liquidation data
-- stdio transport for local MCP clients
+> Need exchange trading (place orders, check balances)? Use [@aicoin/aicoin-mcp](https://www.npmjs.com/package/@aicoin/aicoin-mcp) instead — it includes everything here plus 11 CCXT trading tools.
 
-## Quick Start
+## Connect
 
-```bash
-npm install
-cp .env.example .env
-# Edit .env with your AiCoin API credentials
-npm run build
-npm start
-```
+Get your free API key at [aicoin.com/opendata](https://www.aicoin.com/opendata), then add to your MCP client:
 
-## Environment Variables
+### Claude Code
 
 ```bash
-AICOIN_ACCESS_KEY_ID=your_access_key_id
-AICOIN_ACCESS_SECRET=your_access_secret
+claude mcp add aicoin-opendata -- npx -y @aicoin/opendata-mcp \
+  --env AICOIN_ACCESS_KEY_ID=your-key-id \
+  --env AICOIN_ACCESS_SECRET=your-secret
 ```
 
-## Available Tools
+Or add to `.mcp.json` in your project root:
 
-### Coins
+```json
+{
+  "mcpServers": {
+    "aicoin-opendata": {
+      "command": "npx",
+      "args": ["-y", "@aicoin/opendata-mcp"],
+      "env": {
+        "AICOIN_ACCESS_KEY_ID": "your-key-id",
+        "AICOIN_ACCESS_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
 
-| Tool | Description |
-|------|-------------|
-| `get_coin_list` | All supported coins |
-| `get_coin_ticker` | Real-time price, change, volume |
-| `get_coin_config` | Coin profile/description |
-| `get_ai_coin_analysis` | AI interpretation and prediction |
-| `get_funding_rate_history` | Funding rate history |
-| `get_liquidation_map` | Liquidation heatmap |
-| `get_weighted_funding_rate_history` | Volume-weighted funding rate history |
-| `get_aggregated_stablecoin_oi_history` | Aggregated stablecoin OI history |
-| `get_aggregated_coin_margin_oi_history` | Aggregated coin-margin OI history |
-| `get_liquidation_history` | Liquidation order history |
-| `get_estimated_liquidation_history` | Estimated liquidation chart data |
-| `get_historical_depth` | Historical order book depth |
-| `get_super_depth_history` | Large order depth history |
-| `get_trade_data` | Latest futures trade data |
-
-### Contents
-
-| Tool | Description |
-|------|-------------|
-| `get_newsflash` | Flash news (kuaixun) |
-| `get_news_list` | News article list |
-| `get_news_detail` | Full article content |
-| `get_rss_news_list` | RSS news feed |
-| `get_flash_list` | Industry flash news with classification |
-| `get_exchange_listing_flash` | Exchange listing/delisting news |
+### Cursor
 
-### Markets
+Settings → MCP → Add new MCP server:
 
-| Tool | Description |
-|------|-------------|
-| `get_kline_data` | K-line/candlestick data |
-| `get_market_ticker` | Exchange platform ticker |
-| `get_markets` | All exchange platforms |
-| `get_futures_interest` | Futures open interest |
-| `get_crypto_stock_quotes` | Crypto stock quotes (MSTR, COIN) |
-| `get_crypto_stock_top_gainer` | Top gaining crypto-related stocks |
-| `get_index_price` | Index price data |
-| `get_hot_tab_coins` | Trending coins by category |
-| `get_crypto_company_info` | Crypto company details by symbol |
-| `get_index_info` | Index detail information |
-| `get_index_list` | All available indexes |
-| `get_indicator_kline_trading_pair` | Trading pairs for indicator K-line |
-| `get_indicator_kline_data` | Indicator K-line data records |
-| `get_coin_treasury_entities` | Coin treasury entity data |
-| `get_coin_treasury_history` | Coin treasury historical data |
-| `get_coin_treasury_accumulated` | Accumulated treasury history |
-| `get_latest_coin_treasury_entities` | Latest treasury entities |
-| `get_latest_coin_treasury_history` | Latest treasury history |
-| `get_coin_treasury_summary` | Treasury data summary |
-| `get_latest_depth` | Latest order book depth |
-| `get_full_depth` | Full order book depth |
-| `get_full_depth_grouped` | Full depth grouped by price |
-
-### Features
-
-| Tool | Description |
-|------|-------------|
-| `get_ls_ratio` | Long/short ratio |
-| `get_liquidation_data` | Liquidation/forced-close data |
-| `get_big_orders` | Whale order tracking |
-| `get_agg_trades` | Aggregated large trades |
-| `get_trading_pair_ticker` | Trading pair ticker data |
-| `get_strategy_signal` | Indicator win-rate signals |
-| `get_nav` | Market overview navigation data |
-| `get_grayscale_trust` | Grayscale trust fund data |
-| `get_gray_scale` | Grayscale holdings data |
-| `get_stock_market` | Crypto-related stock market data |
-| `get_signal_alert` | Signal alert data |
-| `get_signal_alert_config` | Signal alert config options |
-| `delete_signal_alert` | Delete signal alert by ID |
-| `add_signal_alert` | Add new signal alert |
-| `get_signal_alert_list` | Signal alert settings list |
-| `get_change_signal` | Abnormal movement signals |
-| `get_trading_pair` | Trading pair info by key |
-| `get_trading_pairs` | Trading pair list for platform |
-
-### Hyperliquid
-
-| Tool | Description |
-|------|-------------|
-| `hl_get_tickers` | All Hyperliquid tickers |
-| `hl_get_ticker_by_coin` | Ticker for specific coin |
-| `hl_get_whale_positions` | Whale open positions |
-| `hl_get_liquidations` | Liquidation history |
-| `hl_get_trader_stats` | Trader statistics by address |
-| `hl_info` | Generic Info API (all info types) |
-| `hl_get_fills_by_address` | Trade fills by wallet address |
-| `hl_get_fills_by_oid` | Trade fills by order ID |
-| `hl_get_fills_by_twapid` | Trade fills by TWAP ID |
-| `hl_get_top_trades` | Top trades |
-| `hl_get_filled_orders` | Filled orders by address |
-| `hl_get_filled_order_by_oid` | Filled order by order ID |
-| `hl_get_orders` | Latest orders by address |
-| `hl_get_order_by_oid` | Order by order ID |
-| `hl_get_top_open_orders` | Top open orders |
-| `hl_get_active_stats` | Active order statistics |
-| `hl_get_portfolio` | Account value and PNL curves |
-| `hl_get_pnls` | PNL curve data by address |
-| `hl_get_best_trades` | Most profitable trades |
-| `hl_get_performance_by_coin` | Per-coin trading performance |
-| `hl_get_completed_trades` | Completed trades list |
-| `hl_get_current_position_history` | Current position history |
-| `hl_get_completed_position_history` | Completed position history |
-| `hl_get_current_position_pnl` | Current position PnL |
-| `hl_get_completed_position_pnl` | Completed position PnL |
-| `hl_get_current_position_executions` | Current position executions |
-| `hl_get_completed_position_executions` | Completed position executions |
-| `hl_get_traders_accounts` | Batch trader account info |
-| `hl_get_traders_statistics` | Batch trader statistics |
-| `hl_get_whale_events` | Latest whale position events |
-| `hl_get_whale_directions` | Whale long/short counts |
-| `hl_get_whale_history_long_ratio` | Historical whale long/short ratio |
-| `hl_get_liquidation_stats` | Liquidation statistics |
-| `hl_get_liquidation_stats_by_coin` | Liquidation stats by coin |
-| `hl_get_liquidation_top_positions` | Top liquidated positions |
-| `hl_smart_find` | Discover smart money addresses |
-| `hl_discover_traders` | Discover traders by criteria |
-| `hl_get_twap_states` | TWAP order states |
-| `hl_get_max_drawdown` | Max drawdown by address |
-| `hl_get_net_flow` | Ledger net flow by address |
-| `hl_get_klines_with_taker_vol` | K-lines with taker volume |
-
-## Client Configuration
-
-> Get your API credentials at [AiCoin OpenAPI](https://www.aicoin.com/opendata)
+```json
+{
+  "mcpServers": {
+    "aicoin-opendata": {
+      "command": "npx",
+      "args": ["-y", "@aicoin/opendata-mcp"],
+      "env": {
+        "AICOIN_ACCESS_KEY_ID": "your-key-id",
+        "AICOIN_ACCESS_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
 
-### Claude Desktop
+### Windsurf
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Add to `~/.codeium/windsurf/mcp_config.json`:
 
 ```json
 {
@@ -169,17 +65,39 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
       "command": "npx",
       "args": ["-y", "@aicoin/opendata-mcp"],
       "env": {
-        "AICOIN_ACCESS_KEY_ID": "your_access_key_id",
-        "AICOIN_ACCESS_SECRET": "your_access_secret"
+        "AICOIN_ACCESS_KEY_ID": "your-key-id",
+        "AICOIN_ACCESS_SECRET": "your-secret"
       }
     }
   }
 }
 ```
 
-### Cursor
+### VS Code (Copilot)
+
+Add to `.vscode/mcp.json` in your project:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "aicoin-opendata": {
+        "type": "stdio",
+        "command": "npx",
+        "args": ["-y", "@aicoin/opendata-mcp"],
+        "env": {
+          "AICOIN_ACCESS_KEY_ID": "your-key-id",
+          "AICOIN_ACCESS_SECRET": "your-secret"
+        }
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
 
-Add to `.cursor/mcp.json`:
+Add to `claude_desktop_config.json`:
 
 ```json
 {
@@ -188,40 +106,110 @@ Add to `.cursor/mcp.json`:
       "command": "npx",
       "args": ["-y", "@aicoin/opendata-mcp"],
       "env": {
-        "AICOIN_ACCESS_KEY_ID": "your_access_key_id",
-        "AICOIN_ACCESS_SECRET": "your_access_secret"
+        "AICOIN_ACCESS_KEY_ID": "your-key-id",
+        "AICOIN_ACCESS_SECRET": "your-secret"
       }
     }
   }
 }
 ```
 
-### Windsurf
+### OpenCode
 
-Add to `~/.codeium/windsurf/mcp_config.json` (same format as Cursor).
+Add to `.opencode/config.toml`:
 
-### VS Code (Copilot)
+```toml
+[mcp_servers.aicoin-opendata]
+command = "npx"
+args = ["-y", "@aicoin/opendata-mcp"]
+
+[mcp_servers.aicoin-opendata.env]
+AICOIN_ACCESS_KEY_ID = "your-key-id"
+AICOIN_ACCESS_SECRET = "your-secret"
+```
+
+### Codex
+
+```bash
+codex --mcp-config mcp.json
+```
 
-Add to `.vscode/mcp.json`:
+Where `mcp.json` contains:
 
 ```json
 {
-  "servers": {
+  "mcpServers": {
     "aicoin-opendata": {
-      "type": "stdio",
       "command": "npx",
       "args": ["-y", "@aicoin/opendata-mcp"],
       "env": {
-        "AICOIN_ACCESS_KEY_ID": "your_access_key_id",
-        "AICOIN_ACCESS_SECRET": "your_access_secret"
+        "AICOIN_ACCESS_KEY_ID": "your-key-id",
+        "AICOIN_ACCESS_SECRET": "your-secret"
       }
     }
   }
 }
 ```
 
-### Claude Code
+## Tools
 
-```bash
-claude mcp add aicoin-opendata -- npx -y @aicoin/opendata-mcp
-```
+| Tool | What it does |
+|------|-------------|
+| `coin_info` | Coin list, real-time prices, profiles, AI analysis |
+| `coin_funding_rate` | Funding rate history (per-exchange or volume-weighted) |
+| `coin_liquidation` | Liquidation heatmap, history, estimated liquidation chart |
+| `coin_open_interest` | Aggregated OI history (stablecoin / coin-margined) |
+| `coin_futures_data` | Futures order book history, large orders, trade data |
+| `market_info` | Exchange list, platform tickers, trending coins, futures OI rankings |
+| `kline` | Standard & indicator K-lines, trading pair discovery |
+| `index_data` | Index prices, details, list of all available indexes |
+| `crypto_stock` | Crypto-related stock quotes, top gainers, company info |
+| `coin_treasury` | Corporate holdings (entities, trade history, accumulated) |
+| `depth` | Real-time order book snapshots (latest, full, grouped) |
+| `market_overview` | Market nav, long/short ratio, liquidation, grayscale, stocks |
+| `order_flow` | Whale order tracking, aggregated large trades |
+| `trading_pair` | Trading pair tickers, pairs by platform, filtered search |
+| `signal_data` | Win-rate strategy signals, alerts, abnormal price movements |
+| `signal_manage` | Add or delete signal alerts |
+| `news` | Paginated news articles, full article detail, RSS feed |
+| `flash` | Flash news, industry flashes, exchange listing announcements |
+| `hl_ticker` | Hyperliquid tickers (single coin or all) |
+| `hl_whale` | HL whale positions, events, long/short directions |
+| `hl_liquidation` | HL liquidation history, stats, top liquidated positions |
+| `hl_open_interest` | HL OI summary, top coins, per-coin history |
+| `hl_taker` | HL taker buy/sell delta, K-lines with taker volume |
+| `hl_trader` | HL trader stats, best trades, performance, batch analytics |
+| `hl_fills` | HL trade fills by address/order/TWAP, top trades |
+| `hl_orders` | HL orders (latest, filled, top open, active stats, TWAP) |
+| `hl_position` | HL position history, PnL, execution trace |
+| `hl_portfolio` | HL portfolio curve, PnL, max drawdown, net flow |
+| `hl_advanced` | HL generic info API, smart money finder, trader discovery |
+| `guide` | Setup guides for API key and tier upgrade |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AICOIN_ACCESS_KEY_ID` | No | AiCoin API key (free tier built-in, rate-limited) |
+| `AICOIN_ACCESS_SECRET` | No | AiCoin API secret |
+
+## 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 |
+
+Upgrade at [aicoin.com/opendata](https://www.aicoin.com/opendata). Your existing key is automatically upgraded.
+
+## Migrating from v1.x
+
+v2.0 consolidates 100+ individual tools into **30 action-based tools**. Each tool now supports multiple actions via an `action` parameter (e.g., `coin_info` with `action: "list"` / `"ticker"` / `"config"` / `"ai_analysis"`).
+
+This reduces context overhead for AI assistants and improves tool selection accuracy. All API endpoints remain the same — only the tool interface changed.
+
+## License
+
+MIT