crypto-quant-signal-mcp 1.4.1 → 1.6.0

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 (42) hide show
  1. package/README.md +149 -113
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +448 -170
  4. package/dist/index.js.map +1 -1
  5. package/dist/lib/adapters/hyperliquid.d.ts +4 -4
  6. package/dist/lib/adapters/hyperliquid.d.ts.map +1 -1
  7. package/dist/lib/adapters/hyperliquid.js +13 -10
  8. package/dist/lib/adapters/hyperliquid.js.map +1 -1
  9. package/dist/lib/analytics.d.ts.map +1 -1
  10. package/dist/lib/analytics.js +3 -1
  11. package/dist/lib/analytics.js.map +1 -1
  12. package/dist/lib/asset-tiers.d.ts +38 -0
  13. package/dist/lib/asset-tiers.d.ts.map +1 -0
  14. package/dist/lib/asset-tiers.js +199 -0
  15. package/dist/lib/asset-tiers.js.map +1 -0
  16. package/dist/lib/license.d.ts.map +1 -1
  17. package/dist/lib/license.js +33 -9
  18. package/dist/lib/license.js.map +1 -1
  19. package/dist/lib/oi-ranking.d.ts +25 -0
  20. package/dist/lib/oi-ranking.d.ts.map +1 -0
  21. package/dist/lib/oi-ranking.js +111 -0
  22. package/dist/lib/oi-ranking.js.map +1 -0
  23. package/dist/lib/performance-db.d.ts.map +1 -1
  24. package/dist/lib/performance-db.js +96 -13
  25. package/dist/lib/performance-db.js.map +1 -1
  26. package/dist/lib/stripe.d.ts +19 -0
  27. package/dist/lib/stripe.d.ts.map +1 -0
  28. package/dist/lib/stripe.js +196 -0
  29. package/dist/lib/stripe.js.map +1 -0
  30. package/dist/scripts/seed-signals.js +39 -15
  31. package/dist/scripts/seed-signals.js.map +1 -1
  32. package/dist/tools/get-market-regime.d.ts.map +1 -1
  33. package/dist/tools/get-market-regime.js +5 -2
  34. package/dist/tools/get-market-regime.js.map +1 -1
  35. package/dist/tools/get-trade-signal.d.ts.map +1 -1
  36. package/dist/tools/get-trade-signal.js +45 -33
  37. package/dist/tools/get-trade-signal.js.map +1 -1
  38. package/dist/tools/scan-funding-arb.js +2 -2
  39. package/dist/types.d.ts +37 -4
  40. package/dist/types.d.ts.map +1 -1
  41. package/package.json +3 -2
  42. package/server.json +3 -3
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  # crypto-quant-signal-mcp
6
6
 
7
- AI trading brain for crypto perps — composite signals, funding rate arb scanning, and market regime detection via MCP.
7
+ The signal intelligence layer for AI trading agents — composite quant signals across crypto and TradFi perps, cross-venue arbitrage detection, and regime-aware market classification via MCP.
8
8
 
9
9
  [![npm version](https://img.shields.io/npm/v/crypto-quant-signal-mcp)](https://www.npmjs.com/package/crypto-quant-signal-mcp)
10
10
  [![npm downloads](https://img.shields.io/npm/dw/crypto-quant-signal-mcp)](https://www.npmjs.com/package/crypto-quant-signal-mcp)
@@ -12,6 +12,23 @@ AI trading brain for crypto perps — composite signals, funding rate arb scanni
12
12
 
13
13
  ---
14
14
 
15
+ ## Why AlgoVault
16
+
17
+ Most MCP trading servers give you raw data — prices, order books, candles. Your agent still has to figure out what to do with it.
18
+
19
+ AlgoVault is different. We give your agent **one answer**: a directional verdict with a confidence score, built from a multi-factor composite scoring engine tuned on production quant systems. Every signal is tracked, every outcome is measured, and the full track record is public from day one.
20
+
21
+ **What makes this not just another indicator wrapper:**
22
+
23
+ - **Composite scoring, not single-indicator noise.** Multiple orthogonal signals — momentum oscillators, trend structure, derivatives positioning, volume dynamics, open interest flow — fused into a single weighted verdict. The weights are calibrated from live market outcome data, not textbook defaults.
24
+ - **Regime-aware signal generation.** Signals are filtered through a market regime classifier before emission. The engine knows when to signal and when to stay silent — a trend-following setup in a ranging market gets suppressed, not broadcast.
25
+ - **Cross-venue intelligence.** Funding rates from Hyperliquid, Binance, and Bybit are normalized and compared in real-time. Nobody else does cross-venue derivatives analysis via MCP.
26
+ - **Published track record with every release.** Every signal is recorded with outcome prices at multiple horizons. Win rate, profit factor, and expected value are computed continuously. No cherry-picking, no survivorship bias.
27
+ - **Adaptive scoring.** Indicator weights are retuned monthly from outcome data. The engine learns what works and adjusts — the signal you get today is better than the one from last month.
28
+ - **Crypto + TradFi coverage.** 290+ assets — standard crypto perps, TradFi perpetuals (stocks, indices, commodities, FX via Hyperliquid's xyz dex), and liquidity-filtered meme coins. Assets are classified into quality tiers with institutional-grade signal filtering.
29
+
30
+ ---
31
+
15
32
  ## Try It in 30 Seconds
16
33
 
17
34
  No code. No API key. No install.
@@ -29,23 +46,92 @@ No code. No API key. No install.
29
46
 
30
47
  **Step 3.** Ask Claude anything:
31
48
 
32
- > "Get me a trade signal for BTC"
49
+ > "Get me a trade signal for ETH on the 4h timeframe"
33
50
 
34
51
  ![BTC Signal Result](https://raw.githubusercontent.com/AlgoVaultLabs/crypto-quant-signal-mcp/main/docs/screenshots/BTC-signal.png)
35
52
 
36
- That's it. You now have a crypto quant analyst inside Claude.
53
+ That's it. Your Claude now has a quant analyst built in.
54
+
55
+ ---
56
+
57
+ ## Tools
58
+
59
+ ### `get_trade_signal`
60
+
61
+ Returns a composite **BUY / SELL / HOLD** verdict with confidence score for any supported asset — crypto perps, TradFi perpetuals (stocks, indices, commodities, FX), and liquidity-filtered meme coins on Hyperliquid.
62
+
63
+ Under the hood: a multi-factor scoring engine evaluates momentum, trend structure, derivatives sentiment, open interest dynamics, and volume conviction. Scores pass through regime-aware filters and adaptive post-processing gates — including funding flow analysis, volatility regime detection, and trend persistence decay — before a final verdict is emitted.
64
+
65
+ Only high-conviction signals are generated. The engine is designed to stay silent when the edge is unclear.
66
+
67
+ **Parameters:**
68
+ - `coin` (string, required): Asset symbol — e.g. `"ETH"`, `"BTC"`, `"SOL"`, `"GOLD"`, `"TSLA"`, or any of 290+ supported assets
69
+ - `timeframe` (string, default `"15m"`): `"1m"`, `"3m"`, `"5m"`, `"15m"`, `"30m"`, `"1h"`, `"2h"`, `"4h"`, `"8h"`, `"12h"`, `"1d"`
70
+ - `includeReasoning` (boolean, default `true`): Human-readable explanation of the signal logic
71
+
72
+ **Output includes:** signal direction, confidence score (0–100), all computed indicator values, detected market regime, reasoning narrative, and `_algovault` metadata for downstream tool composability.
73
+
74
+ ### `scan_funding_arb`
75
+
76
+ Scans cross-venue funding rate differentials across Hyperliquid, Binance, and Bybit. Normalizes hourly vs 8-hour rate conventions, computes basis-point spreads, and ranks opportunities by annualized return.
77
+
78
+ This is the only MCP server that provides cross-venue funding arbitrage intelligence — long one exchange, short another, capture the spread.
79
+
80
+ **Parameters:**
81
+ - `minSpreadBps` (number, default `5`): Minimum spread in basis points to include
82
+ - `limit` (number, default `10`): Maximum results returned
83
+
84
+ **Output includes:** per-opportunity venue rates, optimal long/short direction, annualized spread percentage, and next funding timestamps.
85
+
86
+ ### `get_market_regime`
87
+
88
+ Classifies the current market environment into one of four regimes: **TRENDING_UP**, **TRENDING_DOWN**, **RANGING**, or **VOLATILE**.
89
+
90
+ Uses a multi-dimensional classification approach combining directional strength measurement, normalized volatility analysis, price structure pattern recognition, and cross-venue funding sentiment divergence. The regime classification directly informs how `get_trade_signal` filters its output — agents can also use it independently for strategy selection and position sizing.
91
+
92
+ **Parameters:**
93
+ - `coin` (string, required): Asset symbol
94
+ - `timeframe` (string, default `"4h"`): Candle timeframe for analysis
95
+
96
+ **Output includes:** regime label, confidence score, underlying metrics (trend strength, volatility interpretation, price structure), cross-venue funding sentiment, and a plain-English strategy suggestion.
97
+
98
+ ---
99
+
100
+ ## Performance Tracking
101
+
102
+ Every signal is tracked from emission to outcome. No exceptions.
103
+
104
+ **What we measure:**
105
+ - Outcome prices at timeframe-appropriate evaluation windows
106
+ - PFE Win Rate — did price move in the signal direction at any point during the evaluation window
107
+ - Expected Value — probability-weighted average return per signal
108
+ - Profit Factor — gross wins divided by gross losses
109
+ - Peak Favorable Excursion (PFE) and Maximum Adverse Excursion (MAE)
110
+ - Running statistics per asset, timeframe, and quality tier
111
+
112
+ **Infrastructure:**
113
+ - Remote mode: PostgreSQL with automated outcome backfill
114
+ - Local mode: SQLite at `~/.crypto-quant-signal/performance.db`
115
+ - Only high-confidence BUY/SELL signals are tracked — HOLD is excluded
37
116
 
38
117
  ---
39
118
 
40
- ## What It Does
119
+ ## Pricing
120
+
121
+ | Feature | Free | Pro ($49/mo) | Enterprise ($299/mo) | x402 (per call) |
122
+ |---------|------|-------------|---------------------|-----------------|
123
+ | Assets | BTC, ETH | All 290+ assets | All 290+ | All 290+ |
124
+ | Asset classes | Crypto only | Crypto + TradFi | Crypto + TradFi | Crypto + TradFi |
125
+ | Timeframes | 15m, 1h | All 11 | All 11 | All 11 |
126
+ | Funding arb results | Top 5 | Unlimited | Unlimited | Unlimited |
127
+ | Track record | Full access | Full access | Full access | Full access |
128
+ | Monthly calls | ~100/day | 15,000/mo | Unlimited | Unlimited |
129
+ | Support | Community | Email | Priority | — |
130
+ | Price | $0 | $49/mo | $299/mo | $0.01–0.05/call |
41
131
 
42
- | Tool | What you get |
43
- |------|-------------|
44
- | `get_trade_signal` | BUY/SELL/HOLD verdict with confidence score. Combines RSI, EMA crossover, funding rate, OI momentum, and volume. |
45
- | `scan_funding_arb` | Cross-venue funding rate arbitrage opportunities (Hyperliquid vs Binance vs Bybit) with annualized spreads. |
46
- | `get_market_regime` | Market regime classification — TRENDING_UP, TRENDING_DOWN, RANGING, or VOLATILE — with cross-venue funding sentiment. |
132
+ **x402 micropayments:** AI agents pay per HTTP call with USDC on Base — no signup, no API key, no billing. The payment receipt is the credential. See [x402.org](https://x402.org).
47
133
 
48
- Every signal is tracked. Outcomes are measured at 15m, 1h, 4h, and 24h. The track record ships from day one.
134
+ **Subscriptions:** Sign up at [api.algovault.com/signup](https://api.algovault.com/signup). API key delivered instantly after checkout.
49
135
 
50
136
  ---
51
137
 
@@ -53,12 +139,11 @@ Every signal is tracked. Outcomes are measured at 15m, 1h, 4h, and 24h. The trac
53
139
 
54
140
  ### Remote endpoint (recommended)
55
141
 
56
- Point any MCP client at:
57
142
  ```
58
143
  https://api.algovault.com/mcp
59
144
  ```
60
145
 
61
- Supports Streamable HTTP transport. Pay per call with x402 (USDC on Base) — no signup needed.
146
+ Streamable HTTP transport. Compatible with any MCP client — Claude, Cursor, Cline, custom agents.
62
147
 
63
148
  ### Local install via npx
64
149
 
@@ -68,8 +153,6 @@ npx -y crypto-quant-signal-mcp
68
153
 
69
154
  ### Claude Desktop / Cursor config
70
155
 
71
- Add to `claude_desktop_config.json`:
72
-
73
156
  ```json
74
157
  {
75
158
  "mcpServers": {
@@ -88,125 +171,76 @@ Add to `claude_desktop_config.json`:
88
171
  npm install crypto-quant-signal-mcp
89
172
  ```
90
173
 
91
- ---
92
-
93
- ## Pricing
94
-
95
- | Feature | Free | Pro ($49/mo) | x402 (per call) |
96
- |---------|------|-------------|-----------------|
97
- | Assets | BTC, ETH | All 200+ HL perps | All 200+ |
98
- | Timeframes | 1h | 1h, 4h, 1d | All |
99
- | Funding arb results | Top 5 | Unlimited | Unlimited |
100
- | Track record | Full access | Full access | Full access |
101
- | Monthly calls | ~100/day | 15,000/mo | Unlimited |
102
- | Price | $0 | $49/mo | $0.01-0.02/call |
103
-
104
- **x402 micropayments:** AI agents pay per HTTP call with USDC on Base chain — no signup, no API key, no billing. Payment receipt is the credential. See [x402.org](https://x402.org).
174
+ ### Self-hosting
105
175
 
106
- **API key:** Set `CQS_API_KEY` env var or pass `Authorization: Bearer <key>` header.
107
-
108
- ---
109
-
110
- ## Tools Reference
111
-
112
- ### get_trade_signal
113
-
114
- Composite signal from five weighted indicators (v3 scoring):
115
-
116
- | Indicator | Weight | What it measures |
117
- |-----------|--------|-----------------|
118
- | RSI(14) | 30% | Oversold/overbought with 7-tier scoring |
119
- | EMA(9/21) | 20% | Trend direction via crossover |
120
- | Funding rate | 20% | Derivatives sentiment + crowding penalty |
121
- | OI momentum | 15% | New money confirmation |
122
- | Volume | 20% | Conviction from 24h volume vs moving average |
123
-
124
- v3 features: asymmetric thresholds (BUY requires higher conviction than SELL), funding confirmation gate (penalizes BUY when longs are crowded), regime-aware filtering.
125
-
126
- **Parameters:**
127
- - `coin` (string, required): e.g. "ETH", "BTC", "SOL"
128
- - `timeframe` (string, default "1h"): "1h", "4h", or "1d"
129
- - `includeReasoning` (boolean, default true): Human-readable explanation
130
-
131
- ### scan_funding_arb
132
-
133
- Scans cross-venue funding rate differences. Normalizes HL hourly rates vs Binance/Bybit 8h rates and annualizes the spread.
134
-
135
- **Parameters:**
136
- - `minSpreadBps` (number, default 5): Minimum spread in basis points
137
- - `limit` (number, default 10): Max results
138
-
139
- ### get_market_regime
140
-
141
- Classifies market conditions using ADX(14), ATR(14)/price volatility ratio, swing high/low price structure, and cross-venue funding sentiment.
142
-
143
- **Parameters:**
144
- - `coin` (string, required): e.g. "BTC", "ETH"
145
- - `timeframe` (string, default "4h"): "1h", "4h", or "1d"
146
-
147
- ---
148
-
149
- ## Performance Tracking
150
-
151
- Every signal is recorded with outcome prices at **15 minutes, 1 hour, 4 hours, and 24 hours**.
152
-
153
- - **Remote mode:** PostgreSQL — aggregated across all users, backfilled every 15 minutes
154
- - **Local mode:** SQLite at `~/.crypto-quant-signal/performance.db`
155
-
156
- Only signals with confidence >= 40 and a BUY or SELL verdict are tracked. HOLD signals are not recorded.
176
+ ```bash
177
+ git clone https://github.com/AlgoVaultLabs/crypto-quant-signal-mcp
178
+ cd crypto-quant-signal-mcp
179
+ cp .env.example .env # Edit with your values
180
+ npm ci && npm run build
181
+ docker compose up -d
182
+ ```
157
183
 
158
184
  ---
159
185
 
160
186
  ## Architecture
161
187
 
162
188
  ```
163
- Remote Server (Hetzner VPS)
164
- Agent → HTTPS → api.algovault.com/mcp
165
- → x402 payment check → API key check → free tier
166
- → MCP Server (Streamable HTTP, Express)
167
- → PostgreSQL (signal tracking, 15m/1h/4h/24h outcomes)
168
- → Hyperliquid public API
169
-
170
- Local Mode (stdio)
171
- Claude Desktop → stdio → npx crypto-quant-signal-mcp
172
- → Same 3 tools, free tier limits
173
- → SQLite (local tracking)
174
- → Hyperliquid public API
189
+ Agent / Claude / Cursor
190
+ │
191
+ ▼
192
+ api.algovault.com/mcp (Streamable HTTP)
193
+ │
194
+ ├─ x402 payment verification (USDC on Base)
195
+ ├─ API key / subscription check
196
+ ├─ Free tier fallback
197
+ │
198
+ ▼
199
+ MCP Server (Express + @modelcontextprotocol/sdk)
200
+ │
201
+ ├─ Composite Scoring Engine
202
+ │ ├─ Multi-factor indicator fusion
203
+ │ ├─ Regime-aware signal filtering
204
+ │ └─ Adaptive post-processing gates
205
+ │
206
+ ├─ Asset Classification Engine
207
+ │ ├─ 4-tier quality system (Blue Chip → Major Alt → TradFi → Meme)
208
+ │ └─ Liquidity filter for meme/micro assets
209
+ │
210
+ ├─ Exchange Adapter Layer
211
+ │ └─ Hyperliquid (standard + xyz TradFi perps) · Binance, Bybit (funding data)
212
+ │
213
+ ├─ Performance Tracker
214
+ │ └─ PostgreSQL (remote) / SQLite (local)
215
+ │
216
+ └─ Hyperliquid Public API (free, no auth)
175
217
  ```
176
218
 
177
- **Exchange adapter pattern:** code against the `ExchangeAdapter` interface, not raw API calls. Hyperliquid today, more exchanges in Phase 2.
219
+ **Exchange adapter pattern:** All exchange interactions go through the `ExchangeAdapter` interface — supporting both standard crypto perps and xyz TradFi perps on Hyperliquid, with Binance and Bybit for cross-venue funding comparison.
178
220
 
179
221
  ---
180
222
 
181
- ## Suite Compatibility
182
-
183
- All tools output an `_algovault` metadata block for composability:
184
-
185
- | Tool | Feeds into (Phase 2+) |
186
- |------|----------------------|
187
- | `get_trade_signal` | `crypto-quant-risk-mcp`, `crypto-quant-backtest-mcp` |
188
- | `scan_funding_arb` | `crypto-quant-risk-mcp`, `crypto-quant-execution-mcp` |
189
- | `get_market_regime` | `crypto-quant-risk-mcp`, `crypto-quant-backtest-mcp` |
223
+ ## Suite Composability
190
224
 
191
- ---
225
+ Every tool output includes an `_algovault` metadata block declaring version and compatible downstream tools:
192
226
 
193
- ## Self-Hosting
227
+ | This tool | Feeds into (Phase 2+) |
228
+ |-----------|----------------------|
229
+ | `get_trade_signal` | `crypto-quant-risk-mcp` (position sizing) · `crypto-quant-backtest-mcp` (validation) |
230
+ | `scan_funding_arb` | `crypto-quant-execution-mcp` (optimal entry/exit) · `crypto-quant-risk-mcp` (exposure) |
231
+ | `get_market_regime` | `crypto-quant-risk-mcp` (regime-aware sizing) · `crypto-quant-backtest-mcp` (filtered backtests) |
194
232
 
195
- ```bash
196
- git clone https://github.com/AlgoVaultLabs/crypto-quant-signal-mcp
197
- cd crypto-quant-signal-mcp
198
- cp .env.example .env # Edit with your values
199
- npm ci && npm run build
200
- docker compose up -d
201
- ```
233
+ Schemas are designed for composability. All tools share consistent `timestamp`, `coin`, and `_algovault` fields — downstream tools accept these objects directly as input.
202
234
 
203
235
  ---
204
236
 
205
237
  ## Privacy
206
238
 
207
- **Local mode:** No data sent to AlgoVault servers. Signal history stored locally. No telemetry.
239
+ **Local mode:** Zero telemetry. No data sent to AlgoVault servers. Signal history stored on your machine only.
208
240
 
209
- **Remote mode:** Requests logged for analytics (IP hashed, never stored raw). See [privacy policy](https://algovault.com/privacy).
241
+ **Remote mode:** Request metadata logged for analytics (IP hashed, never stored raw). See [privacy policy](https://api.algovault.com/privacy).
242
+
243
+ ---
210
244
 
211
245
  ## License
212
246
 
@@ -214,4 +248,6 @@ MIT
214
248
 
215
249
  ---
216
250
 
217
- Built by [AlgoVault Labs](https://algovault.com) | [Landing page](https://algovault.com) | [API endpoint](https://api.algovault.com/mcp)
251
+ Built by [AlgoVault Labs](https://algovault.com) — signal intelligence for the autonomous trading era.
252
+
253
+ [Landing page](https://algovault.com) · [API endpoint](https://api.algovault.com/mcp)
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AASA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAutBpE,wBAAgB,mBAAmB,cAElC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AASA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAy4BpE,wBAAgB,mBAAmB,cAElC"}