# BitCLI
> Ultra-fast High-Frequency Trading (HFT) crypto alerts and order flow analytics engine.

## Overview
BitCLI is an institutional-grade C++ execution engine connected directly to raw Layer-2 WebSockets across Binance Futures, Bybit Linear, and Hyperliquid.
Instead of polling slow 1-minute candle closes, BitCLI evaluates order flow events, volume spikes, Cumulative Volume Delta (CVD), Open Interest (OI) changes, and liquidation cascades in memory (under 500 nanoseconds latency).

## Ecosystem Interfaces
- Telegram CLI Bot: https://t.me/bitclibot
- Documentation: https://docs.bitcli.io
- GitHub Organization: https://github.com/BitCLI-io
- API & IPN Gateway: https://api.bitcli.io
- Webhook Relay: https://wh.bitcli.io
- User Dashboard: https://my.bitcli.io (Upcoming)
- MCP Server: https://mcp.bitcli.io (Q4 2026)

## 1. Core Analytics & Radars
BitCLI aggregates data across multiple exchanges to provide true market intelligence:
- **RVOL (Relative Volume):** Measures current volume bursts against the 20-period Simple Moving Average (SMA). e.g., RVOL 4.0x means 400% of normal activity.
- **CVD (Cumulative Volume Delta):** Tracks the net difference between aggressive market buyers (ask hitters) and sellers (bid hitters).
- **Z-Score Liquidations:** Detects statistical anomalies in forced liquidations (e.g., a Z-Score of >3σ indicates a severe liquidation cascade).
- **Funding Rates:** All rates are mathematically normalized to an 8-hour basis across all exchanges for unified evaluation.
- **Top Radars:** Whale volume bursts, Short/Long Squeezes (Extreme Funding + OI growth), Volatility (nATR), and Funding Heatmaps.

## 2. Telegram CLI Alert Syntax
Users can type plain commands directly into the Telegram bot.
- **Exact Price:** `<coin> <price>` (e.g., `btc 95000`)
- **Corridor Breakout:** `<coin> <min>-<max>` (e.g., `btc 64k-95k`)
- **Key Levels:** `<coin> ath` (All-Time High), `<coin> pdl` (Previous Day Low)
- **Velocity (Pumps/Dumps):** `<coin> <pct>% <tf>` (e.g., `sol +3.5% 5m`)
- **Whale Volume Spikes:** `<coin|*> vol <tf> x<multiplier>` (e.g., `* vol 15m x4` - global scan)
- **Liquidations:** `<coin|*> liq <usd_amount>` (e.g., `btc liq 500k`) or `* liq z3`
- **CVD Divergence:** `<coin> cvd div <tf>` (e.g., `eth cvd div 15m`)
- **Funding Rate Extreme:** `<coin|*> fr <direction> <pct>%` (e.g., `* fr > 0.1%`)

## 3. Quantitative Risk Calculators
Traders can run these commands in Telegram for instant risk math:
- `/pos <coin> <entry> <sl> <risk_usd>`: Calculates position size (lot) based on fixed dollar risk and exchange fees.
- `/liq <coin> <entry> <leverage> [long|short]`: Calculates TRUE bankruptcy price factoring in Maintenance Margin Rate (MMR).
- `/dca <coin> price:qty price:qty ... [short]`: Calculates average entry and true break-even price including exit taker fees.
- `/rr <coin> <entry> <sl> <tp1> [tp2] [tp3]`: Multi-target Risk/Reward planner.
- `/fncost <coin> <position_usd> [long|short] [rate%]`: Estimates carry costs for holding a position across 8h/24h/7d.
- `/atr <coin> [tf] [multiplier]`: Generates dynamic Stop-Loss/Take-Profit distances based on Average True Range.

## 4. TradingView Webhook Gateway
BitCLI provides a hosted cloud relay for routing TradingView Pine Script alerts to Telegram channels or groups in <15ms.
- **Endpoint:** `https://wh.bitcli.io/v1/{SECRET_UUID}`
- **Method:** HTTP POST
- **Supported Payload Format (JSON):**
  ```json
  {
    "coin": "{{ticker}}",
    "action": "BUY",
    "price": {{close}},
    "comment": "RSI Oversold"
  }
  ```
- **Custom HTML Templates:** Supported via the `"message"` key using Jinja2 syntax.

## 5. Model Context Protocol (MCP) - Roadmap
The upcoming MCP server (`mcp.bitcli.io`) will expose the following tools to autonomous AI agents (Cursor, Claude Desktop, AutoGPT):
- `get_market_intel(coin: string)`: Returns aggregated metrics (OI, Funding, CVD, RVOL).
- `get_top_radars(category: string)`: Categories include 'whales', 'squeeze', 'heat', 'volatility'.
- `calculate_position_size(entry: float, sl: float, risk: float)`
- `create_hft_alert(command_string: string)`: Programs the C++ core to monitor specific anomalies.