# Binance MCP + ChainVector

One MCP server that pairs **Binance execution** with **ChainVector market intelligence**. Connect it to any MCP client (Claude Desktop, Cursor, Windsurf, ...) and the agent can read live signals, regime classification, probabilities and risk gauges from ChainVector, pick a strategy template, and execute the resulting decision on Binance — with intelligence and execution kept cleanly separated.

- **Execution (Binance)**: the full Binance MCP tool surface — spot trading, TWAP/VP algo orders, convert, wallet, simple earn, staking, copy trading and more.
- **Intelligence (ChainVector)**: 32 signal tools covering momentum, regime, risk index, probability engine, order flow, whale pressure, funding, liquidations, prediction markets and options context.
- **Strategy templates**: 7 selectable advisor tools that fuse ChainVector signals into structured trade decisions (`long` / `short` / `flat`, EV score, vetoes, size multiplier, stop/target).

Strategy advisors **never place orders**. They return a decision; placing the trade is always a separate, explicit Binance tool call.

## Strategy templates

Ask your agent to run `chainvectorStrategyList`, or call a template directly:

| Template | Tool | Setup it trades | Best regime |
| --- | --- | --- | --- |
| `advise` | `chainvectorStrategyAdvise` | Full ensemble: regime gate + EV weighting + veto stack | any (recommends the specialist template) |
| `momentum` | `chainvectorStrategyMomentum` | Momentum continuation with breadth + book alignment | trending |
| `meanrev` | `chainvectorStrategyMeanRevert` | RSI / Bollinger extreme back toward the mean | choppy / quiet |
| `squeeze` | `chainvectorStrategySqueeze` | Crowded funding side unwinding | squeeze_setup |
| `cascade-fade` | `chainvectorStrategyCascadeFade` | Fade an exhausting liquidation cascade | cascading (exhaustion) |
| `carry` | `chainvectorStrategyCarry` | Delta-neutral funding-carry venue pairs | quiet / any |
| `probability-target` | `chainvectorStrategyProbabilityTarget` | Quantified TP/SL plan: P(target before stop), expectancy in R | any (position planning) |

Every decision includes the underlying signals, active **vetoes** (risk index extreme, cascade against direction, crowded squeeze against direction, cascading regime, no-momentum quiet regime) and **warnings** (venue dispersion, weak breadth, counter-trend). Treat `action: "flat"` or any veto as a hard no-trade.

Example prompts once connected:

- *"Run the strategy list and tell me which template fits the current BTC regime."*
- *"Run chainvectorStrategyAdvise on BTCUSDT with a 60 minute horizon. If it says long with no vetoes, buy $100 of BTC at market."*
- *"Plan a long on ETHUSDT with take profit 2%, stop 1%: use the probability-target template and only proceed if expectancy is positive."*

## ChainVector signal tools

**Core signals** — `chainvectorSignalsSnapshot` (one-call decision snapshot), `chainvectorMomentum` (cross-venue scorecard, EV weight or veto), `chainvectorLeadLag`, `chainvectorRegime` (trending / choppy / quiet / squeeze_setup / cascading), `chainvectorRiskIndex` (0-100 stress circuit breaker), `chainvectorSignalsHistory`, `chainvectorVolatility` (vol battery + expected move), `chainvectorIndicators` (RSI/EMA/MACD/ATR/Bollinger), `chainvectorProbability` (six-estimator ensemble: terminal / touch / range, 30s-24h horizons, strike ladders).

**Order flow & microstructure** — `chainvectorOrderflowCvd`, `chainvectorLongShort`, `chainvectorWhalePressure`, `chainvectorOrderbookImbalance`, `chainvectorOrderbookWalls`, `chainvectorPositioning`.

**Derivatives context** — `chainvectorFundingCurrent`, `chainvectorFundingWeighted`, `chainvectorFundingArbitrage`, `chainvectorFundingSqueeze`, `chainvectorBasis`, `chainvectorOpenInterest`, `chainvectorLiquidations`, `chainvectorCascadeRisk`, `chainvectorLiquidationHeatmap`.

**Prediction markets & options** — `chainvectorPredictionsMarkets` / `Quotes` / `Trades` / `Results` / `Stability` (bid-price stability score) / `Edge` (model vs market repricing), `chainvectorOptionsMaxPain`, `chainvectorOptionsImpliedProbability`.

## Requirements

- Node.js v18 or later (native `fetch` is used for ChainVector)
- A Binance API key + secret ([create one](https://www.binance.com/en/my/settings/api-management) — see `readme/` for step-by-step screenshots)
- A ChainVector API key ([chainvector.com](https://chainvector.com) — keys look like `cv_live_...`)

## Installation

```sh
git clone https://github.com/C0inFlips/binance-mcp-chainvector.git
cd binance-mcp-chainvector
npm install
npm run build
```

Optional interactive setup (writes `.env` and offers Claude Desktop configuration):

```sh
npm run init
```

## Configuration

Create a `.env` file (or copy `.env.example`):

```sh
BINANCE_API_KEY=YOUR_BINANCE_API_KEY
BINANCE_API_SECRET=YOUR_BINANCE_API_SECRET
CHAINVECTOR_API_KEY=cv_live_YOUR_CHAINVECTOR_KEY
```

### MCP client config (Claude Desktop / Cursor / Windsurf)

Claude Desktop config lives at:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
    "mcpServers": {
        "binance-mcp-chainvector": {
            "command": "node",
            "args": [
                "/absolute/path/to/binance-mcp-chainvector/build/index.js"
            ],
            "env": {
                "BINANCE_API_KEY": "YOUR_BINANCE_API_KEY",
                "BINANCE_API_SECRET": "YOUR_BINANCE_API_SECRET",
                "CHAINVECTOR_API_KEY": "cv_live_YOUR_CHAINVECTOR_KEY"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}
```

Restart the client after editing. The same block works in `.cursor/mcp.json` for Cursor.

## How the strategy loop works

1. **Choose** — `chainvectorStrategyList`, or run `chainvectorStrategyAdvise` and follow its `regime.recommended_strategy`.
2. **Decide** — run the template tool for your symbol. It fetches the ChainVector signals it needs and returns a structured decision.
3. **Gate** — only act when `action != "flat"` and `vetoes` / `blockers` are empty. Scale position size by `size_multiplier`.
4. **Execute** — place the order with the Binance tools (`BinanceNewOrder` for spot market/limit orders, or the TWAP/VP algo tools for large orders), using `suggested.stop_pct` / `suggested.take_profit_pct` for exits.
5. **Repeat** — decisions are point-in-time reads, not standing orders. Re-run the template before every new entry.

## Rate limits & reliability

- ChainVector tool calls are cached for a few seconds server-side in this process, so repeated reads within one agent turn reuse the same sample.
- On a 429 the client backs off automatically (honoring `Retry-After`) and reports the cooldown in the tool error.
- Strategy advisors make several ChainVector calls per invocation — don't poll them in a tight loop.

## Disclaimer

Model outputs surfaced through these tools (probability, regime, heatmap estimates) are informational only and not investment advice. Trading cryptocurrencies involves substantial risk. Never commit real API keys to a repository; use environment variables or your MCP client's `env` block.

## License

This project is open-source under the MIT License.