AI-powered derivatives market analysis that aggregates funding rates, open interest, order book depth, liquidations, and long/short ratios across exchanges — then produces directional bias scores using Claude AI.

• Fetches real-time derivatives data from Bybit (free) and Coinglass ($29/mo)
• Aggregates 8 data sources per symbol into a unified market snapshot
• Sends data to Claude AI for directional bias analysis (-100 to +100 score)
• Delivers color-coded signals to Slack with key findings and warnings
• Stores all signals in SQLite (or optional Supabase) for historical analysis
• Exposes a REST API for custom integrations

• Python 3.11+
• Bybit API key (free)
• Coinglass API key ($29/mo minimum)
• Anthropic API key
• Slack incoming webhook URL

cp config.example.yaml config.yaml
# Edit config.yaml with your settings

export BYBIT_API_KEY="your-key"
export BYBIT_API_SECRET="your-secret"
export COINGLASS_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"

pip install -r requirements.txt
python doctor.py --config config.yaml

All 7 checks should pass. Review doctor-report.json for details.

# Background loop (every 5 minutes)
python main.py --config config.yaml

# Single analysis, all symbols
python main.py --config config.yaml --once

# Single symbol
python main.py --config config.yaml --once --symbol BTCUSDT

# REST API server
python main.py --config config.yaml --serve --port 8000

# Build
docker build -t derivatives-signal-agent .

# Run loop mode
docker-compose up agent

# Run API server
docker-compose --profile api up api

# Run doctor
docker-compose --profile doctor run doctor

When running with --serve:

# Analyze BTC
curl -X POST http://localhost:8000/analyze/BTCUSDT

# Get latest signals
curl http://localhost:8000/signals/latest

# Health check
curl http://localhost:8000/health

Each signal includes:

• Score: -100 (extreme bearish) to +100 (extreme bullish)
• Bias: strong_bearish, bearish, neutral, bullish, strong_bullish
• Confidence: low, medium, high
• Findings: Key observations from the data
• Warnings: Conflicting signals or extreme readings
• Data Quality: complete, partial, degraded
• Cost: Claude API cost for the analysis

If any source fails, analysis proceeds with available data. Claude is told which sources are missing.

See config.example.yaml for all options. Key sections:

• analysis: Symbols to track, signal thresholds
• notifications: Slack, webhook, email, Telegram settings
• storage: SQLite (default) or Supabase
• guardrails: Daily limits, cost caps, quiet hours
• cache: TTL settings per data type
• rate_limits: Per-provider request limits with circuit breaker

• Bybit API: Free
• Coinglass API: $29/month (buyer pays)
• Claude API: ~$0.001-0.005 per analysis (configurable daily cap)
• Self-hosted: No monthly platform fees

• Read-only: No trade execution code exists. guardrails.read_only: true cannot be disabled.
• Daily limits: Configurable max analyses per day and cost cap.
• Disclaimers: Every output includes SEC compliance disclaimer.
• Secrets: All API keys via environment variables, never in config files.

This software is for informational purposes only and does not constitute financial advice. Trading derivatives carries substantial risk of loss. Past performance is not indicative of future results. Do your own research.

See LICENSE.md. Non-exclusive, non-transferable, perpetual usage license with 7-day defect warranty.