Repository: github.com/python-telegramBot/crypto-liquidity-ai-trading-bot
A modular, signal-driven trading framework for cryptocurrency markets. Detects order book gaps, hidden liquidity walls, and sweep events across major exchanges in real time—designed for quant researchers, algo traders, and firms building liquidity-aware execution tools.
- Overview
- Why Liquidity-Based Signals
- Target Users
- Backtest Results
- Strategy Concept
- Architecture
- Quick Start
- Capabilities
- How Liquidity Detection Works
- Installation
- Supported Exchanges
- Project Structure
- Use Cases
- Related Projects
- FAQ
- Contributing
Most trading bots react to price. This one reads the market differently.
crypto-liquidity-ai-trading-bot focuses on order book structure—detecting where large passive orders sit, when liquidity walls form or vanish, and when stop-loss clusters are swept. These events often precede sharp price moves, making them higher-quality signals than most lagging technical indicators.
The framework is built to be modular and extensible: plug in your own execution engine, risk layer, or research pipeline without rewriting the core.
Retail indicators (RSI, MACD, moving averages) describe what price has already done. Order book data describes what is about to happen—where passive capital is sitting, where stops are clustered, and which levels the market is likely to test.
Professional traders monitor this continuously. This framework gives independent developers and quant teams the same visibility.
Key signal types detected:
- Liquidity gaps — thin order book zones where price may move rapidly
- Hidden walls — large resting orders that appear or disappear
- Stop-loss sweeps — price reaching stop clusters, triggering momentum
- Book imbalance — aggressive bid/ask pressure shifts
This project is intended for:
- Algorithmic trading firms building in-house liquidity intelligence and execution infrastructure
- Quantitative researchers studying order book dynamics and market microstructure
- Exchanges and surveillance teams monitoring for liquidity anomalies
- Developers building AI trading agents, signal systems, or execution layers
It assumes familiarity with financial markets, order books, and at least one of Node.js or Python.
The metrics below are from a historical simulation using order-book and liquidity-sweep signals on major spot pairs. These are not live trading results.
Test Configuration
| Parameter | Value |
|---|---|
| Period | January 2024 – December 2024 |
| Duration | 12 months |
| Asset class | Cryptocurrency (spot) |
| Strategy | Liquidity-sweep + order-book imbalance |
| Trading style | Medium-frequency, signal-driven |
| Pairs | BTC/USDT, ETH/USDT, selected altcoins |
| Execution model | Simulated limit and market fills |
Performance Metrics
| Metric | Result |
|---|---|
| Win rate | 58.2% |
| Profit factor | 1.42 |
| Max drawdown | −12.4% |
| Sharpe ratio (daily) | 1.18 |
Interpreting These Numbers
A win rate above 50% suggests the liquidity signals carry predictive information beyond a random baseline. A profit factor of 1.42 indicates positive expectancy over the tested period. A daily Sharpe above 1.0 reflects reasonable risk-adjusted returns, while max drawdown of −12.4% bounds the observed tail risk.
Example signal output:
{
"symbol": "BTC/USDT",
"direction": "LONG",
"strength": 0.61,
"reason": "liquidity_sweep_detected",
"ts": "2024-11-15T08:44:02Z"
}Disclaimer: Backtest results do not guarantee future performance. Live results will differ due to fees, slippage, execution latency, and changing market conditions. Conduct independent testing and risk assessment before any live deployment.
Price indicators lag. Liquidity moves first.
Large resting orders and stop-loss clusters sit in the order book before price reaches them. When price sweeps those levels, liquidity is consumed—and subsequent moves often accelerate as the book empties. This framework identifies and monitors those levels continuously.
The goal is to trade with order flow rather than chasing price action after the fact.
Market Data (REST / WebSocket)
│
▼
Order Book Analyzer
│
▼
Liquidity Detector
(gaps · walls · sweeps)
│
▼
Signal Engine
│
┌────┴────┐
▼ ▼
Alerts Execution Layer
(optional)
The codebase maintains a clean separation between:
- Data ingestion (
modules/) — exchange APIs, raw book data - Analysis (
trade/) — orderbook processing, liquidity detection - Output — configurable alerts and an optional execution interface
This makes it straightforward to extend any layer independently.
git clone https://github.com/python-telegramBot/crypto-liquidity-ai-trading-bot.git
cd crypto-liquidity-ai-trading-bot
npm installEdit config.default.jsonc with your exchange API keys and preferred settings, then:
node app.jsFor backtesting, data analysis, or building a custom Python wrapper:
python -m venv venv
source venv/bin/activate # macOS/Linux
# venv\Scripts\activate # Windows
pip install -r requirements.txtSee full Installation instructions below for environment-specific details.
| Feature | Description |
|---|---|
| Liquidity detection | Scans order books for depth gaps, concentration zones, and imbalance |
| Hidden wall tracking | Surfaces and monitors large resting buy/sell walls in real time |
| Sweep detection | Identifies stop-loss cluster sweeps and aggressive market order flow |
| Multi-exchange support | Designed to connect to Binance, Bybit, Kraken, OKX, and others |
| Configurable alerts | Fires notifications on liquidity events via configurable thresholds |
| Modular framework | Clean separation of data, analysis, and execution layers |
Liquidity hunting targets price zones where large volumes of passive orders (stops, limits) are concentrated. When price reaches and sweeps those zones, the resulting order flow often drives fast, directional moves.
The detection pipeline operates in four stages:
- Map — Continuously scan order books to identify stop-loss clusters and thin book zones
- Detect — Recognize in real time when walls form, disappear, or are swept
- Alert — Emit a signal when a liquidity event fires so you can act immediately
- Execute — Optionally feed signals into your own execution layer (manual or automated)
Detectable signal types: stop-loss clusters, order book vacuums, liquidity wall removals, and aggressive market order flow.
git clone https://github.com/python-telegramBot/crypto-liquidity-ai-trading-bot.git
cd crypto-liquidity-ai-trading-botNode.js (main engine):
npm install
# Configure API keys in config.default.jsonc
node app.jsPython (optional research layer):
python -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows
pip install -r requirements.txtPython usage example:
from liquidity_hunting import LiquidityBot
bot = LiquidityBot(api_key="YOUR_API_KEY", secret="YOUR_SECRET")
bot.scan_liquidity()
bot.generate_alerts()API keys and exchange endpoints are configured via config.default.jsonc. Copy it to config.jsonc before making changes.
The framework is designed to connect to any exchange with a REST or WebSocket API. The following are supported out of the box:
| Exchange | Markets |
|---|---|
| Binance | Spot, Futures |
| Bybit | Derivatives |
| Kraken | Spot |
| OKX | Spot, Derivatives |
| Coinbase | Spot |
| Hyperliquid | Perpetuals |
Custom exchange integrations can be added by implementing the standard connector interface in trade/.
crypto-liquidity-ai-trading-bot/
├── app.js # Application entry point
├── config.default.jsonc # Configuration template
├── package.json
├── helpers/ # Shared utilities and cryptographic helpers
├── modules/ # Exchange API clients, database, configuration
├── routes/ # Health checks, debug, and initialization routes
├── trade/ # Core logic: liquidity, orderbook, exchange adapters
├── types/ # TypeScript type declarations
├── utils/ # General-purpose utilities
└── assets/ # Static assets and documentation images
Algorithmic trading — Feed structured liquidity signals into your execution engine for automated or semi-automated strategies.
Quantitative research — Analyze order book behavior, sweep frequency, and book imbalance patterns across assets and time periods.
AI/ML feature engineering — Use liquidity events as features or triggers in machine learning models trained on market microstructure data.
Market microstructure analysis — Study how gaps, walls, and sweep behavior evolve across different market conditions and exchanges.
Part of the same AI trading framework suite:
- Crypto Futures AI Trading Bot — Funding rate arbitrage and smart-money flow monitoring
- Cross-Exchange AI Arbitrage Bot — CEX/DEX spread detection and cross-venue execution
What is liquidity hunting?
A strategy that focuses on price levels where large volumes of stop-loss or passive limit orders are concentrated. When price reaches those levels, the liquidity is consumed ("swept") and price often accelerates. Identifying these zones in advance is the core signal this framework provides.
Is execution automated?
The framework focuses on signal generation and alerting. Automated execution is not included by default—you can integrate your own execution layer, or use the signals to inform manual trading decisions.
What technical background is required?
Working knowledge of order books, crypto markets, and Node.js (or Python for research use) is assumed. The codebase is documented and modular, but this is not a beginner-oriented tool.
Can I add my own exchange?
Yes. Implement the standard connector interface in trade/ and configure the endpoint in config.jsonc.
Contributions are welcome. The preferred workflow is:
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes with clear, descriptive messages
- Open a pull request against
main
Please open an issue first for significant changes or new features. See CONTRIBUTING.md for additional guidelines.
License: MIT © 2026