# 🕵️ Market Detective

> **Investigate the move. Find the signal. Trace the evidence.**

Market Detective is a **read-only AI market intelligence agent** that investigates unusual activity across crypto markets and explains what is happening using multiple market signals.

## ✨ Features

### 🔎 Asset Investigation

Enter any supported asset and get a detailed investigation of its current market behavior.

### 🚨 Market Anomaly Detection

Identify assets experiencing unusual activity and rank them using an anomaly score.

### 📊 Multi-Signal Analysis

Market Detective combines:

* 📈 Price movement
* 📊 Trading volume
* 🌪️ Volatility
* ⚖️ Order-book imbalance
* 🔗 Market correlation

to determine whether a move is ordinary or unusual.

### 🧪 Market Autopsy

Investigate a major move and see the evidence behind it, including the sequence of signals that appeared.

### 🕒 Evidence Timeline

Follow how an event developed over time, from the initial signal to the final investigation result.

### 🧠 Explainable Insights

Instead of only displaying charts and numbers, the agent explains **why** an asset was flagged and what signals contributed to the result.

### 🔍 Market Scanner

Scan multiple markets and quickly identify the assets with the strongest abnormal activity.

### 💻 Interactive React Dashboard

A modern React-based interface designed around investigation rather than traditional trading dashboards.

---

## 🔌 Binance Agent OS Integration

Market Detective follows the **Binance Agent OS + MCP architecture pattern**.

It does not require users to provide Binance API keys or connect a wallet.

The MCP-capable host connects to Binance Agent OS:

```text
https://agent.binance.com/mcp/agentic
```

Binance Agent OS provides the market data through its MCP tools, which is then handed to Market Detective for analysis.

```text
Binance Agent OS
        ↓
Binance MCP
        ↓
Market Data
        ↓
Market Detective MCP
        ↓
Forensic Analysis
        ↓
Investigation Results
        ↓
React Dashboard
```

This separation keeps **authentication and data access with the Agent OS host**, while Market Detective focuses on **analysis, anomaly detection, and explanation**.

---

## 🛡️ Read-Only by Design

Market Detective is focused entirely on market intelligence.

✅ Read-only
✅ No wallet connection
✅ No API-key onboarding
✅ No trading or order execution
✅ No transfers
✅ No deposits or withdrawals
✅ No account management

---

## 🛠️ Built With

⚛️ React
⚡ Vite
🟢 Node.js
🔌 MCP
🤖 Binance Agent OS
📊 Market Analytics

---

## 🚀 Getting Started

```bash
npm install
npm test
npm run build
```

Start the backend:

```bash
npm run server
```

Start the frontend:

```bash
npm run dev
```

Then open the local Vite URL in your browser.

---

## 🎯 Vision

Market Detective is built around a simple idea:

> **Don't just watch the market. Investigate it.**