@aicoin/aicoin-mcp 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +222 -110
  2. package/build/index.js +6 -21
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,139 +1,251 @@
1
- # @aicoin/mcp
1
+ # @aicoin/aicoin-mcp
2
2
 
3
- Unified AiCoin MCP Server — crypto market data + trading in one package.
3
+ AiCoin MCP Server — real-time crypto market data & exchange trading for any AI assistant.
4
4
 
5
- Merges `@aicoin/opendata-mcp` (market data via AiCoin API) and `@aicoin/trade-mcp` (trading via CCXT) into **41 tools**.
5
+ **41 tools** · Market data · K-lines · Funding rates · Liquidations · Order flow · Hyperliquid analytics · News · Multi-exchange trading via CCXT
6
6
 
7
- ## Quick Start
7
+ ## Connect
8
+
9
+ Get your free API key at [aicoin.com/opendata](https://www.aicoin.com/opendata), then add to your MCP client:
10
+
11
+ ### Claude Code
12
+
13
+ ```bash
14
+ claude mcp add aicoin -- npx -y @aicoin/aicoin-mcp \
15
+ --env AICOIN_ACCESS_KEY_ID=your-key-id \
16
+ --env AICOIN_ACCESS_SECRET=your-secret
17
+ ```
18
+
19
+ Or add to `.mcp.json` in your project root:
20
+
21
+ ```json
22
+ {
23
+ "mcpServers": {
24
+ "aicoin": {
25
+ "command": "npx",
26
+ "args": ["-y", "@aicoin/aicoin-mcp"],
27
+ "env": {
28
+ "AICOIN_ACCESS_KEY_ID": "your-key-id",
29
+ "AICOIN_ACCESS_SECRET": "your-secret"
30
+ }
31
+ }
32
+ }
33
+ }
34
+ ```
35
+
36
+ ### Cursor
37
+
38
+ Settings → MCP → Add new MCP server:
8
39
 
9
40
  ```json
10
41
  {
11
42
  "mcpServers": {
12
43
  "aicoin": {
13
44
  "command": "npx",
14
- "args": ["-y", "@aicoin/mcp"],
45
+ "args": ["-y", "@aicoin/aicoin-mcp"],
15
46
  "env": {
16
- "AICOIN_ACCESS_KEY_ID": "<your opendata key>",
17
- "AICOIN_ACCESS_SECRET": "<your opendata secret>",
18
- "DEFAULT_EXCHANGE": "binance",
19
- "BINANCE_API_KEY": "<your key>",
20
- "BINANCE_SECRET": "<your secret>",
21
- "USE_PROXY": "false"
47
+ "AICOIN_ACCESS_KEY_ID": "your-key-id",
48
+ "AICOIN_ACCESS_SECRET": "your-secret"
22
49
  }
23
50
  }
24
51
  }
25
52
  }
26
53
  ```
27
54
 
55
+ ### Windsurf
56
+
57
+ Add to `~/.codeium/windsurf/mcp_config.json`:
58
+
59
+ ```json
60
+ {
61
+ "mcpServers": {
62
+ "aicoin": {
63
+ "command": "npx",
64
+ "args": ["-y", "@aicoin/aicoin-mcp"],
65
+ "env": {
66
+ "AICOIN_ACCESS_KEY_ID": "your-key-id",
67
+ "AICOIN_ACCESS_SECRET": "your-secret"
68
+ }
69
+ }
70
+ }
71
+ }
72
+ ```
73
+
74
+ ### VS Code (Copilot)
75
+
76
+ Add to `.vscode/mcp.json` in your project:
77
+
78
+ ```json
79
+ {
80
+ "mcp": {
81
+ "servers": {
82
+ "aicoin": {
83
+ "type": "stdio",
84
+ "command": "npx",
85
+ "args": ["-y", "@aicoin/aicoin-mcp"],
86
+ "env": {
87
+ "AICOIN_ACCESS_KEY_ID": "your-key-id",
88
+ "AICOIN_ACCESS_SECRET": "your-secret"
89
+ }
90
+ }
91
+ }
92
+ }
93
+ }
94
+ ```
95
+
96
+ ### Claude Desktop
97
+
98
+ Add to `claude_desktop_config.json`:
99
+
100
+ ```json
101
+ {
102
+ "mcpServers": {
103
+ "aicoin": {
104
+ "command": "npx",
105
+ "args": ["-y", "@aicoin/aicoin-mcp"],
106
+ "env": {
107
+ "AICOIN_ACCESS_KEY_ID": "your-key-id",
108
+ "AICOIN_ACCESS_SECRET": "your-secret"
109
+ }
110
+ }
111
+ }
112
+ }
113
+ ```
114
+
115
+ ### OpenCode
116
+
117
+ Add to `.opencode/config.toml`:
118
+
119
+ ```toml
120
+ [mcp_servers.aicoin]
121
+ command = "npx"
122
+ args = ["-y", "@aicoin/aicoin-mcp"]
123
+
124
+ [mcp_servers.aicoin.env]
125
+ AICOIN_ACCESS_KEY_ID = "your-key-id"
126
+ AICOIN_ACCESS_SECRET = "your-secret"
127
+ ```
128
+
129
+ ### Codex
130
+
131
+ ```bash
132
+ codex --mcp-config mcp.json
133
+ ```
134
+
135
+ Where `mcp.json` contains:
136
+
137
+ ```json
138
+ {
139
+ "mcpServers": {
140
+ "aicoin": {
141
+ "command": "npx",
142
+ "args": ["-y", "@aicoin/aicoin-mcp"],
143
+ "env": {
144
+ "AICOIN_ACCESS_KEY_ID": "your-key-id",
145
+ "AICOIN_ACCESS_SECRET": "your-secret"
146
+ }
147
+ }
148
+ }
149
+ }
150
+ ```
151
+
152
+ ## Enable Exchange Trading (Optional)
153
+
154
+ To place orders, check balances, and manage positions, add your exchange API key:
155
+
156
+ ```json
157
+ {
158
+ "env": {
159
+ "AICOIN_ACCESS_KEY_ID": "your-key-id",
160
+ "AICOIN_ACCESS_SECRET": "your-secret",
161
+ "DEFAULT_EXCHANGE": "okx",
162
+ "OKX_API_KEY": "your-exchange-key",
163
+ "OKX_SECRET": "your-exchange-secret",
164
+ "OKX_PASSPHRASE": "your-passphrase"
165
+ }
166
+ }
167
+ ```
168
+
169
+ Exchange API keys are stored locally only and never sent to AiCoin servers.
170
+
171
+ **Supported exchanges:** `binance` `binanceusdm` `binancecoinm` `okx` `bybit` `bitget` `gate` `huobi` `hyperliquid`
172
+
173
+ ## Tools
174
+
175
+ ### Market Data (30 tools)
176
+
177
+ | Tool | What it does |
178
+ |------|-------------|
179
+ | `coin_info` | Coin list, real-time prices, profiles, AI analysis |
180
+ | `coin_funding_rate` | Funding rate history (per-exchange or volume-weighted) |
181
+ | `coin_liquidation` | Liquidation heatmap, history, estimated liquidation chart |
182
+ | `coin_open_interest` | Aggregated OI history (stablecoin / coin-margined) |
183
+ | `coin_futures_data` | Futures order book history, large orders, trade data |
184
+ | `market_info` | Exchange list, platform tickers, trending coins, futures OI rankings |
185
+ | `kline` | Standard & indicator K-lines, trading pair discovery |
186
+ | `index_data` | Index prices, details, list of all available indexes |
187
+ | `crypto_stock` | Crypto-related stock quotes, top gainers, company info |
188
+ | `coin_treasury` | Corporate holdings (entities, trade history, accumulated) |
189
+ | `depth` | Real-time order book snapshots (latest, full, grouped) |
190
+ | `market_overview` | Market nav, long/short ratio, liquidation, grayscale, stocks |
191
+ | `order_flow` | Whale order tracking, aggregated large trades |
192
+ | `trading_pair` | Trading pair tickers, pairs by platform, filtered search |
193
+ | `signal_data` | Win-rate strategy signals, alerts, abnormal price movements |
194
+ | `signal_manage` | Delete signal alerts |
195
+ | `news` | Paginated news articles, full article detail, RSS feed |
196
+ | `flash` | Flash news, industry flashes, exchange listing announcements |
197
+ | `hl_ticker` | Hyperliquid tickers (single coin or all) |
198
+ | `hl_whale` | HL whale positions, events, long/short directions |
199
+ | `hl_liquidation` | HL liquidation history, stats, top liquidated positions |
200
+ | `hl_open_interest` | HL OI summary, top coins, per-coin history |
201
+ | `hl_taker` | HL taker buy/sell delta, K-lines with taker volume |
202
+ | `hl_trader` | HL trader stats, best trades, performance, batch analytics |
203
+ | `hl_fills` | HL trade fills by address/order/TWAP, top trades |
204
+ | `hl_orders` | HL orders (latest, filled, top open, active stats, TWAP) |
205
+ | `hl_position` | HL position history, PnL, execution trace |
206
+ | `hl_portfolio` | HL portfolio curve, PnL, max drawdown, net flow |
207
+ | `hl_advanced` | HL generic info API, smart money finder, trader discovery |
208
+ | `guide` | Setup guides for API key, tier upgrade, exchange trading |
209
+
210
+ ### Exchange Trading (11 tools)
211
+
212
+ | Tool | What it does |
213
+ |------|-------------|
214
+ | `exchange_info` | List supported exchanges, query trading pairs |
215
+ | `exchange_ticker` | Real-time ticker (single or batch) |
216
+ | `exchange_market_data` | Order book, recent trades, OHLCV candlesticks |
217
+ | `exchange_funding` | Current and historical funding rates |
218
+ | `account_status` | Account balance and open positions |
219
+ | `account_orders` | Query open/closed orders, trade history |
220
+ | `account_history` | Ledger, deposit, and withdrawal history |
221
+ | `create_order` | Place market or limit orders |
222
+ | `cancel_order` | Cancel single or all open orders |
223
+ | `set_trading_config` | Set leverage and margin mode |
224
+ | `transfer` | Transfer funds between accounts (spot/futures) |
225
+
28
226
  ## Environment Variables
29
227
 
30
228
  | Variable | Required | Description |
31
229
  |----------|----------|-------------|
32
- | `AICOIN_ACCESS_KEY_ID` | No | AiCoin OpenData API key (free tier built-in) |
33
- | `AICOIN_ACCESS_SECRET` | No | AiCoin OpenData API secret |
34
- | `DEFAULT_EXCHANGE` | No | Default exchange for trading (default: binance) |
230
+ | `AICOIN_ACCESS_KEY_ID` | No | AiCoin API key (free tier built-in, rate-limited) |
231
+ | `AICOIN_ACCESS_SECRET` | No | AiCoin API secret |
232
+ | `DEFAULT_EXCHANGE` | No | Default exchange for trading (default: `binance`) |
35
233
  | `{EXCHANGE}_API_KEY` | For trading | Exchange API key |
36
234
  | `{EXCHANGE}_SECRET` | For trading | Exchange API secret |
37
235
  | `{EXCHANGE}_PASSPHRASE` | OKX/Bitget | Exchange passphrase |
38
- | `USE_PROXY` | No | Enable proxy (true/false) |
39
- | `PROXY_URL` | No | Proxy URL (http/https/socks5) |
40
-
41
- Supported exchanges: `binance`, `binanceusdm`, `binancecoinm`, `okx`, `bybit`, `bitget`, `gate`, `huobi`, `hyperliquid`
42
-
43
- ## Tools (41)
44
-
45
- ### Trade (11) — CCXT-based exchange trading
46
-
47
- | # | Tool | Description |
48
- |---|------|-------------|
49
- | 1 | `exchange_info` | List exchanges, query trading pairs. Actions: `exchanges`, `markets` |
50
- | 2 | `exchange_ticker` | Real-time ticker (single or batch) |
51
- | 3 | `exchange_market_data` | Order book, trades, OHLCV. Actions: `orderbook`, `trades`, `ohlcv` |
52
- | 4 | `exchange_funding` | Funding rates. Actions: `current`, `history` |
53
- | 5 | `account_status` | Account balance & positions. Actions: `balance`, `positions` |
54
- | 6 | `account_orders` | Order queries. Actions: `open`, `closed`, `by_id`, `my_trades` |
55
- | 7 | `account_history` | Account history. Actions: `ledger`, `deposits`, `withdrawals` |
56
- | 8 | `create_order` | Place market/limit orders |
57
- | 9 | `cancel_order` | Cancel single or all orders |
58
- | 10 | `set_trading_config` | Set leverage & margin mode. Actions: `leverage`, `margin_mode` |
59
- | 11 | `transfer` | Transfer funds between accounts |
60
-
61
- ### Coins (5) — AiCoin coin data
62
-
63
- | # | Tool | Description |
64
- |---|------|-------------|
65
- | 12 | `coin_info` | Coin data. Actions: `list`, `ticker`, `config`, `ai_analysis` |
66
- | 13 | `coin_funding_rate` | Funding rate history (regular or volume-weighted) |
67
- | 14 | `coin_liquidation` | Liquidation data. Actions: `map`, `history`, `estimated` |
68
- | 15 | `coin_open_interest` | Aggregated OI history (stablecoin or coin-margined) |
69
- | 16 | `coin_futures_data` | Futures depth & trades. Actions: `historical_depth`, `super_depth`, `trade_data` |
70
-
71
- ### Contents (2) — News & flash
72
-
73
- | # | Tool | Description |
74
- |---|------|-------------|
75
- | 17 | `news` | News articles. Actions: `list`, `detail`, `rss` |
76
- | 18 | `flash` | Flash news. Actions: `newsflash`, `list`, `exchange_listing` |
77
-
78
- ### Markets (6) — Market & index data
79
-
80
- | # | Tool | Description |
81
- |---|------|-------------|
82
- | 19 | `market_info` | Exchange/market data. Actions: `exchanges`, `ticker`, `hot_coins`, `futures_interest` |
83
- | 20 | `kline` | K-line data. Actions: `data`, `indicator`, `trading_pair` |
84
- | 21 | `index_data` | Index data. Actions: `price`, `info`, `list` |
85
- | 22 | `crypto_stock` | Crypto stocks. Actions: `quotes`, `top_gainer`, `company` |
86
- | 23 | `coin_treasury` | Corporate holdings. Actions: `entities`, `history`, `accumulated`, `latest_entities`, `latest_history`, `summary` |
87
- | 24 | `depth` | Order book depth. Actions: `latest`, `full`, `grouped` |
88
-
89
- ### Features (5) — Signals & analytics
90
-
91
- | # | Tool | Description |
92
- |---|------|-------------|
93
- | 25 | `market_overview` | Market overview. Actions: `nav`, `ls_ratio`, `liquidation`, `grayscale_trust`, `gray_scale`, `stock_market` |
94
- | 26 | `order_flow` | Order flow. Actions: `big_orders`, `agg_trades` |
95
- | 27 | `trading_pair` | Trading pairs. Actions: `ticker`, `by_market`, `list` |
96
- | 28 | `signal_data` | Signal data. Actions: `strategy`, `alert`, `config`, `alert_list`, `change` |
97
- | 29 | `signal_manage` | Manage alerts. Actions: `add`, `delete` |
98
-
99
- ### Hyperliquid (11) — HL-specific analytics
100
-
101
- | # | Tool | Description |
102
- |---|------|-------------|
103
- | 30 | `hl_ticker` | HL tickers (single coin or batch) |
104
- | 31 | `hl_whale` | Whale data. Actions: `positions`, `events`, `directions`, `history_ratio` |
105
- | 32 | `hl_liquidation` | Liquidation data. Actions: `history`, `stats`, `stats_by_coin`, `top_positions` |
106
- | 33 | `hl_open_interest` | OI data. Actions: `summary`, `top_coins`, `history` |
107
- | 34 | `hl_taker` | Taker data. Actions: `delta`, `klines` |
108
- | 35 | `hl_trader` | Trader analytics. Actions: `stats`, `best_trades`, `performance`, `completed_trades`, `accounts`, `statistics` |
109
- | 36 | `hl_fills` | Trade fills. Actions: `by_address`, `by_oid`, `by_twapid`, `top_trades` |
110
- | 37 | `hl_orders` | Orders. Actions: `latest`, `by_oid`, `filled`, `filled_by_oid`, `top_open`, `active_stats`, `twap_states` |
111
- | 38 | `hl_position` | Position data. Actions: `current_history`, `completed_history`, `current_pnl`, `completed_pnl`, `current_executions`, `completed_executions` |
112
- | 39 | `hl_portfolio` | Portfolio data. Actions: `portfolio`, `pnls`, `max_drawdown`, `net_flow` |
113
- | 40 | `hl_advanced` | Advanced. Actions: `info`, `smart_find`, `discover` |
114
-
115
- ### Guide (1)
116
-
117
- | # | Tool | Description |
118
- |---|------|-------------|
119
- | 41 | `guide` | Setup guides. Actions: `api_key`, `upgrade`, `trade_setup` |
120
-
121
- ## Testing
236
+ | `USE_PROXY` | No | Enable proxy (`true`/`false`) |
237
+ | `PROXY_URL` | No | Proxy URL, e.g. `http://127.0.0.1:7890` |
122
238
 
123
- ```bash
124
- npm run build
125
- node test-tools.mjs # Test all tools
126
- node test-tools.mjs hl_ # Test Hyperliquid only
127
- node test-tools.mjs coin # Test coin-related only
128
- ```
239
+ ## API Tiers
129
240
 
130
- ## Development
241
+ | Tier | Price | Rate Limit | Features |
242
+ |------|-------|------------|----------|
243
+ | Basic | Free | 10 req/min | Market data, news, K-lines, indexes |
244
+ | Normal | ¥99/mo | 60 req/min | + Funding rate, liquidation, OI |
245
+ | Premium | ¥299/mo | 120 req/min | + Depth, whale tracking, order flow |
246
+ | Professional | ¥999/mo | 300 req/min | + Full depth, all features |
131
247
 
132
- ```bash
133
- npm run dev # Watch mode
134
- npm run build # Production build
135
- npm start # Run server
136
- ```
248
+ Upgrade at [aicoin.com/opendata](https://www.aicoin.com/opendata). Your existing key is automatically upgraded.
137
249
 
138
250
  ## License
139
251
 
package/build/index.js CHANGED
@@ -1554,28 +1554,13 @@ function registerFeatureTools(server2) {
1554
1554
  );
1555
1555
  server2.tool(
1556
1556
  "signal_manage",
1557
- "Manage signal alerts.\n\u2022 add \u2014 create new alert. Requires: subType + symbol\n\u2022 delete \u2014 remove alert. Requires: id",
1557
+ "Delete a signal alert. Requires: id",
1558
1558
  {
1559
- action: z6.enum(["add", "delete"]).describe("add: create new alert; delete: remove alert by ID"),
1560
- id: z6.string().optional().describe("REQUIRED for delete. Signal alert ID"),
1561
- subType: z6.string().optional().describe("REQUIRED for add. Alert sub type"),
1562
- symbol: z6.string().optional().describe("REQUIRED for add. Trading pair symbol"),
1563
- remark: z6.string().optional().describe("For add: alert remark/note")
1559
+ id: z6.string().describe("REQUIRED. Signal alert ID to delete")
1564
1560
  },
1565
- async ({ action, id, subType, symbol, remark }) => {
1561
+ async ({ id }) => {
1566
1562
  try {
1567
- switch (action) {
1568
- case "add": {
1569
- if (!subType || !symbol) return err("subType and symbol are required for add action");
1570
- const params = { subType, symbol };
1571
- if (remark) params.remark = remark;
1572
- return ok(await apiGet("/api/v2/signal/addSignalAlert", params));
1573
- }
1574
- case "delete": {
1575
- if (!id) return err("id is required for delete action");
1576
- return ok(await apiGet("/api/v2/signal/delSignalAlert", { id }));
1577
- }
1578
- }
1563
+ return ok(await apiGet("/api/v2/signal/delSignalAlert", { id }));
1579
1564
  } catch (e) {
1580
1565
  return err(e);
1581
1566
  }
@@ -2133,7 +2118,7 @@ Add them to your MCP client config:
2133
2118
  "mcpServers": {
2134
2119
  "aicoin": {
2135
2120
  "command": "npx",
2136
- "args": ["-y", "@aicoin/mcp"],
2121
+ "args": ["-y", "@aicoin/aicoin-mcp"],
2137
2122
  "env": {
2138
2123
  "AICOIN_ACCESS_KEY_ID": "<your accessKeyId>",
2139
2124
  "AICOIN_ACCESS_SECRET": "<your accessSecret>"
@@ -2235,7 +2220,7 @@ Common proxy ports:
2235
2220
  "mcpServers": {
2236
2221
  "aicoin": {
2237
2222
  "command": "npx",
2238
- "args": ["-y", "@aicoin/mcp"],
2223
+ "args": ["-y", "@aicoin/aicoin-mcp"],
2239
2224
  "env": {
2240
2225
  "AICOIN_ACCESS_KEY_ID": "<your opendata key>",
2241
2226
  "AICOIN_ACCESS_SECRET": "<your opendata secret>",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aicoin/aicoin-mcp",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "description": "AiCoin MCP Server - unified crypto market data & trading via AiCoin API + CCXT",
5
5
  "main": "build/index.js",
6
6
  "type": "module",