Autonomous Multi-Agent AI Crypto Trading Operating System
⚠️ RESEARCH SOFTWARE - EDUCATIONAL USE ONLY SIGMAX is experimental research software for learning about AI trading systems. NOT for production trading. Trading crypto involves high risk of total loss. Read full Disclaimer before use.
SIGMAX is an open-source, autonomous AI trading system that combines multi-agent intelligence, quantum optimization, and advanced risk management for cryptocurrency trading.
🤖 Multi-Agent Debate - Bull vs Bear agents with researcher arbitration ⚛️ Quantum Optimization - VQE/QAOA portfolio optimization with Qiskit (real implementation) 🛡️ Safety-First - Auto-pause triggers, risk limits, paper trading 🔒 AI Security - Prompt injection defense, MCP hijacking protection, fake news detection 🧠 Behavioral Finance - Cognitive biases, social sentiment, Fear & Greed modeling 🎨 Web UI - Minimal, tabbed dashboard for system state, events, and connections 🔊 Multiple Interfaces - Telegram, Web UI, CLI, Python/TypeScript SDKs 💯 Local Option - Can run with Ollama (default uses cloud LLMs)
- OS: macOS 13+ or Linux (Ubuntu 22.04+)
- RAM: 16GB minimum
- Tools: Docker/Podman, Node.js 20+, Python 3.11+, Rust 1.75+
git clone https://github.com/I-Onlabs/SIGMAX.git
cd SIGMAX
bash deploy.shThis will:
- Install dependencies
- Start backend services (Podman)
- Launch UI at
http://localhost:3000 - Build macOS .app (if on macOS)
- Open setup wizard
Click to expand manual installation steps
# 1. Backend
cd core
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# 2. Frontend
cd ../ui/web
npm install
# 3. Environment
cp .env.example .env
# Edit .env with your API keys
# 4. Services
podman-compose up -d
# 5. Start UI
npm run dev
# 6. Start orchestrator
cd ../../core
python main.pySIGMAX has completed six major development phases with production-ready components:
| Phase | Achievement | Status |
|---|---|---|
| Phase 1 | Performance benchmarking - 1,700+ decisions/sec, 10-100x above targets | ✅ Results |
| Phase 2 | Integration testing - 437 tests, 89 integration tests, 100% pass rate | ✅ Summary |
| Phase 3 | SDK publishing - Python & TypeScript ready for PyPI/npm | ✅ Python • TypeScript |
| Phase 4 | CLI packaging - PyPI-ready distribution with comprehensive docs | ✅ Details |
| Phase 5 | AI Security - TradeTrap-inspired multi-layer defense system | ✅ Docs |
| Phase 6 | Behavioral Finance - TwinMarket-inspired agent behavior modeling | ✅ Docs |
Key Highlights:
- 🚀 Performance: Sub-millisecond decisions, production-ready throughput
- 🧪 Testing: Comprehensive coverage with clean security audit
- 📦 Distribution: SDKs ready for publication (pending final review)
- 🛠️ Tooling: Professional CLI with multiple installation modes
- 🔒 Security: Prompt injection, MCP hijacking, state tampering, fake news defense
- 🧠 Behavioral: Cognitive biases, social sentiment networks, order book simulation
See Roadmap for complete phase details.
| 🎯 I want to... | 📖 Start here |
|---|---|
| Trade crypto with AI |
bash deploy.sh → Use Telegram botSee Telegram Commands |
| Build apps on SIGMAX |
Install SDK: pip install sigmax-sdkSee SDK Guide |
| Automate trading ops |
Use CLI: sigmax analyze BTC/USDTSee CLI Guide |
| Research AI trading |
Read Architecture See Enhancements |
| Contribute code |
Fork repo → Read Contributing Join Discord |
┌─────────────┐
│ Planner │ Creates structured plan
└──────┬──────┘
▼
┌──────────────┐
│ Researcher │ Executes tasks in parallel (1.8-2.4x speedup)
└──────┬───────┘
▼
┌──────────────┐
│ Validator │ 4D quality checks, re-research if needed
└──────┬───────┘
▼
┌──────────────┐
│ Fundamental │ On-chain metrics + financial ratios
└──────┬───────┘
▼
┌──────────────┐
│ Bull vs Bear │ Informed debate
│ Debate │
└──────┬───────┘
▼
┌─────────────────┐
│ Risk + Privacy │ Final safety check
└─────────────────┘
Specialized Agents:
- Sentiment - Multi-source aggregation (news, social, on-chain)
- Technical - ML ensemble (XGBoost, LightGBM, Random Forest)
- Fundamentals - P/F, MC/TVL, NVT, token velocity
- Risk - Exposure monitoring, auto-pause triggers
- Arbitrage - 50+ DEX/CEX scanning
- Privacy - PII detection, anti-collusion
- Compliance - EU AI Act + SEC compliant
SIGMAX uses quantum computing (VQE/QAOA algorithms via Qiskit) for portfolio optimization.
Features:
- Portfolio Optimization - VQE + QAOA algorithms for optimal position sizing
- Hot-starting - Faster convergence using classical solutions as initial state
- Visualization Hooks - Circuit data available via API for optional UI rendering
- Classical Fallback - Automatic Kelly Criterion fallback when quantum disabled/fails
Configuration:
- Enable: Set
QUANTUM_ENABLED=truein.env(default) - Disable: Set
QUANTUM_ENABLED=falsefor classical-only optimization - Performance: Quantum is more accurate but slower; classical is fast and reliable
When to Use:
- ✅ Quantum: Complex portfolio optimization, multi-asset portfolios, production trading
- ✅ Classical: Simple buy/sell decisions, low-latency requirements, development/testing
See Quantum Module Documentation for details.
- Freqtrade Integration - Paper + Live trading (implemented)
- HFT Support - HFT execution module present; LEAN engine integration planned
- Multi-Chain - On-chain RPC sampling for EVM/Solana via
CHAINS+CHAIN_RPC_*; full multi-chain execution planned - Slippage Monitoring - Auto-pause on excessive slippage (>1%) (implemented)
- Backtesting - Framework for Sharpe/Sortino, max drawdown analysis (implemented)
SIGMAX implements multi-layered defense against AI-specific trading threats (inspired by TradeTrap):
| Defense Layer | Threat | Protection |
|---|---|---|
| PromptGuard | Prompt injection | Pattern detection, sanitization |
| ToolValidator | MCP hijacking | Schema validation, anomaly detection |
| StateIntegrity | State tampering | Position/balance verification |
| NewsValidator | Fake news | Source credibility, manipulation detection |
from core.agents import SecureOrchestrator
orchestrator = SecureOrchestrator(enable_all_guards=True)
result = await orchestrator.analyze_symbol_secure("BTC/USDT")See Security Module Documentation for details.
SIGMAX models realistic agent behavior with cognitive biases and social dynamics (inspired by TwinMarket):
Cognitive Biases:
- Disposition Effect - Hold losers, sell winners early
- Loss Aversion - Weight losses 2x more than gains
- Overconfidence - Overestimate prediction accuracy
- Herding - Follow crowd behavior
Social Sentiment:
- Fear & Greed Index (0-100 scale)
- Sentiment propagation networks
- Herd behavior detection
Market Simulation:
- Order book matching engine
- Price-time priority
- Market impact modeling
# Run multi-agent simulation
python tools/behavioral_simulation.py --agents 20 --rounds 100 --symbol BTC/USDTSee Behavioral Finance Documentation for details.
Risk Caps (Configurable):
- Max Exposure: $50 total
- Position Size: $10-15 per trade
- Stop Loss: -1.5% per trade
- Daily Loss Limit: $10
Auto-Pause Triggers:
- 3 consecutive losses
- API error burst (>5 errors/min)
- Sentiment drop (<-0.3)
- MEV attack (slippage >1%)
Logging & Monitoring:
- Decision logging with timestamps
- Daily performance snapshots via Telegram (planned)
- CSV export for analysis
- API request audit logs
- Tabbed Layout - Overview, Analysis, Events, System Health, Connections
- Performance Charts - In-session metrics and trends
- Event Log - Filterable trading events
- System Status - Health indicators and risk triggers
- Connections - Exchange accounts + actions
✅ Status: Performance benchmarks completed Dec 21, 2024. All operations exceed production targets by 10-100x. See PERFORMANCE_BASELINE.md for complete analysis.
Benchmarked on: M3 Max, macOS, Python 3.10.12 (December 21, 2024)
| Operation | Mean | P95 | P99 | Throughput |
|---|---|---|---|---|
| Decision Storage (In-Memory) | 0.015ms | 0.017ms | 0.022ms | 66,000 ops/sec |
| Decision Storage (PostgreSQL) | 0.58ms | 1.00ms | 1.50ms | 1,700 ops/sec |
| Database Queries (LIMIT 10) | 0.16ms | 0.18ms | 0.23ms | 6,400 ops/sec |
| Quantum Module Init | 0.015ms | 0.016ms | 0.016ms | Instant |
- Trading Decisions (with PostgreSQL): ~1,000 decisions/second
- API Queries (from database): ~5,000 queries/second
- In-Memory Reads: ~50,000 ops/second
| Mode | Latency | Use Case |
|---|---|---|
| Classical | <1ms | ✅ Real-time trading, high-frequency |
| Quantum | 2-30 seconds | ✅ Strategic rebalancing, complex portfolios (5+ assets) |
Key Finding: Classical mode delivers sub-millisecond decisions suitable for real-time trading. Quantum mode adds 20-300x latency but provides mathematically optimal portfolio allocation for strategic decisions.
Production Targets: All operations exceed targets by 10-100x. System handles 1,700+ decisions/second with <1.5ms P99 latency.
- ✅ Test suite: 437 tests pass (100% pass rate)
- ✅ Integration tests: 89 tests covering API workflow, quantum integration, safety enforcer
- ✅ Security audit: Clean (all HIGH/MEDIUM issues resolved)
- ✅ Performance baselines: Complete (full report)
# Run agent latency benchmarks
pytest tests/performance/benchmark_agents.py -v -s -m performance
# Run API load tests (requires API server running)
locust -f tests/load/locustfile.py --host=http://localhost:8000 \
--users 100 --spawn-rate 10 --run-time 5m --headless
# Full instructions: docs/PERFORMANCE_BASELINE.md/status # Current PnL, open trades
/start balanced # Start with balanced risk profile
/pause 2h # Pause for 2 hours
/resume # Resume trading
/panic # Emergency stop + close all
/why BTC/USDT # Explain last BTC decision
/quantum portfolio # Show quantum optimization
/agents # Show agent debate history# Install with CLI support
pip install -e ".[cli]"
# Configure API access
sigmax config set api_key YOUR_API_KEY
# Analyze trading pairs
sigmax analyze BTC/USDT --risk balanced
# Check system status
sigmax status
# Create and manage proposals
sigmax propose ETH/USDT --size 1000
sigmax approve PROP-abc123
sigmax execute PROP-abc123
# Interactive shell mode
sigmax shell
⚠️ NOT YET PUBLISHED - Install from source until v0.3.0
# ❌ pip install sigmax-sdk # NOT available yet
# ✅ Install from source:
git clone https://github.com/I-Onlabs/SIGMAX.git
cd SIGMAX/sdk/python
pip install -e .from sigmax_sdk import SigmaxClient, RiskProfile, TradeMode
async with SigmaxClient(api_url="http://localhost:8000") as client:
# Get system status
status = await client.get_status()
# Streaming analysis (SSE)
async for event in client.analyze_stream("BTC/USDT"):
print(f"[{event['status']}] {event.get('message', '')}")
if event.get('final'):
break
# Synchronous analysis
result = await client.analyze("ETH/USDT", RiskProfile.BALANCED)
# Trading workflow
proposal = await client.propose_trade("BTC/USDT", mode=TradeMode.PAPER, size=0.1)
await client.approve_proposal(proposal.proposal_id)
await client.execute_proposal(proposal.proposal_id)
⚠️ Publication status depends on npm release. If not published, install from source.
# ✅ If published:
# npm install @sigmax/sdk
# ✅ Install from source:
git clone https://github.com/I-Onlabs/SIGMAX.git
cd SIGMAX/sdk/typescript
npm install && npm run build
npm link
# In your project:
npm link @sigmax/sdkimport { SigmaxClient, RiskProfile, TradeMode } from '@sigmax/sdk';
const client = new SigmaxClient({
apiUrl: 'http://localhost:8000'
});
// Get system status
const status = await client.getStatus();
// Streaming analysis (SSE)
for await (const event of client.analyzeStream('BTC/USDT')) {
console.log(`[${event.status}] ${event.message || ''}`);
if (event.final) break;
}
// Synchronous analysis
const result = await client.analyze('ETH/USDT', RiskProfile.BALANCED);
// Trading workflow
const proposal = await client.proposeTrade('BTC/USDT', {
mode: TradeMode.PAPER,
size: 0.1
});
await client.approveProposal(proposal.proposalId);
await client.executeProposal(proposal.proposalId);📖 TypeScript SDK Documentation
Publishing is automated via GitHub Actions when a sdk-ts-v* tag is pushed.
# Streaming analysis (SSE)
curl -N -H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"message":"Analyze BTC","symbol":"BTC/USDT"}' \
http://localhost:8000/api/chat/stream
# Trade proposals
curl -X POST -H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"symbol":"BTC/USDT"}' \
http://localhost:8000/api/chat/proposals
# List proposals
curl -H "Authorization: Bearer $API_KEY" \
http://localhost:8000/api/chat/proposals
# Approve proposal
curl -X POST -H "Authorization: Bearer $API_KEY" \
http://localhost:8000/api/chat/proposals/PROP-123/approve
# Execute proposal
curl -X POST -H "Authorization: Bearer $API_KEY" \
http://localhost:8000/api/chat/proposals/PROP-123/executeSIGMAX/
├── core/ # Multi-agent orchestrator
│ ├── main.py # Main entry point
│ ├── agents/ # Specialized AI agents
│ ├── modules/ # Trading, quantum, arbitrage
│ └── interfaces/ # Multi-channel contracts
├── trading/ # Trading engines
│ ├── freqtrade/ # Main bot
│ └── lean/ # HFT backup
├── ui/ # Web UI + API
│ ├── web/ # React frontend
│ ├── desktop/ # Tauri wrapper
│ └── api/ # FastAPI backend
├── infra/ # Deployment
│ ├── podman-compose.yml
│ └── prometheus/
└── docs/ # Documentation
SIGMAX supports multiple interfaces feeding the same orchestrator:
| Interface | Status | Use Case |
|---|---|---|
| Telegram Bot | ✅ Production | Natural language control |
| Web UI | ✅ Production | Minimal dashboard |
| Web API | ✅ Production | REST + SSE streaming |
| CLI | ✅ Production | Automation/scripting (docs) |
| Python SDK | ✅ Available | Programmatic access (docs) |
| TypeScript SDK | Web/Node.js integration (docs) | |
| WebSocket | ✅ Available | Real-time bidirectional (docs) |
See Interface Enhancement Plan for details.
- Architecture Overview
- Agent Design (coming soon)
- Safety & Risk Management
- Quantum Integration (coming soon)
- Complete Enhancement Summary
- Phase 1: Validation
- Phase 2: Planning System
- Phase 3: Fundamental Analysis
- Integration Testing
- Security Module - TradeTrap-inspired AI defense
- Behavioral Finance - TwinMarket-inspired agent modeling
- API Reference
- CLI Guide
- SDK Overview
- Python SDK
- TypeScript SDK
- WebSocket Protocol
- Contributing Guide
# Run 1-year backtest
python core/main.py --backtest --start 2024-01-01 --end 2024-12-31
# Generate report
python core/main.py --report --output reports/2024.pdf# All safety tests
pytest tests/safety/ -v
# Specific tests
pytest tests/safety/test_risk_limits.py
pytest tests/safety/test_mev_protection.py
pytest tests/safety/test_policy_validator.pylocust -f tests/load/locustfile.py --host http://localhost:8000- Multi-agent orchestrator
- Freqtrade integration
- Quantum optimizer
- Telegram bot
- Enhancement phases 1-3 (validation, planning, fundamentals)
- ✅ Core component latency benchmarks (PostgreSQL, quantum, in-memory)
- ✅ Real-world throughput testing (1,700+ decisions/sec)
- ✅ Quantum vs classical performance comparison
- ✅ Production readiness validation (10-100x above targets)
- 📊 Full results
- ✅ Comprehensive test suite (437 tests, 89 integration tests)
- ✅ API workflow testing (proposal → approval → execution)
- ✅ Quantum integration validation
- ✅ Safety enforcer verification
- 📋 Test summary
- ✅ Python SDK prepared for PyPI (84% coverage, 13/13 tests passing)
- ✅ TypeScript SDK prepared for npm (52% coverage, 41/41 tests passing)
- ✅ Security audits complete (no vulnerabilities)
- ✅ Dual-format builds (CJS + ESM)
- 📦 Python SDK status | TypeScript SDK status
- ✅ PyPI-ready package configuration
- ✅ Installation script (normal, user, dev, pipx modes)
- ✅ Comprehensive CLI documentation (527 lines)
- ✅ Package structure optimization (17KB wheel, 19KB tarball)
- 🛠️ CLI packaging details
- ✅ CLI interface (
sigmaxcommand) - ✅ Python SDK (sigmax-sdk v1.0.0) - source install available
- ✅ TypeScript SDK (@sigmax/sdk v1.0.0) - source install available
- ✅ WebSocket support
- ✅ Enhanced documentation
⚠️ Requires security audit, legal review, regulatory compliance
- Live BTC/USDT only (paper trading verified first)
- Enhanced real-time monitoring
- Advanced slippage protection
- Manual approval workflow for high-risk operations
- Add ETH, SOL, ARB, BASE
- Memecoin scanner
- Leverage 2x (with safety)
- Advanced arbitrage
⚠️ Note: These are experimental research directions, not production commitments. Any implementation would require proper regulatory compliance and legal review.
- Multi-user support (research/educational environments)
- Strategy sharing & backtesting (non-commercial)
- Mobile monitoring app (read-only, educational)
- Self-hosted deployment guides
- Community governance (technical decisions only)
# Trading
EXCHANGE=binance
API_KEY=your_key
API_SECRET=your_secret
TESTNET=true
# LLM (Optional - uses Ollama by default)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-...
# Telegram
TELEGRAM_BOT_TOKEN=123456:ABC...
TELEGRAM_CHAT_ID=your_id
# Safety
MAX_DAILY_LOSS=10
MAX_POSITION_SIZE=15
STOP_LOSS_PCT=1.5
# Validation thresholds (optional)
MIN_RESEARCH_SUMMARY_LENGTH=20
MIN_TECHNICAL_ANALYSIS_LENGTH=20
# Quantum Computing (VQE/QAOA Portfolio Optimization)
QUANTUM_ENABLED=true # Enable quantum optimization (default: true)
QUANTUM_BACKEND=qiskit_aer # Quantum simulator backend
QUANTUM_SHOTS=1000 # Circuit executions (1000-10000)
# Database
POSTGRES_URL=postgresql://user:pass@localhost:5432/sigmax
REDIS_URL=redis://localhost:6379See .env.example for full configuration.
We welcome contributions! See CONTRIBUTING.md for guidelines.
# Pre-commit hooks
pre-commit install
# Run tests
pytest
# Lint
ruff check .
mypy core/
# Format
black core/ ui/api/MIT License - See LICENSE for details.
- Freqtrade: GPL-3.0
- Qiskit: Apache 2.0
- React: MIT
- Tauri: MIT/Apache 2.0
CURRENT STATUS: EDUCATIONAL AND RESEARCH SOFTWARE
SIGMAX (Phases 0-1) is research software for educational purposes. It is designed to explore autonomous AI trading concepts, multi-agent systems, and quantum optimization in a controlled environment.
- Trading Risk: Cryptocurrency trading involves substantial risk of total capital loss
- Not Financial Advice: SIGMAX does not provide investment, financial, or trading advice
- Your Responsibility: All trading decisions and outcomes are solely your responsibility
- Paper Trading First: Always test thoroughly in paper trading mode before considering any real funds
- Regulatory Compliance: Check your local regulations - automated trading may be restricted or prohibited in your jurisdiction
- No Warranty: Provided "as-is" without warranties of any kind (see LICENSE)
- No Liability: Developers and contributors assume no liability for financial losses or damages
While the roadmap includes exploratory phases (2-4), these are research directions only, not guarantees. Any progression beyond paper trading would require:
- Comprehensive security audits
- Regulatory compliance review
- Legal framework compliance
- Explicit user agreements
- Professional risk disclosures
✅ Appropriate Uses:
- Learning about AI trading systems
- Research on multi-agent architectures
- Backtesting trading strategies
- Paper trading and simulation
- Academic and educational purposes
❌ Not Recommended:
- Production trading without thorough testing
- Trading with funds you cannot afford to lose
- Relying on AI decisions without understanding them
- Circumventing regulatory requirements
BY USING THIS SOFTWARE, YOU ACKNOWLEDGE THESE RISKS AND AGREE TO USE IT RESPONSIBLY AT YOUR OWN RISK.
Built with: Freqtrade • Qiskit • LangChain • Tauri • React • Three.js
Inspired by: Soly_AI • FinRobot • AutoGPT • Metagpt • AI-Trader • TradeTrap • TwinMarket
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Discord: Join Community (coming soon)
Built with ❤️ by the SIGMAX Community