crypto-quant-signal-mcp 1.2.0 → 1.4.1

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 (39) hide show
  1. package/README.md +124 -119
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +172 -116
  4. package/dist/index.js.map +1 -1
  5. package/dist/lib/indicators.d.ts +31 -0
  6. package/dist/lib/indicators.d.ts.map +1 -1
  7. package/dist/lib/indicators.js +109 -0
  8. package/dist/lib/indicators.js.map +1 -1
  9. package/dist/lib/license.js +2 -2
  10. package/dist/lib/license.js.map +1 -1
  11. package/dist/lib/performance-db.d.ts +18 -0
  12. package/dist/lib/performance-db.d.ts.map +1 -1
  13. package/dist/lib/performance-db.js +187 -90
  14. package/dist/lib/performance-db.js.map +1 -1
  15. package/dist/lib/x402.d.ts +1 -0
  16. package/dist/lib/x402.d.ts.map +1 -1
  17. package/dist/lib/x402.js +16 -2
  18. package/dist/lib/x402.js.map +1 -1
  19. package/dist/resources/signal-performance.d.ts +4 -2
  20. package/dist/resources/signal-performance.d.ts.map +1 -1
  21. package/dist/resources/signal-performance.js +79 -27
  22. package/dist/resources/signal-performance.js.map +1 -1
  23. package/dist/scripts/backfill-outcomes.d.ts +17 -8
  24. package/dist/scripts/backfill-outcomes.d.ts.map +1 -1
  25. package/dist/scripts/backfill-outcomes.js +163 -84
  26. package/dist/scripts/backfill-outcomes.js.map +1 -1
  27. package/dist/scripts/seed-signals.d.ts +22 -8
  28. package/dist/scripts/seed-signals.d.ts.map +1 -1
  29. package/dist/scripts/seed-signals.js +72 -29
  30. package/dist/scripts/seed-signals.js.map +1 -1
  31. package/dist/tools/get-market-regime.js +1 -1
  32. package/dist/tools/get-trade-signal.d.ts.map +1 -1
  33. package/dist/tools/get-trade-signal.js +88 -23
  34. package/dist/tools/get-trade-signal.js.map +1 -1
  35. package/dist/tools/scan-funding-arb.js +2 -2
  36. package/dist/types.d.ts +15 -3
  37. package/dist/types.d.ts.map +1 -1
  38. package/package.json +1 -1
  39. package/server.json +1 -1
package/README.md CHANGED
@@ -1,59 +1,74 @@
1
1
  <p align="center">
2
- <img src="logo.png" alt="AlgoVault" width="120" />
2
+ <img src="https://raw.githubusercontent.com/AlgoVaultLabs/crypto-quant-signal-mcp/main/logo.png" alt="AlgoVault" width="120" />
3
3
  </p>
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. Powered by Hyperliquid data. Remote-first with x402 micropayments.
7
+ AI trading brain for crypto perps — composite signals, funding rate arb scanning, and market regime detection via MCP.
8
8
 
9
- ## What It Does
9
+ [![npm version](https://img.shields.io/npm/v/crypto-quant-signal-mcp)](https://www.npmjs.com/package/crypto-quant-signal-mcp)
10
+ [![npm downloads](https://img.shields.io/npm/dw/crypto-quant-signal-mcp)](https://www.npmjs.com/package/crypto-quant-signal-mcp)
11
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10
12
 
11
- Three opinionated tools + one performance resource that combine multiple indicators into a single verdict with confidence score:
13
+ ---
12
14
 
13
- | Tool | Description |
14
- |------|-------------|
15
- | `get_trade_signal` | Composite BUY/SELL/HOLD signal combining RSI(14), EMA(9/21), funding rate, OI momentum, and volume |
16
- | `scan_funding_arb` | Cross-venue funding rate arbitrage scanner (Hyperliquid vs Binance vs Bybit) |
17
- | `get_market_regime` | Market regime classification with cross-venue funding sentiment |
18
- | `signal-performance` | Historical signal track record — win rate, Sharpe ratio, profit factor |
15
+ ## Try It in 30 Seconds
19
16
 
20
- ## Architecture
17
+ No code. No API key. No install.
21
18
 
22
- ```
23
- Remote Server (revenue-generating)
24
- Agent → HTTP POST → api.algovault.com/signal/mcp
25
- → x402 payment check → API key check → free tier
26
- → MCP Server (Streamable HTTP)
27
- → PostgreSQL (signal tracking)
28
- → Hyperliquid API
19
+ **Step 1.** Open Claude → Settings → Integrations → Add custom connector
29
20
 
30
- Local Mode (distribution magnet)
31
- Claude Desktop → stdio → npx crypto-quant-signal-mcp
32
- → Same tools, free tier only
33
- → SQLite (local signal tracking)
34
- → Hyperliquid API
35
- ```
21
+ **Step 2.** Enter the name and URL:
22
+
23
+ | Field | Value |
24
+ |-------|-------|
25
+ | Name | `Crypto Quant Signal` |
26
+ | URL | `https://api.algovault.com/mcp` |
36
27
 
37
- ## Quick Start
28
+ ![Add Connector](https://raw.githubusercontent.com/AlgoVaultLabs/crypto-quant-signal-mcp/main/docs/screenshots/Add-Connector.png)
38
29
 
39
- ### Remote HTTP (for AI agents)
30
+ **Step 3.** Ask Claude anything:
31
+
32
+ > "Get me a trade signal for BTC"
33
+
34
+ ![BTC Signal Result](https://raw.githubusercontent.com/AlgoVaultLabs/crypto-quant-signal-mcp/main/docs/screenshots/BTC-signal.png)
35
+
36
+ That's it. You now have a crypto quant analyst inside Claude.
37
+
38
+ ---
39
+
40
+ ## What It Does
41
+
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. |
40
47
 
41
- Connect your MCP client to:
48
+ Every signal is tracked. Outcomes are measured at 15m, 1h, 4h, and 24h. The track record ships from day one.
49
+
50
+ ---
51
+
52
+ ## For Developers
53
+
54
+ ### Remote endpoint (recommended)
55
+
56
+ Point any MCP client at:
42
57
  ```
43
- https://api.algovault.com/signal/mcp
58
+ https://api.algovault.com/mcp
44
59
  ```
45
60
 
46
- Pay per call via x402 (USDC on Base) — no signup needed.
61
+ Supports Streamable HTTP transport. Pay per call with x402 (USDC on Base) — no signup needed.
47
62
 
48
- ### Local Install (for Claude Desktop / Cursor)
63
+ ### Local install via npx
49
64
 
50
65
  ```bash
51
66
  npx -y crypto-quant-signal-mcp
52
67
  ```
53
68
 
54
- ### Claude Desktop Config
69
+ ### Claude Desktop / Cursor config
55
70
 
56
- Add to your `claude_desktop_config.json`:
71
+ Add to `claude_desktop_config.json`:
57
72
 
58
73
  ```json
59
74
  {
@@ -61,147 +76,137 @@ Add to your `claude_desktop_config.json`:
61
76
  "crypto-quant-signal": {
62
77
  "command": "npx",
63
78
  "args": ["-y", "crypto-quant-signal-mcp"],
64
- "env": {
65
- "TRANSPORT": "stdio",
66
- "CQS_API_KEY": "your-pro-key-here"
67
- }
79
+ "env": { "TRANSPORT": "stdio" }
68
80
  }
69
81
  }
70
82
  }
71
83
  ```
72
84
 
73
- No API key needed for free tier — just remove the `CQS_API_KEY` line.
74
-
75
- ## Pricing
76
-
77
- | Feature | Free | Pro ($49/mo) | Enterprise ($299/mo) | x402 (pay per call) |
78
- |---------|------|-------------|---------------------|---------------------|
79
- | `get_trade_signal` | BTC + ETH, 1h only | All 200+ perps, all timeframes | Same + SLA | Full access — $0.02/call |
80
- | `scan_funding_arb` | Top 5 results | Unlimited | Unlimited | Full access — $0.01/call |
81
- | `get_market_regime` | All assets | All assets | All assets + SLA | Full access — $0.02/call |
82
- | `signal-performance` | Full access | Full access | Full access | Free |
83
- | Monthly calls | ~100/day | 15,000/mo | 100,000/mo | Unlimited |
84
- | Overage | Hard cap | $0.01/call | $0.005/call | N/A |
85
-
86
- ### x402 Micropayments
85
+ ### npm install
87
86
 
88
- AI agents pay per HTTP call with USDC on Base chain — no signup, no API key, no billing. Payment receipt is the credential.
89
-
90
- ### API Key
87
+ ```bash
88
+ npm install crypto-quant-signal-mcp
89
+ ```
91
90
 
92
- Set `CQS_API_KEY` environment variable or pass `Authorization: Bearer <key>` header. Enterprise keys start with `ent_`.
91
+ ---
93
92
 
94
- ## Example Agent Prompts
93
+ ## Pricing
95
94
 
96
- **Quick signal check:**
97
- > "Get a trade signal for ETH on the 1h timeframe"
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 |
98
103
 
99
- **Funding arb scan:**
100
- > "Scan for funding rate arbitrage opportunities with at least 10 bps spread"
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).
101
105
 
102
- **Market regime with cross-venue sentiment:**
103
- > "What's the current market regime for BTC on the 4h chart?"
106
+ **API key:** Set `CQS_API_KEY` env var or pass `Authorization: Bearer <key>` header.
104
107
 
105
- **Multi-step analysis:**
106
- > "Check the market regime for SOL, then get a trade signal. If it's a BUY, also scan for any funding arb opportunities on SOL."
108
+ ---
107
109
 
108
110
  ## Tools Reference
109
111
 
110
112
  ### get_trade_signal
111
113
 
112
- Returns a composite signal by weighting five indicators:
114
+ Composite signal from five weighted indicators (v3 scoring):
113
115
 
114
- - **RSI(14)** — 25% weight: oversold/overbought detection
115
- - **EMA(9/21) crossover** — 30% weight: trend direction
116
- - **Funding rate** — 20% weight: sentiment from derivatives market
117
- - **OI momentum** — 15% weight: new money confirmation
118
- - **Volume** — 10% weight: conviction multiplier
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.
119
125
 
120
126
  **Parameters:**
121
- - `coin` (string, required): Asset symbol (e.g. "ETH", "BTC", "SOL")
127
+ - `coin` (string, required): e.g. "ETH", "BTC", "SOL"
122
128
  - `timeframe` (string, default "1h"): "1h", "4h", or "1d"
123
- - `includeReasoning` (boolean, default true): Include human-readable explanation
129
+ - `includeReasoning` (boolean, default true): Human-readable explanation
124
130
 
125
131
  ### scan_funding_arb
126
132
 
127
- Scans Hyperliquid's `predictedFundings` endpoint for cross-venue funding rate differences. Normalizes HL hourly rates vs Binance/Bybit 8h rates and annualizes the spread.
133
+ Scans cross-venue funding rate differences. Normalizes HL hourly rates vs Binance/Bybit 8h rates and annualizes the spread.
128
134
 
129
135
  **Parameters:**
130
136
  - `minSpreadBps` (number, default 5): Minimum spread in basis points
131
- - `limit` (number, default 10): Max results to return
137
+ - `limit` (number, default 10): Max results
132
138
 
133
139
  ### get_market_regime
134
140
 
135
- Classifies market conditions using ADX(14), ATR(14)/price volatility ratio, price structure (swing high/low analysis), and cross-venue funding sentiment.
141
+ Classifies market conditions using ADX(14), ATR(14)/price volatility ratio, swing high/low price structure, and cross-venue funding sentiment.
136
142
 
137
143
  **Parameters:**
138
- - `coin` (string, required): Asset symbol
144
+ - `coin` (string, required): e.g. "BTC", "ETH"
139
145
  - `timeframe` (string, default "4h"): "1h", "4h", or "1d"
140
146
 
141
- ## Performance Tracking
142
-
143
- Every signal from `get_trade_signal` is tracked with outcome prices at 1h, 4h, and 24h intervals. Access the track record via the `performance://signal-stats` MCP resource.
147
+ ---
144
148
 
145
- - **Remote mode:** PostgreSQL (server-side, aggregated across all users)
146
- - **Local mode:** SQLite at `~/.crypto-quant-signal/performance.db` (private to your machine)
149
+ ## Performance Tracking
147
150
 
148
- ## Self-Hosting
151
+ Every signal is recorded with outcome prices at **15 minutes, 1 hour, 4 hours, and 24 hours**.
149
152
 
150
- ```bash
151
- git clone https://github.com/AlgoVaultLabs/crypto-quant-signal-mcp
152
- cd crypto-quant-signal-mcp
153
- cp .env.example .env # Edit with your values
154
- npm ci && npm run build
155
- docker compose up -d
156
- ```
153
+ - **Remote mode:** PostgreSQL — aggregated across all users, backfilled every 15 minutes
154
+ - **Local mode:** SQLite at `~/.crypto-quant-signal/performance.db`
157
155
 
158
- ## Technical Details
156
+ Only signals with confidence >= 40 and a BUY or SELL verdict are tracked. HOLD signals are not recorded.
159
157
 
160
- - **Data source:** Hyperliquid public API (free, no auth required)
161
- - **Transports:** Streamable HTTP (default, port 3000) + stdio (via `TRANSPORT=stdio`)
162
- - **Storage:** PostgreSQL (remote) or SQLite (local)
163
- - **Exchange adapter:** Pluggable — Hyperliquid today, Binance/Bybit adapters in Phase 2
164
- - **x402 payments:** USDC on Base chain per x402.org spec
158
+ ---
165
159
 
166
- ## Examples
160
+ ## Architecture
167
161
 
168
- **Get a trade signal:**
169
- ```
170
- User: "Get me a trade signal for BTC on the 1h timeframe"
171
- → Returns: BUY/SELL/HOLD with 72% confidence, RSI=66.7, EMA cross bullish, funding neutral
172
162
  ```
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
173
169
 
174
- **Scan funding arbitrage:**
175
- ```
176
- User: "Scan for funding rate arbitrage opportunities"
177
- → Returns: Top 5 cross-venue spreads (HL vs Binance vs Bybit), annualized returns
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
178
175
  ```
179
176
 
180
- **Check market regime:**
181
- ```
182
- User: "What's the market regime for ETH?"
183
- → Returns: TRENDING_UP, ADX=34.2, volatility moderate, cross-venue funding sentiment
184
- ```
177
+ **Exchange adapter pattern:** code against the `ExchangeAdapter` interface, not raw API calls. Hyperliquid today, more exchanges in Phase 2.
178
+
179
+ ---
185
180
 
186
181
  ## Suite Compatibility
187
182
 
188
- All tools output an `_algovault` metadata block for composability with future AlgoVault tools:
183
+ All tools output an `_algovault` metadata block for composability:
189
184
 
190
- | Tool output | Feeds into (Phase 2+) |
191
- |------------|----------------------|
185
+ | Tool | Feeds into (Phase 2+) |
186
+ |------|----------------------|
192
187
  | `get_trade_signal` | `crypto-quant-risk-mcp`, `crypto-quant-backtest-mcp` |
193
188
  | `scan_funding_arb` | `crypto-quant-risk-mcp`, `crypto-quant-execution-mcp` |
194
189
  | `get_market_regime` | `crypto-quant-risk-mcp`, `crypto-quant-backtest-mcp` |
195
190
 
196
- ## Privacy Policy
191
+ ---
192
+
193
+ ## Self-Hosting
194
+
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
+ ```
202
+
203
+ ---
204
+
205
+ ## Privacy
197
206
 
198
- crypto-quant-signal-mcp connects to Hyperliquid's public API (api.hyperliquid.xyz) to fetch market data. In local/stdio mode:
199
- - No data is sent to AlgoVault Labs servers
200
- - Signal history is stored locally in SQLite (~/.crypto-quant-signal/performance.db)
201
- - No personal information is collected
202
- - No telemetry or analytics in local mode
207
+ **Local mode:** No data sent to AlgoVault servers. Signal history stored locally. No telemetry.
203
208
 
204
- In remote mode (api.algovault.com/mcp), requests are logged for analytics (IP hashed, never stored raw). See https://algovault.com/privacy for full details.
209
+ **Remote mode:** Requests logged for analytics (IP hashed, never stored raw). See [privacy policy](https://algovault.com/privacy).
205
210
 
206
211
  ## License
207
212
 
@@ -209,4 +214,4 @@ MIT
209
214
 
210
215
  ---
211
216
 
212
- Built by [AlgoVault Labs](https://algovault.com)
217
+ Built by [AlgoVault Labs](https://algovault.com) | [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;AA+pBpE,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;AAutBpE,wBAAgB,mBAAmB,cAElC"}