A real-time crypto market intelligence system that predicts potential liquidation cascades by combining derivatives data with stablecoin flow analysis.

Ever noticed how crypto markets can crash 10% in minutes? That's often a liquidation cascade - when leveraged traders get liquidated, their forced sells trigger more liquidations, creating a domino effect.

This project tries to detect these events before they happen by watching:

• Funding rates - High positive = too many longs, they'll get rekt on a dip
• Open Interest changes - Rising OI + flat price = overleveraged market
• Long/Short ratios - Extreme imbalance = reversal incoming
• Stablecoin flows - Big USDT deposits to exchanges often precede dumps

The system calculates two scores:

• Liquidation Risk (0-100) - How likely is a cascade?
• Stablecoin Pressure (-100 to +100) - Is smart money buying or selling?

When both signals align (high risk + negative pressure), you get an alert.

CoinGecko API ──→ Futures Producer ──→ Kafka ──→ Signal Processor ──→ TimescaleDB ──→ Grafana
Etherscan API ──→ Stablecoin Producer ──↗

Stack:

• Data Sources: CoinGecko (prices), Etherscan (stablecoin flows)
• Message Queue: Apache Kafka
• Processing: Python (custom signal processor)
• Storage: TimescaleDB (time-series PostgreSQL)
• Visualization: Grafana

• Docker & Docker Compose
• Python 3.9+
• (Optional) Etherscan API key for stablecoin tracking

git clone https://github.com/dharmateja03/liquidation-cascade-monitor.git
cd liquidation-cascade-monitor

# Start Kafka, TimescaleDB, Grafana
docker-compose up -d

# Wait for services to be ready
sleep 15

# Create Kafka topics
docker exec kafka kafka-topics --bootstrap-server localhost:9092 \
  --create --topic prices --partitions 3 --replication-factor 1 --if-not-exists

docker exec kafka kafka-topics --bootstrap-server localhost:9092 \
  --create --topic funding_rates --partitions 3 --replication-factor 1 --if-not-exists

docker exec kafka kafka-topics --bootstrap-server localhost:9092 \
  --create --topic open_interest --partitions 3 --replication-factor 1 --if-not-exists

docker exec kafka kafka-topics --bootstrap-server localhost:9092 \
  --create --topic liquidations --partitions 3 --replication-factor 1 --if-not-exists

docker exec kafka kafka-topics --bootstrap-server localhost:9092 \
  --create --topic long_short_ratio --partitions 3 --replication-factor 1 --if-not-exists

docker exec kafka kafka-topics --bootstrap-server localhost:9092 \
  --create --topic stablecoin_flows --partitions 3 --replication-factor 1 --if-not-exists

cd producers
pip install -r requirements.txt

Terminal 1 - Data Producer:

python binance_futures_producer.py

Terminal 2 - Signal Processor:

python signal_processor.py

Terminal 3 (Optional) - Stablecoin Tracker:

# Edit stablecoin_producer.py and add your Etherscan API key first
python stablecoin_producer.py

Go to http://localhost:3000

• Username: admin
• Password: admin

Navigate to Dashboards → "Liquidation Cascade Monitor"

liquidation-cascade-monitor/
├── docker-compose.yml          # Infrastructure setup
├── start.sh                    # One-click startup script
├── config/
│   └── init.sql                # TimescaleDB schema
├── producers/
│   ├── requirements.txt
│   ├── binance_futures_producer.py   # Price & derivatives data
│   ├── stablecoin_producer.py        # On-chain stablecoin flows
│   └── signal_processor.py           # Risk calculation engine
├── grafana/
│   └── provisioning/
│       ├── datasources/
│       │   └── datasources.yml
│       └── dashboards/
│           ├── dashboards.yml
│           └── liquidation_cascade.json
└── docs/
    ├── architecture.png
    └── grafana-dashboard.png

Current Limitations:

• Binance Futures API is geo-restricted (US). Using simulated derivatives data based on spot price movements.
• Stablecoin tracking requires Etherscan API key
• Only tracking BTC and ETH currently

Ideas for Improvement:

• Add more exchanges (Bybit, OKX, dYdX)
• Real liquidation data from exchanges with global access
• ML model for cascade prediction
• Telegram/Discord alerts
• Historical backtesting to validate signals

Kafka not starting?

docker-compose down -v
docker-compose up -d

No data in Grafana?

1. Make sure producers are running
2. Check Kafka UI at http://localhost:8080 to see if messages are flowing
3. Verify TimescaleDB has data:

docker exec timescaledb psql -U postgres -d crypto_signals -c "SELECT COUNT(*) FROM prices;"

MIT - Do whatever you want with it.

Built for learning Kafka, stream processing, and crypto market microstructure. Not financial advice. Don't trade based on this. This file is built with AI