# BitCLI Full Documentation > This file contains the complete concatenated documentation for AI agents. ================================================================= FILE: index.md ================================================================= # ⚡️ BitCLI System Overview BitCLI is an institutional-grade, low-latency execution engine connected directly to Layer-2 WebSockets across **Binance Futures**, **Bybit Linear**, and **Hyperliquid**. Instead of polling slow REST endpoints or waiting for 1-minute candle closes, BitCLI processes order flow, liquidation cascades, Cumulative Volume Delta (CVD), and Open Interest (OI) in RAM with **sub-500 nanosecond** internal latency. --- ## Dual Interface Architecture BitCLI operates on a unified core with two dedicated presentation channels: ``` ┌─────────────────────────────────────────┐ │ BitCLI C++ Memory Core │ │ (Binance · Bybit · Hyperliquid L2 WS) │ └────────────────────┬────────────────────┘ │ ┌──────────────────────┴──────────────────────┐ ▼ ▼ ┌────────────────────────┐ ┌────────────────────────┐ │ Traders & Humans │ │ AI Agents & Devs │ ├────────────────────────┤ ├────────────────────────┤ │ • Telegram CLI & SPA │ │ • MCP Server (HTTP/SSE)│ │ • Discord Webhook Hub │ │ • Python SDK (WS M2M) │ │ • TradingView Relays │ │ • BCT Token Standard │ └────────────────────────┘ └────────────────────────┘ ``` ### 1. For Traders (Telegram & Discord) * **Command Line Terminal:** No clunky menus. Simply type commands like `btc 95k`, `sol 3% 5m`, or `/pos btc 65k 50` directly into [@bitclibot](https://t.me/bitclibot). * **AI Copilot:** Talk in plain natural language (e.g., *"alert me if solana pumps 3% in 5 minutes"*). The built-in assistant auto-translates your intent into active C++ triggers. * **Unified Webhook Hub:** Route TradingView Pine Script alerts to private chats, channels, or Discord servers in <15ms. ### 2. For AI Agents (Model Context Protocol & SDK) * **Token Optimization (BCT-30):** Traditional exchange REST APIs burn thousands of LLM inference tokens on bloated JSON arrays. BitCLI computes microstructure indicators server-side and returns dense BCT matrices, saving **up to 70%** on LLM costs. * **Asynchronous Execution:** AI agents (Cursor, Claude, AutoGPT) set triggers via the `alert_manager` tool and sleep. When market conditions hit, BitCLI pushes notifications to the human's Telegram or Discord without expensive polling loops. * **Direct Notifications:** Agents can proactively message their human users using the `send_notification` tool. --- ## Supported Venues & Instruments BitCLI continuously ingests tick-by-tick L2 data for **1,650+ perpetual contracts**: | Exchange | Contract Category | Normalized Metrics | | :--- | :--- | :--- | | **Bybit** | Linear Perpetual (USDT / USDC) | 8h Normalized Funding, Tick-by-tick CVD | | **Binance** | USDⓈ-M Perpetuals | 8h Normalized Funding, AggTrades, ForceOrders | | **Hyperliquid** | DEX Perpetuals | Native EVM funding, liquidation streams | | **Aggregated (`agg`)** | Cross-exchange consolidated | Volume-summed OI, median price, peak RVOL | --- ## Quick Navigation * ⌨️ **[CLI Alert Syntax](/syntax)** — Full command dictionary for price, velocity, and whale radars. * 🧠 **[Market Intel & Screener](/market_intel)** — Scan 1,650+ perps in <1.5s via `/scan`. * 🧮 **[Risk Calculators](/calculators)** — Position sizing (`/pos`), True MMR liquidations (`/liq`), and DCA break-even (`/dca`). * 🤖 **[MCP Server Guide](/mcp)** — Connect Cursor or Claude Desktop to the engine. * 💳 **[Tariffs & Quotas](/tariffs)** — Pricing, daily limits, and unified USD balances. ================================================================= FILE: syntax.md ================================================================= # Unified CLI Command Syntax BitCLI uses an identical command-line syntax across all interfaces. Whether you type a message directly into the Telegram bot or an AI agent passes a string into the MCP `alert_manager(command=...)` tool, the C++ engine parses and executes it identically. > 💡 **Default Exchange Context:** Alerts default to **Bybit Linear**. To target another venue, prefix the command with `binance`, `bybit`, or `hl` (Hyperliquid). You can change your personal default exchange via `/settings`. --- ## 1. Price Targets & Corridors Set absolute price levels, exit channels, or percentage deviations evaluated tick-by-tick. | Syntax | Example | Description | | :--- | :--- | :--- | | ` ` | `btc 95k` | Triggers when BTC reaches $95,000 (auto-detects UP/DOWN direction). | | `[exchange] ` | `binance eth 3150` | Explicitly targets Binance USDⓈ-M Futures. | | ` -` | `btc 64k-95k` | **Corridor Exit:** Alerts when price leaves this channel in either direction. | | ` +%` | `sol +3.5%` | Triggers only if SOL pumps 3.5% from current market price. | | ` -%` | `eth -5%` | Triggers only if ETH dumps 5% from current market price. | | ` %` | `btc 2%` | **Bidirectional Corridor:** Alerts if price deviates ±2%. | *Note: Suffixes `k` (thousand) and `m` (million) are supported everywhere (e.g. `95.5k`, `1.2m`).* --- ## 2. Velocity (Rapid Pumps & Dumps) Detect sudden price momentum before the candle closes. The engine evaluates rolling price changes in RAM tick-by-tick. **Syntax:** `[exchange] [+-]% ` * `btc 3% 5m` — Alert if BTC jumps ±3% within any rolling 5-minute window. * `sol +2.5% 1m` — Fast pump alert: triggers only on upward moves > 2.5% within 1 minute. * `* -5% 15m` — **Global Radar:** Scans **all 1,650+ contracts** simultaneously across the exchange and alerts if any coin dumps 5% in 15 minutes. --- ## 3. Whale Volume Spikes (RVOL) Volume spikes compare the volume of the currently forming candle block against the 20-period Simple Moving Average (SMA20) of historical closed blocks. **Syntax:** `[exchange] vol x` * `sol vol 5m x3` — Triggers when SOL 5m volume exceeds 3x its 20-period baseline. * `* vol 15m x4` — Scans the whole exchange for anomalous institutional volume bursts (4.0x SMA20). --- ## 4. Forced Liquidations & Cascade Anomalies Monitor forced position liquidations and statistical clustering in real time. * `btc liq 500k` — Single forced liquidation event exceeding $500,000 USD on BTC. * `* liq 1m` — Global scan for liquidation events exceeding $1,000,000 USD on any contract. * `* liq z3` — **Liquidation Cascade Anomaly:** Triggers when liquidation volume exceeds 3 standard deviations (Z-Score > 3.0σ) from historical baseline. --- ## 5. Order Flow (Cumulative Volume Delta) Cumulative Volume Delta (CVD) measures the net imbalance between aggressive market buyers (ask hitters) and aggressive market sellers (bid hitters). * `btc cvd div 15m` — **CVD Divergence:** Detects exhaustion setups where price makes a new high/low while CVD initiative diverges. * `sol cvd abs 5m` — **Delta Absorption:** Catches passive institutional limit walls (icebergs) absorbing aggressive taker flow. --- ## 6. Open Interest & Funding Rates Normalized 8-hour funding rates and leverage accumulation tracking. * `* oi +5% 15m` — Sudden 5% surge in open interest in 15 minutes (leverage buildup). * `sol oi -10% 1h` — Mass position flush / liquidations. * `* fr > 0.1%` — Alerts when longs are heavily overcrowded (paying >0.1% per 8h funding). * `sol fr < -0.05%` — Alerts when short sellers are aggressively paying longs to hold positions. --- ## 7. Historical & Daily Key Levels * `btc ath` — Alerts when Bitcoin breaks its global All-Time High. * `sol atl` — Alerts when Solana breaks its All-Time Low. * `eth pdh` — Breakout above Yesterday's High (Previous Day High). * `eth pdl` — Breakdown below Yesterday's Low (Previous Day Low). --- ## 8. Cooldown Modifier (`cd=`) Prevent alert spam during choppy or high-volatility conditions by appending a cooldown period: * `* vol 5m x3 cd=30m` — Trigger once, then mute volume alerts for 30 minutes. * `btc 3% 5m cd=1h` — Mute velocity alerts on BTC for 1 hour after first trigger. ================================================================= FILE: market_intel.md ================================================================= # 🧠 Market Intel & Universal Screener BitCLI operates as a real-time high-frequency data aggregator. Instead of switching between multiple exchange tabs, you can scan and pull institutional metrics across **1,650+ perpetual contracts** simultaneously. Metrics are consolidated across **Binance**, **Bybit**, and **Hyperliquid**. --- ## 1. Universal Market Screener (`/scan` or `/screen`) The Universal Screener evaluates continuous streaming data in RAM and returns filtered, ranked assets across perpetual contracts in less than **1.5 seconds**. **Syntax:** `/scan [exchange] [filters...] [sort:field_(asc|desc)] [limit]` --- ### A. Exchange Scope & Cross-Exchange Aggregation (`agg`) By default, BitCLI runs in **Consolidated Aggregation Mode (`agg`)**. It evaluates liquidity across all supported major perpetual venues simultaneously. * **Default (`agg`):** Consolidated view across **Binance Futures**, **Bybit Linear**, and **Hyperliquid**. * **Single Venue:** Filter by a specific exchange by including its tag anywhere in your query: * `binance` — Binance USDⓈ-M Perpetuals * `bybit` — Bybit Linear Perpetuals * `hl` — Hyperliquid DEX Perpetuals #### How Metrics Are Aggregated in `agg` Mode: * 💰 **Volume & Open Interest:** **Mathematically Summed ($\sum$)** across supported exchanges to reflect true liquidity weight. * 📍 **Price:** **Median Price**. Protects against isolated scam-wicks or exchange-specific outages. * 💸 **Funding Rate & RSI:** **Capital-Weighted (OI-Weighted)**. The exchange with the largest open interest dictates the indicator value. * ⚡️ **Relative Volume (RVOL):** **Maximum Peak ($\max$)**. An institutional volume burst on one venue is preserved and not diluted. --- ### B. Supported Metrics & Parameters | Filter Key | Metric | Unit / Format | Description | | :--- | :--- | :--- | :--- | | `vol` or `v24` | Rolling 24h Volume | USD (`k`, `m`, `b`) | Total turnover over the last 24 hours. Does not reset at 00:00 UTC. | | `oi` | Open Interest | USD (`k`, `m`, `b`) | Total active leveraged capital outstanding. | | `oichg` | 24h OI Delta | Percentage (`%`) | 24-hour rate of change in Open Interest. | | `rvol` | Relative Volume | Multiplier (`float`) | Ratio of current 1-hour volume to the 20-period moving average (SMA20). | | `fund` or `fr` | Funding Rate | Percentage (`%`) | Normalized **8-hour standard basis** across all exchanges. | | `rsi` | Relative Strength | Bounded [0–100] | 15-minute timeframe RSI-14. | | `bias` | Trend Deviation | Percentage (`%`) | Price deviation from the 1-hour 20-period EMA (`(Price/EMA20 - 1) * 100`). | | `natr` | Volatility (nATR) | Percentage (`%`) | 1-hour Normalized ATR (`ATR14 / Price * 100`). | | `cvd` | Rolling 60m Delta | Net USD (`k`, `m`) | Net taker buyer/seller volume over the rolling last 60 minutes. | **Operators:** `>`, `<`, `>=`, `<=`, `=`, `!=` **Units:** `k` (thousands), `m` (millions), `b` (billions), `%` (percent). --- ### C. How Sorting Works (`sort:field_direction`) You can rank your scan results by any metric to float the most critical setups to the top. * **Default Ranking:** If you omit the sort parameter, the screener automatically sorts by **RVOL Descending (`sort:rvol_desc`)** to highlight the biggest volume anomalies first. * **Directions Explained:** * **`_desc` (Descending / Highest First):** Finds **market maximums**. *Example:* `sort:vol_desc` (highest turnover), `sort:fund_desc` (highest positive funding), `sort:oichg_desc` (fastest leverage accumulation). * **`_asc` (Ascending / Lowest First):** Finds **market minimums**. *Example:* `sort:rsi_asc` (deepest oversold RSI dips), `sort:fund_asc` (deepest negative funding). * **Shorthand:** Omitting the direction automatically defaults to `_desc` (e.g., `sort:vol` is identical to `sort:vol_desc`). --- ### D. Smart Anti-Dust Protection (Default Scan) When running a bare `/scan` without explicit constraints, the engine protects you from illiquid garbage contracts: 1. Enforces `vol_24h >= $1,000,000` USD turnover. 2. Enforces `oi >= $500,000` USD active open interest. 3. Automatically excludes stablecoins (`USDC`, `USD1`, `FDUSD`, `EUR`). > Only liquid, actively traded contracts with institutional participation are returned. ### E. Battle-Tested Trading Presets Copy and paste these commands directly into the Telegram chat: * 🐋 **Whale Momentum Bursts (High RVOL on heavy volume):** `/scan rvol>2.5 vol>5m sort:rvol_desc` * 🗜 **Short Squeeze Trap (Positive funding with aggressive OI buildup):** `/scan fund>0.08 oichg>5 vol>3m sort:fund_desc` * 🩸 **Long Squeeze Cascade (Deep negative funding, longs underwater):** `/scan fund<-0.05 oichg>5 sort:fund_asc` * 📉 **Oversold Mean-Reversion Dip (RSI in floor + surge in volume):** `/scan rsi<30 rvol>2 vol>5m sort:rsi_asc` * 🌋 **High-Beta Altcoin Scalping (Top volatility with positive delta):** `/scan natr>4 cvd>0 vol>10m sort:natr_desc 15` * 🟣 **Hyperliquid Exclusive Gems (Scan Hyperliquid perps only):** `/scan hl oichg>10 vol>1m sort:oichg_desc` --- ### F. Viral Community Sharing (Inline Mode) Share live scan setups into any crypto group or direct message without typing: 1. Type `@YourBot` (e.g., `@bitclibot `) in any Telegram chat. 2. If query is blank, your **last 10 successful calculations, screener queries, and setups** appear in a tap-to-send snippet menu. 3. To share a live custom scan, type: `@YourBot scan rvol>2 fund<0` 4. The generated card calculates live data on-the-fly and includes your permanent partner referral button. --- ## 2. Deep Dive Asset Intel (`/intel` or `/i`) **Syntax:** `/i ` (e.g., `/i BTC` or `/i SOL`) Generates a unified cross-exchange diagnostic snapshot: * **Consolidated Price & Total OI:** Combines Open Interest across Binance, Bybit, and Hyperliquid. * **OI-Weighted Funding Rate:** Mathematically weights funding by capital distribution to expose true market carry cost. * **RVOL (Relative Volume):** Highlights whether institutional activity is active over the 20-period baseline. * **Rolling CVD Slope:** Tracks aggressive market order aggression versus passive limit absorption. --- ## 3. Quant TA Consensus (`/ta`) **Syntax:** `/ta ` An emotionless quantitative gauge scoring an asset from **Strong Short** (-100) to **Strong Long** (+100) based on: 1. **Trend Bias:** Deviation from 1h EMA20. 2. **Momentum:** 15m RSI-14 levels. 3. **Volatility:** 1h Normalized ATR (nATR). 4. **Order Flow:** 1h CVD Delta and regression slope. --- ## 4. Whale Radar (`/whales` or `/whl`) **Syntax:** `/whales` Scans all active contracts and returns the **Top 10 assets experiencing anomalous volume spikes right now**. Sorted strictly by Relative Volume (`RVOL`). An RVOL of `3.5x` indicates the asset is currently trading 350% of its normal 20-period baseline. --- ## 5. Squeeze Radar (`/squeeze` or `/sqz`) **Syntax:** `/squeeze` Identifies heavily leveraged assets vulnerable to cascading forced closes: $$\text{Squeeze Score} = |\text{Funding}| \times \max(0, \Delta \text{OI}_{24h}) \times \max(1, \text{RVOL})$$ * **Short Squeeze:** Extreme positive funding + rising OI = short sellers trapped. * **Long Squeeze:** Negative funding + rising OI = long buyers bleeding carry fees. --- ## 6. Funding Heatmap (`/heat` or `/ht`) **Syntax:** `/heat` Displays the most extreme funding rates across perpetual markets. Use it to locate: * Market sentiment extremes (euphoria vs panic). * **Cash-and-Carry Arbitrage (Delta Neutral):** Shorting high-funding perps while holding spot captures market-neutral annualized yields (**APR > 100%**). --- ## 7. Volatility Radar (`/volatility` or `/natr`) **Syntax:** `/natr [1m|5m|15m|1h|4h|1d]` Ranks assets by **Normalized ATR (nATR)**: $$\text{nATR} = \frac{\text{ATR}_{14}}{\text{Price}} \times 100\%$$ Identifies the highest percentage movers for active scalpers and day traders. ================================================================= FILE: indicators.md ================================================================= # Order Flow & Quantitative Indicators BitCLI calculates institutional-grade metrics in RAM using lock-free data structures, providing data that usually requires expensive desktop terminals. --- ## 1. Cumulative Volume Delta (CVD) Cumulative Volume Delta tracks the net imbalance between aggressive market buyers (hitting the ask) and aggressive market sellers (hitting the bid). ### A. CVD Divergence (`cvd div`) Detects exhaustion setups where price makes a new high/low while market participant initiative fades. * `btc cvd div 15m` * `* cvd div 5m` * **Bearish Divergence:** Price prints a Higher High (HH), but CVD slopes downward (Lower High) ➔ Aggressive buyers are exhausted. * **Bullish Divergence:** Price prints a Lower Low (LL), but CVD slopes upward ➔ Aggressive sellers are vanishing. ### B. Delta Absorption (`cvd abs`) Catches passive institutional iceberg walls absorbing aggressive market orders. * `sol cvd abs 5m` > **Mathematical Engine:** BitCLI measures the **Price Compression Ratio (PCR)**: > `PCR = (Candle Range / ATR₁₄) ≤ 0.3` > A tight candle combined with massive volume delta signals a passive iceberg limit order absorbing the market flow. --- ## 2. Liquidation Cascades & Z-Scores Forced liquidations fuel sharp momentum bursts. BitCLI tracks individual liquidations and statistical anomaly clusters. ### A. Absolute Liquidation Size * `btc liq 500k` — Single forced liquidation event exceeding $500,000 USD. * `* liq 1m` — Global scan for liquidation events exceeding $1,000,000 USD on any contract. ### B. Liquidation Cascade Z-Score (`liq z`) Tracks statistical anomalies in liquidation clustering using streaming exponential variance: > **Z-Score Formula:** `Z = (Vol_liq - EMA_liq) / σ_liq` * `* liq z3` — Triggers when liquidation volume exceeds 3 standard deviations (3σ) from baseline (extreme liquidation cascade / squeeze). --- ## 3. Open Interest (OI) & Funding Rates ### A. Open Interest Shifts Open Interest measures total outstanding contracts. Rapid shifts reveal new leverage entering or exiting. * `* oi +5% 15m` — Sudden 5% surge in open leverage in 15m (potential squeeze setup). * `sol oi -10% 1h` — Leverage flush / mass position closures. ### B. Normalized 8-Hour Funding Rates BitCLI normalizes all funding rates across Binance, Bybit, and Hyperliquid to an **8-hour standard** for uniform cross-exchange evaluation. * `* fr > 0.1%` — Alerts when longs are heavily overcrowded (paying >0.1% per 8h). * `sol fr < -0.05%` — Alerts when aggressive shorts are paying heavy funding to longs. --- ## 4. Classic Technical Indicators Calculated tick-by-tick with $O(1)$ rolling memory caches: * **RSI Level:** `btc rsi 15m < 30` (Oversold condition on 15m chart). * **Price / EMA Cross:** `eth ema 1h > 3200` (Price crosses above 1-hour 20-period EMA). ================================================================= FILE: calculators.md ================================================================= # Professional Risk Calculators Never guess your position size or stop-loss distance. Run these commands directly in Telegram for instant calculations. --- ## 1. Volatility Stops (ATR Calculator) (`/atr`) Professional traders do not use fixed percentages (like a 2% stop-loss) because a 2% move on Bitcoin is huge, while a 2% move on a memecoin is just background noise. They use **ATR (Average True Range)** to place stops outside the normal volatility zone. **Syntax:** `/atr [timeframe] [multiplier]` ### Examples: * `/atr BTC 1h 2` — Calculates the 1h ATR for Bitcoin and multiplies it by 2.0x to give you a safe Stop-Loss and Take-Profit distance. * `/atr SOL 15m 1.5` — For shorter-term scalping. > **Output Includes:** Exact distances in USD and percentages, plus calculated Long/Short execution prices rounded perfectly to the exchange's tick size. --- ## 2. Position Size Calculator (`/pos`) Calculates exact lot size based on your dollar risk, Stop-Loss distance, and exchange round-trip taker fees (~0.11%). **Syntax:** `/pos [entry] [leverage]` ### Examples: * `/pos btc 65k 63.7k 50` — Limit entry at $65k, SL at $63.7k, max allowed loss $50. * `/pos eth 3400 50` — Entry price omitted? BitCLI fetches the **live market price** automatically. * `/pos sol 140 135 2% 20x` — Risk 2% of a standard $1,000 equity base. > **Output Includes:** Exact coin quantity, notional position value, required margin for 10x / 20x / 50x leverage, and an interactive **"Set SL Alert"** button. --- ## 3. True Liquidation Engine (`/liq`) TradingView formulas ignore Maintenance Margin Rates (MMR). BitCLI calculates the **true exchange bankruptcy price** including maintenance margin requirements and clearance penalties. **Syntax:** `/liq [entry] [long/short]` ### Examples: * `/liq btc 65k 50x long` * `/liq sol 20x short` *(uses current live price)* > Generates an automatic **"Alert 1% before Liquidation"** quick-button. --- ## 4. True Break-Even DCA Calculator (`/dca`) Closing an averaged position at average entry results in a loss due to exchange fees. BitCLI calculates the **true break-even price**, factoring in exit fees. **Syntax:** `/dca price:qty price:qty ... [short]` ### Examples: * `/dca btc 65k:100 62k:200 59k:300` — Bought $100 at 65k, $200 at 62k, $300 at 59k. * `/dca sol 150:50 160:100 short` — Short grid break-even. --- ## 5. Multi-Target Risk/Reward (`/rr`) Plans multi-target scaling setups assuming standard institutional execution (50% size at TP1, 30% at TP2, 20% at TP3). **Syntax:** `/rr [tp2] [tp3]` * `/rr btc 65k 64k 67k 69k` > Calculates Effective Risk:Reward ratio, gives a setup verdict, and renders individual alert buttons for each TP and Stop level. --- ## 6. Funding Carry Cost (`/fncost`) Forecasts holding costs (or yield received) across 8-hour, 24-hour, and 7-day horizons. **Syntax:** `/fncost [long/short] [rate%]` * `/fncost btc 10000 long` *(fetches live 8h funding rate)* * `/fncost sol 50k short 0.05%` *(custom test rate)* ================================================================= FILE: tariffs.md ================================================================= # Subscription Plans & Limits BitCLI operates on a **Product-Led Growth (PLG)** model: all core metrics (CVD, OI, Liquidations, Funding) are accessible for free, while paid plans scale your execution capacity and scanning scope. --- ## Plan Comparison Matrix | Feature / Limit | Free | Trader | Core | Pro | Prime / Founder | | :--- | :---: | :---: | :---: | :---: | :---: | | **Monthly Price** | **$0** | **$1** | **$3** | **$10** | **$30** | | **Yearly Price** *(2 Mos Free)* | — | **$10/yr** | **$30/yr** | **$100/yr** | **$300/yr** | | **Active Alert Slots** | **3** *(up to 10)* | **50** | **200** | **800** | **2,500** | | **Daily Webhook Relay** | **10 / day** | **100 / day** | **500 / day** | **3,000 / day** | **Unlimited** | | **AI Copilot Queries** | **5 / day** | **10 / day** | **30 / day** | **100 / day** | **300 / day** | | **MCP API Quota** | **50 / day** | **200 / day** | **1,000 / day** | **5,000 / day** | **25,000 / day** | | **Risk Calculators** | **Unlimited** | **Unlimited** | **Unlimited** | **Unlimited** | **Unlimited** | | **Global Exchange Scan (`*`)** | ❌ No | ❌ No | **✅ Yes** | **✅ Yes** | **✅ Yes** | | **Technical Indicators** *(RSI, EMA)* | ❌ No | ❌ No | ❌ No | **✅ Yes** | **✅ Yes** | | **White-Label Personal Bot** | ✅ Included | ✅ Included | ✅ Included | ✅ Included | ✅ Included | | **Affiliate RevShare** | 10% or 20%* | 10% or 20%* | 10% or 20%* | 10% or 20%* | **30% (5 Levels)** | > *\* Base commission is 10%. Connecting your White-Label Bot boosts your base commission to 20% across all retail tiers.* --- ## Waterfall Billing (API & MCP) BitCLI uses a **Waterfall Billing** model for AI Agents and MCP API usage to ensure you never unexpectedly run out of funds: 1. **Tariff Quota First:** Every API call (e.g., getting BCT-30 candles or setting an alert via Cursor) consumes 1 request from your daily `AI / MCP API Quota`. 2. **USD Balance (Overdraft):** If you exhaust your daily tariff quota, the system will seamlessly fallback to your unified USD Wallet Balance at a flat rate of **$0.001 per request**. ## Tier Deep Dive ### 🆓 Free Tier (The Hook) * **Limits:** 3 active alerts, 10 TradingView webhooks/day. * **AI & API:** 5 AI Copilot (Telegram) requests/day | **50 MCP API** requests/day. * **Viral Boost:** Earn **+1 permanent alert slot** for every invited friend who sets at least one alert (capped at 10 slots). ### 🔵 Trader ($1 / month or $10 / year) — "No-Brainer" * **Capacity:** **50 active alerts**, **100 webhooks/day**. * **AI & API:** **10 AI Copilot** requests/day | **200 MCP API** requests/day. * **Value:** Perfect for retail traders. Easily handles full-day PineScript webhook relaying, personal multi-coin corridor tracking, and light AI Agent (Cursor) integrations. ### 🟣 Core ($3 / month or $30 / year) — "Market Scanner" * **Capacity:** **200 alerts**, **500 webhooks/day**. * **AI & API:** **30 AI Copilot** requests/day | **1,000 MCP API** requests/day. * **Killer Feature:** **Global Wildcard (`*`) Enabled.** Monitor all 1,650+ contracts simultaneously: * `* vol 15m x4` (Exchange-wide whale spike scanner) * `* liq z3` (Statistical liquidation cascade radar) ### 🟡 Pro ($10 / month or $100 / year) — "The Quant" * **Capacity:** **800 alerts**, **3,000 webhooks/day**. * **AI & API:** **100 AI Copilot** requests/day | **5,000 MCP API** requests/day. * **Killer Feature:** Full access to continuous memory indicators (`btc rsi 15m < 25`, `sol cvd div 15m`) and heavy autonomous Python Agent usage via WebSockets. ### 👑 Prime ($30 / month) or OG Founder ($300 Lifetime) * **Capacity:** **2,500 active alerts**, **Unlimited webhooks**. * **AI & API:** **300 AI Copilot** requests/day | **25,000 MCP API** requests/day. * **Founder Status:** Limited to 100 users. All Prime features unlocked forever, plus automatic **5-Level Influencer** affiliate status. ================================================================= FILE: webhooks.md ================================================================= # TradingView Webhook Gateway Relay Pine Script alerts directly into Telegram chats, VIP channels, or private groups with zero delivery delay. --- ## 1. How It Works `TradingView Alert (HTTP POST) ➔ BitCLI Cloud Edge ➔ Redis Stream ➔ Telegram Chat` --- ## 2. Setup Guide 1. In the bot, run `/webhooks` and click **➕ Create Webhook**. 2. Give your endpoint a name (e.g. `BTC Scalp VIP`). 3. Select where signals should be delivered (**Private Chat**, **Channel**, or **Group**). * *Note: To deliver to a Channel/Group, add the bot as an Administrator with "Post Messages" rights first.* 4. Copy your unique endpoint URL. --- ## 3. Configuring TradingView 1. Open your TradingView chart and click **Create Alert** (`Alt + A`). 2. Under the **Notifications** tab, check **Webhook URL** and paste your BitCLI link. 3. In the **Settings** tab, paste this JSON payload into the **Message** box: ```json { "coin": "{{ticker}}", "action": "BUY", "price": {{close}}, "comment": "RSI Oversold Bounce" } ``` --- ## 4. Custom Jinja2 Templates You can customize message formatting directly from Pine Script by passing a `"message"` field: ```json { "message": "🔥 VIP SIGNAL\nCoin: {{ticker}}\nEntry: {{close}}\nTP1: {{plot_0}}" } ``` BitCLI renders this payload into a formatted card: > 🔥 **VIP SIGNAL** > Coin: `BTCUSDT` > Entry: 95200.50 > TP1: 96000.00 --- ## 5. Security & IP Whitelisting * **TradingView IP Filter:** Toggle this option in `/webhooks` to silently drop any request originating outside TradingView's official server subnets. * **Instant URL Rotation:** If your secret URL leaks, regenerate it in one tap without deleting your webhook config. ================================================================= FILE: mcp.md ================================================================= # Model Context Protocol (MCP) Server Connect your AI agents (Cursor, Claude Desktop, AutoGPT) directly to live exchange order flow via the official **BitCLI MCP Server**. > 🛑 **Stop burning millions of LLM tokens on raw OHLCV data.** > Traditional REST APIs send bloated JSON arrays. BitCLI computes complex micro-structural metrics in RAM and delivers **token-optimized BCT matrices** directly into your agent's context window. --- ## 1. Agent Architecture: Stateless vs Autonomous BitCLI supports two paradigms for AI integration: ### A. Stateless Assistants (Cursor, ChatGPT) * **Transport:** Streamable HTTP POST (`https://mcp.bitcli.io/mcp`) * **How it works:** The agent analyzes the market upon your prompt and uses the `alert_manager` tool to set an HFT trigger in the BitCLI C++ Engine. The agent then goes to sleep. When the market condition is met, BitCLI pushes the alert directly to the human user's Telegram or Discord. * **Pro-Tip:** Agents can also use the `send_notification` tool to push immediate text insights to the user's chat. ### B. Autonomous Agents (Python SDK) * **Transport:** Stateful WebSockets (`wss://mcp.bitcli.io/stream`) * **How it works:** Your Python script stays running 24/7. It sets a trigger, and when the C++ engine catches the anomaly, it pushes an event down the WebSocket. Your agent wakes up, pulls the latest data, and executes a trade via exchange APIs. --- ## 2. API Keys & Waterfall Billing BitCLI operates a unified billing system for human Telegram accounts and autonomous AI agents. We use a **Waterfall** approach: 1. **Daily Quota:** When your agent executes a tool, it first deducts from your tariff's daily AI allowance (e.g., Pro plan gets 100 free requests/day). 2. **Pay-As-You-Go ($0.001/req):** Once the daily quota is exhausted, tools are billed at ~$0.001 USD from your global wallet balance. *You can generate an API Key directly in the Telegram Bot (`/list` ➔ `Delegate to AI Agent`) or in the Web Dashboard.* ### 🔧 How to add your API Key to Cursor IDE Cursor's MCP UI does not currently support custom HTTP Headers. You must pass your API key directly in the URL via the `token` query parameter: 1. Open Cursor Settings -> Features -> MCP. 2. Add a new **SSE** Server. 3. Name it `BitCLI`. 4. URL: `https://mcp.bitcli.io/mcp/sse?token=bcli_YOUR_KEY_HERE` *(If you use Claude Desktop, you can inject it via `env` variables).* --- ## 3. Core Tools Exposed ### `market_data` Fetches token-optimized historical OHLCV, CVD delta, and server-side calculated indicators formatted as BCT. Also runs the dynamic screener across 1,650+ perpetuals. ### `calc_engine` Executes mathematical models: position sizing based on $ risk, true MMR liquidation prices, DCA break-even, and multi-target R:R. ### `alert_manager` Registers a high-frequency trigger in the C++ engine. Uses the exact same syntax as the Telegram bot (e.g., `btc 95k`, `sol +3% 5m`, `* vol 15m x4`). ### `send_notification` [NEW] Allows the agent to send a direct message (Telegram HTML supported) to any of the user's verified destinations (Private Telegram, Channels, or Discord Webhooks). Perfect for keeping the human in the loop. ### `user_account` Read-only tool for the agent to check its remaining daily USD limit and list available notification destinations. ================================================================= FILE: partners.md ================================================================= # Affiliate Program & Custom White-Label Bots BitCLI provides an automated revenue-share model and a 1-click personal bot deployment engine. --- ## 1. Commission Structure (1-Level vs 5-Level) ### 🔵 Single-Level Commission (Direct Invites) If you invite users directly, you earn a percentage of their subscription payments. * **Standard Partner:** **10%** * **B2B Bot Owner:** **20%** *(Automatically activated when you link your own bot via `/my_bot`)*. ### 👑 Multi-Level Commission (Influencers & Founders) If you are an approved Influencer or hold the **OG Founder** Lifetime tier, you earn from **5 levels deep** across your entire network tree. Total payout spans **30%**: * **Level 1 (Direct Referrals):** 20% * **Level 2:** 4% * **Level 3:** 3% * **Level 4:** 2% * **Level 5:** 1% --- ## 2. Free Alert Limit Boost (+1 per Friend) * For every invited user who creates **at least one active alert**, your permanent Free tier alert limit increases by **+1**. * Maximum free limit expansion: **10 active alerts** (up from default 3). --- ## 3. Launching Your Own White-Label Bot Telegram limits single bots to 30 messages per second globally. By linking your own custom bot, you get an **isolated rate-limit channel** with 0ms delivery latency, while upgrading your base affiliate commission to **20%**. ### Step-by-Step Setup: 1. Open [@BotFather](https://t.me/BotFather) in Telegram. 2. Send `/newbot`, name your bot, and choose a username. 3. In [@BotFather](https://t.me/BotFather), go to `/mybots` → select your bot → **Bot Settings** → **Inline Mode** → click **Turn on** (or send `/setinline`, pick your bot, and enter any placeholder text, e.g., `whales, ta, pos...`). 4. Copy your HTTP API token. 5. In our bot, run `/my_bot` and send the token. **What BitCLI automates in 1 second:** * Uploads the official bot avatar. * Sets up short/long descriptions and menu commands. * Sets Default Administrator Rights (so it works in channels out-of-the-box). * Attaches the high-frequency webhook. --- ## 4. Invisible Referral Binding Users who join through your personal bot link (`https://t.me/YourBotName`) are **permanently tied to your affiliate account**, even without an explicit referral link parameter. ================================================================= FILE: ai.md ================================================================= # AI Copilot & Quant Assistant BitCLI features a built-in AI Copilot powered by ultra-fast LLMs. It acts as an interactive assistant directly inside the Telegram chat — you don't even need to type special slash commands. --- ## 1. Zero-Friction Syntax Auto-Fix If you mistype a command, make formatting errors, or use natural language, the AI Copilot detects your intent and returns an instant, ready-to-copy correction wrapped in `...`. ### Examples: * **User:** `set alert bitcoin 95 000` **AI Copilot:** *"Avoid spaces in price numbers. Use this command:"* `btc 95k` * **User:** `volume surge solana 4x in 15 minutes` **AI Copilot:** *"For volume spike detection against SMA20, use:"* `sol vol 15m x4` --- ## 2. Order Flow & Quant Explanations You can ask the Copilot complex questions about crypto derivatives, market structure, and mechanics. It speaks strictly as an order flow quant: * *"What does a -0.08% funding rate mean?"* ➔ Explains the short-side crowding and potential short squeeze dynamic in 2 concise sentences. * *"How does CVD divergence differ from regular RSI divergence?"* ➔ Explains aggressive market order exhaustion vs passive limit absorption. --- ## 3. Real-Time Market Context When you mention a ticker, BitCLI automatically injects **live price hints** directly into the AI's prompt from the C++ RAM engine. The Copilot knows current market prices without web-scraping latency. --- ## 4. Daily Quotas & Upgrades | Plan | Daily AI Queries | Reset Time | | :--- | :---: | :---: | | **Free** | **5 / day** | 00:00 UTC | | **Trader ($1)** | **10 / day** | 00:00 UTC | | **Core ($3)** | **30 / day** | 00:00 UTC | | **Pro ($10)** | **100 / day** | 00:00 UTC | | **Prime / Founder** | **300 / day** | 00:00 UTC |