# cryptodata-mcp

Production-ready Model Context Protocol (MCP) server delivering specialized crypto market microstructure, derivatives, order flow CVD/OI regime classification, fear & greed sentiment, and whale tracking context.

Designed specifically to complement charting tools (like TradingView) with real-time data that traditional charts cannot offer.

---

## Features & Tools

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `get_orderflow_and_cvd_context` | `ticker` (required, e.g. "BTC"), `period` ("15m" \| "1h" \| "4h" \| "1d", default "4h") | Evaluates market conditions against the 9-State Order Flow Matrix using live Price, OI, Spot CVD, and Futures CVD deltas. All four legs span the same 10-candle lookback of the requested period. |
| `get_liquidation_and_orderbook_context` | `ticker` (default "BTC"), `depth_percent` (0.1-5, default 1), `slippage_notional_usd` (default 100,000), `book_levels` (20-500, default 500), `liquidation_sample_seconds` (1-15, default 3) | Returns order-book spread, depth imbalance, liquidity walls, simulated market-order slippage, and a bounded live sample of Binance/OKX public liquidation streams. |
| `get_market_intelligence_report` | `ticker` (default "BTC"), `period` (default "4h"), liquidity/liquidation parameters, `record_history` (default true) | Combines order flow, OI, CVD, funding, basis, taker ratio, liquidity, liquidations, sentiment, and sampled whale spot taker flow into a weighted confluence report with coverage, conflict, and risk flags. |
| `get_signal_performance` | `ticker` (default "BTC"), `horizon_hours` (1-720, default 24), `min_abs_score` (default 15), optional checkpoint tolerance | Evaluates stored confluence signals against later local price checkpoints and reports observational win rate and direction-adjusted returns by label and regime. |
| `get_whale_scan_rows` | `scan_id`, `tab` ("transfers" \| "trades" \| "transfers_unknown_age" \| "trades_unknown_age"), `cursor` (default 0), `limit` (1-100, default 25) | Reads a stored Arkham scan in bounded pages. Unknown-age tables contain rows deliberately excluded from finite-timeframe metrics. Repeat until `next_cursor` is `null`. |
| `get_basis` | `pair` (default "BTCUSDT"), `contract_type` ("PERPETUAL" \| "CURRENT_QUARTER" \| "NEXT_QUARTER", default "PERPETUAL") | Returns Futures vs. Spot Basis value, Basis %, and Contango / Backwardation / Parity classification. Annualized basis is reported for dated contracts only (scaled by 365/days-to-expiry); it is undefined for perpetuals. |
| `get_funding_rate` | `ticker` (default "BTC") | Returns the current funding rate %, annualized rate %, next settlement time, and trend direction. The settlement interval is read from the venue (8h, 4h, …) rather than assumed. |
| `get_buy_sell_volume_ratio` | `ticker` (default "BTC"), `period` ("15m" \| "1h" \| "4h" \| "1d", default "4h"), `market_type` ("spot" \| "futures" \| "both", default "both") | Taker Buy/Sell volume in USD, Buy/Sell Ratio (> 1.05 = aggressive buyers, < 0.95 = aggressive sellers), Aggressor Delta, and Bias classification. |
| `get_fear_and_greed_index` | `limit` (1-365, default 7) | Global Crypto Fear & Greed Index score (0-100), classification, and multi-day historical trend. |
| `get_whale_and_exchange_flows` | `ticker` (default "BTC"), `timeframe` (default "24h"), `min_usd_value` (Transfers/exchange, default 1,000,000), `trades_min_usd_value` (Arkham Trades, default 100,000), `max_pages` (1-200, default 50), `max_duration_seconds` (30-900, default 240) | Reuses or opens Arkham Explorer, resets pagination to page 1, and scans **both** Transfers and Trades using their separate thresholds until coverage is complete or a declared safety limit stops it. Also returns the exchange tape. |
| `open_arkham_whale_tracker` | `token` (required), `tab` ("transfers" \| "trades" \| "both", default "transfers"), `timeframe` (default "24h"), `min_usd_value` (Transfers, default 1,000,000), `trades_min_usd_value` (Trades, default 100,000), `max_pages` (1-200, default 50), `max_duration_seconds` (30-900, default 240) | Launches Chrome via CDP and performs the same completeness-aware Arkham scan for the selected table scope. |

### Data-availability contract

No tool substitutes placeholder values. When an upstream venue cannot be reached, the tool returns an explicit `UNAVAILABLE` / `INSUFFICIENT DATA` result naming the failure, rather than a zero or a default that would be indistinguishable from a real reading. Likewise, a failed Arkham scrape is reported as a scrape failure — never as an absence of whale activity.

Liquidation output is explicitly a short live observation window, not a complete historical liquidation total. A zero is reported only when at least one stream connected and emitted no matching event during that stated sample; if no stream connects, the liquidation leg is `UNAVAILABLE`.

### Local signal history

`get_market_intelligence_report` appends compact JSONL snapshots to `data/market-intelligence.jsonl` by default. The file is local, ignored by Git, and can be moved by setting `CRYPTODATA_HISTORY_PATH`. Call `get_signal_performance` later to add a fresh price checkpoint and evaluate matured signals at a configurable forward horizon.

The performance report is observational: it depends on when MCP tools were called, and sparse calls may leave signals pending or produce delayed checkpoints. It is not presented as a backtest over continuous exchange candles.

---

## 📊 Order Flow & CVD Cheatsheet Matrix (9 Market Regimes)

The internal matrix evaluator (`src/utils/matrixEvaluator.js`) classifies live market conditions into one of 9 strategic regimes. CVD is classified as an *imbalance ratio* against total taker volume (±2% standard, ±8% sharp), so the thresholds carry the same meaning for BTC and for a small cap. A component pointing the opposite way to a regime's specification counts against that regime, and when several regimes score equally the result is reported as `AMBIGUOUS` rather than silently resolved.

| Kondisi Pasar (Market State) | Price | Open Interest (OI) | CVD Spot | CVD Futures | Makna Strategis (Strategic Interpretation) |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Healthy Uptrend** | Up | Slow Up | Up | Up | Sinyal Beli Terbaik. Uang asli masuk (Spot) dan posisi Long baru dibuka perlahan. |
| **Short Squeeze** | Up | Down | Flat | Sharp Up | Kenaikan Semu. Harga meroket karena trader Short dipaksa beli (Buy to Cover) untuk tutup posisi. |
| **Blow-off Top** | Up | Sharp Up | Down | Sharp Up | Hati-hati Pucuk. FOMO level akut. Ritel nge-Long agresif, Whale di Spot mulai jualan. |
| **Whale Accumulation** | Flat | Slow Up | Up | Flat/Down | Sinyal Emas. Bandar sedang cicil beli (Spot) tanpa membuat harga heboh. Persiapan pump. |
| **Spot Distribution** | Flat | Up | Down | Up | Jebakan Bullish. Ritel FOMO nge-Long di pucuk, tapi Whale diam-diam buang barang di Spot. |
| **Market Exhaustion** | Flat | Down | Flat | Flat | Konsolidasi / Ragu. Pelaku pasar menutup posisi dan wait and see. Bersiap untuk volatilitas arah baru. |
| **Healthy Downtrend** | Down | Slow Up | Down | Down | Trend Turun Valid. Tekanan jual asli dari Spot, diiringi posisi Short baru yang dibangun bertahap. |
| **Long Liquidation** | Down | Down | Flat | Down | Pembersihan. Trader Long kena likuidasi berantai. Biasanya akan ada rebound cepat setelah bersih. |
| **Panic Selling / Aggressive Shorting** | Down | Up | Down | Sharp Down | Trend Turun Kuat. Investor Spot buang barang dan banyak posisi Short baru dibuka secara agresif. |

---

## 🌐 Arkham Intelligence Whale Tracker Launcher

The server includes an automated browser launcher that opens a dedicated **new window of Google Chrome** navigating directly to Arkham Token Explorer:
- **URL Format:** `https://arkm.com/explorer/token/<token_name>`
- Token slugs are resolved dynamically (`BTC` -> `bitcoin`, `ETH` -> `ethereum`, `SOL` -> `solana`).
- Provides direct tab focus for **Transfers** and **Trades**.

Both `get_whale_and_exchange_flows` and `open_arkham_whale_tracker` drive this browser. They **reuse an already-open `arkm.com` tab** on the debug port when one exists — which is the fast path, and the one that carries your logged-in Arkham session. A browser is launched only when no usable tab is found.

> ⚠️ **A launch opens a visible window** using an isolated profile in your temp directory (not your everyday Chrome profile), so you will need to log into Arkham inside it — raise `wait_for_login_seconds` on that first run. Only a browser this server itself spawned is ever terminated; your own Chrome is left alone.

**Coverage contract:** every requested tab is reset to page 1. The scanner continues until it proves the requested timeframe is covered or reaches Arkham's final page. `max_pages` and `max_duration_seconds` are safety ceilings; if either is reached, the result is explicitly `PARTIAL` and includes each tab's start page, last page, total known pages, native-filter status, and stop reason. A structural parser mismatch is a scrape failure, never evidence of quiet whale activity.

The normal report contains only a small preview so it stays usable in an AI context window. The complete captured arrays are saved locally under `data/whale-scans/` and the report returns a `scan_id`. Call `get_whale_scan_rows` separately for `transfers` and `trades`, following `next_cursor` until `null`. This separates browser scan time from model context size: the scraper can capture hundreds of rows without forcing all of them into one response.

Arkham Trades may show both counterparties of one matched execution. The server pairs mirrored BUY/SELL rows and counts their notional once; SIDE is reported descriptively and is not presented as long/short positioning without aggressor or position semantics. Likewise, sampled Binance spot trades are reported as taker-buy/taker-sell flow, never as deposits or withdrawals. Rows whose timestamps cannot be parsed are excluded from finite-timeframe totals and retained in the `*_unknown_age` cursor tables.

The CDP port defaults to `9224` and can be overridden with the `ARKHAM_CDP_PORT` environment variable.

---

## 🛠️ Installation & Setup

### 1. Install

This is plain CommonJS JavaScript — there is no build step.

```bash
npm install
```

### 2. Register in Cursor (`.cursor/mcp.json` or `.vscode/mcp.json`)

Add to your `mcp.json`:

```json
{
  "mcpServers": {
    "cryptodata-mcp": {
      "command": "node",
      "args": [
        "D:/coding/trading/cryptodata-mcp/src/index.js"
      ]
    }
  }
}
```

### 3. Register in Claude Desktop (`claude_desktop_config.json`)

On Windows, locate `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cryptodata-mcp": {
      "command": "node",
      "args": [
        "D:/coding/trading/cryptodata-mcp/src/index.js"
      ]
    }
  }
}
```

---

## 🧪 Testing Locally

You can run the server directly via node:

```bash
npm start
```

Or connect using the official `@modelcontextprotocol/inspector`:

```bash
npx @modelcontextprotocol/inspector node src/index.js
```

Run the deterministic unit tests with:

```bash
npm test
```