🚀 Augustan Trading System

The ultimate futures trading and position sizing tool with intelligent risk management, multi-exchange support, automated signal generation, and comprehensive testing framework.

📚 Complete Documentation

For comprehensive documentation including core components, CLI commands, testing framework, and development guide, see:

📖 AUGUSTAN_COMPLETE_GUIDE.md

This guide covers everything you need to know about the Augustan Trading System.

🚀 Quick Start

# Install everything
pip install -r requirements.txt

# Test installation
python -m trading_system.cli --help

# Run tests
python run_tests.py

# Start paper trading
python -m trading_system.cli paper start --balance 10000

✨ Key Features

💰 Intelligent Position Sizing

• Budget-Based Filtering: Only shows symbols you can actually afford to trade
• Risk-Based Calculation: Positions sized based on your risk tolerance (e.g., 0.2% per trade)
• Exchange Limits Compliance: Respects minimum notional values and position sizes
• Liquidation Safety: Ensures sufficient buffer against liquidation (1.5x+ safety ratio)

📊 Multi-Exchange Volume Analysis

• 5 Major Exchanges: Binance, Bybit, OKX, Bitget, Gate.io
• Real-Time Data: Live volume metrics and market rankings
• Smart Filtering: Volume-based market selection with customizable thresholds
• Enhanced Analysis: Combines volume data with position sizing for optimal symbol selection

📈 Advanced Trading Signals

• RSI Strategy: Relative Strength Index with customizable parameters
• MACD Strategy: Moving Average Convergence Divergence signals
• Multi-Timeframe: 1m, 5m, 1h, 4h, 1d analysis
• Confidence Scoring: Signal strength assessment for better decision making

🤖 Automated Job System

• Daily Volume Jobs: Automated daily market analysis
• Scheduled Execution: Set and forget automation
• Performance Tracking: Historical analysis and performance metrics
• Alert System: Notifications for significant market changes

🛠️ Installation

Quick Install (Recommended)

pip install -e .

After installation, the aug command will be available globally:

aug --help

Development Install

git clone https://github.com/augustan-trading/augustan.git
cd augustan
pip install -e .

Requirements

• Python 3.8+
• Internet connection for exchange APIs
• 50+ MB free disk space

🚀 Quick Start

1. Find Tradeable Symbols for Your Budget

aug position tradeable --budget 50

Result: List of symbols you can safely trade with $50.

2. Analyze Specific Symbol Position Sizing

aug position analyze --symbol DOGE/USDT  # Auto-fetches budget from wallet

Result: Detailed position sizing analysis with safety metrics.

3. Enhanced Volume Analysis with Position Sizing

aug volume analyze --enhanced --budget 50 --risk-percent 0.2

Result: Volume analysis + position sizing for top symbols.

4. Generate Trading Signals for Affordable Symbols

aug trading analyze --use-tradeable --budget 50

Result: RSI/MACD signals only for symbols within your budget.

📊 Real Example Output

$ aug position analyze --symbol DOGE/USDT  # Auto-fetches budget from wallet

📊 Position Sizing Analysis for DOGE/USDT
============================================================
Current Price: $0.2108
Stop Loss: $0.2066 (-2.0%)
Budget: $50.00 USDT
Risk per Trade: 0.5%
Leverage: 5x

✅ TRADEABLE
Position Size: 59.297913 DOGE
Position Value: $12.50
Required Margin: $2.50
Risk Amount: $0.25
Liquidation Price: $0.1695
Safety Ratio: 9.80x
============================================================

🎯 Core Commands

Position Sizing

# Analyze specific symbol
aug position analyze --symbol BTC/USDT --budget 100

# Find tradeable symbols
aug position tradeable --budget 50 --limit 20

# Custom risk settings
aug position analyze --symbol ETH/USDT --budget 200 --risk-percent 1.0 --leverage 10

Volume Analysis

# Basic volume analysis
aug volume analyze

# Enhanced with position sizing
aug volume analyze --enhanced --budget 50 --risk-percent 0.2

# Specific exchanges
aug volume analyze --exchanges bybit --min-volume 5000000

Trading Signals

# Generate signals for top volume symbols
aug trading analyze

# Use only tradeable symbols
aug trading analyze --use-tradeable --budget 50

# Custom timeframe and strategies
aug trading analyze --timeframe 1h --strategies rsi macd

Job Management

# Start daily volume job
aug job start --schedule

# Run job once
aug job run

# Check job status
aug job status

Configuration

# Show current config
aug config show

# Validate config
aug config validate

⚙️ Configuration

The Augustan Trading System uses 3 specialized configuration files for different trading modes and scenarios:

📋 Configuration Files Overview

File	Purpose	When Used
config/exchanges_config.json	Exchange APIs & Basic Settings	Analysis, Jobs, General Operations
config/paper_trading_config.json	Paper Trading Simulation	Learning & Testing
config/live_trading_config.json	Live Trading Settings	Real Money Trading

🔧 1. Exchange Configuration (exchanges_config.json)

Controls: Exchange connections, API credentials, and base system settings.

{
  "binANCE": {
    "spot": {
      "api_key": "your_spot_api_key",
      "secret": "your_spot_secret",
      "enabled": true,
      "testnet": true
    },
    "futures": {
      "api_key": "your_futures_api_key", 
      "secret": "your_futures_secret",
      "enabled": true,
      "testnet": true
    }
  },
  "volume_settings": {
    "min_volume_usd_24h": 1000000,    // Minimum $1M daily volume
    "min_volume_rank": 200,           // Only top 200 coins by volume
    "max_markets_per_exchange": 100   // Max 100 markets per exchange
  },
  "job_settings": {
    "schedule_time": "09:00",         // Daily analysis at 9 AM
    "retention_days": 30,             // Keep data for 30 days
    "output_directory": "volume_data"  // Where to save analysis results
  },
  "signal_generation": {
    "rsi_period": 14,                // RSI calculation period
    "rsi_oversold": 30,              // RSI buy threshold
    "rsi_overbought": 70,            // RSI sell threshold
    "macd_fast": 12,                 // MACD fast EMA
    "macd_slow": 26,                 // MACD slow EMA
    "macd_signal": 9,                // MACD signal line
    "min_signal_strength": 0.7,      // Minimum signal confidence
    "signal_cooldown_minutes": 30     // Time between signals
  }
}

📝 2. Paper Trading Configuration (paper_trading_config.json)

Purpose: Conservative settings for safe learning and testing.

💰 Risk Management (Learning-Friendly):

{
  "risk_management": {
    "default_budget": 100.0,          // Small $100 budget for learning
    "max_risk_per_trade": 0.01,       // Only 1% risk per trade
    "min_safety_ratio": 2.0,          // 2x safety margin required
    "default_leverage": 3,            // Conservative 3x leverage
    "max_position_percent": 0.05,     // Max 5% of portfolio per position
    "stop_loss_percent": 2.0,         // 2% stop loss
    "take_profit_percent": 4.0,       // 4% take profit
    "max_positions": 3,               // Max 3 concurrent positions
    "emergency_stop_loss": 5.0        // Emergency stop at 5% loss
  },
  "data_fetching": {
    "max_retries": 3,                // Fewer retries for stability
    "retry_delay": 1.0,              // Longer delays
    "timeout_seconds": 30            // Longer timeouts
  },
  "trading_mode": "paper"
}

📈 Signal Generation (Conservative):

{
  "signal_generation": {
    "rsi_oversold": 30,              // Conservative RSI levels
    "rsi_overbought": 70,
    "min_signal_strength": 0.7,      // Higher confidence required
    "signal_cooldown_minutes": 30     // Longer cooldown periods
  }
}

🚀 3. Live Trading Configuration (live_trading_config.json)

Purpose: Aggressive settings for production trading with real money.

💰 Risk Management (Production-Ready):

{
  "risk_management": {
    "default_budget": 5000.0,         // Larger $5000 budget
    "max_risk_per_trade": 0.02,       // 2% risk per trade
    "min_safety_ratio": 1.5,          // Lower safety margin (aggressive)
    "default_leverage": 5,            // Higher leverage
    "max_position_percent": 0.1,      // Up to 10% per position
    "max_positions": 5,               // More concurrent positions
    "emergency_stop_loss": 10.0       // Higher emergency stop
  },
  "volume_settings": {
    "min_volume_usd_24h": 5000000,    // Higher volume requirement ($5M)
    "min_volume_rank": 100,           // Only top 100 coins
    "max_markets_per_exchange": 50    // Fewer markets for quality focus
  },
  "signal_generation": {
    "rsi_oversold": 25,              // More extreme RSI levels
    "rsi_overbought": 75,
    "min_signal_strength": 0.6,      // Lower confidence threshold
    "signal_cooldown_minutes": 15     // Faster signal generation
  },
  "trading_mode": "live"
}

🎯 Configuration Comparison

Setting	Paper Trading	Live Trading	Purpose
Budget	$100	$5000	Learning vs Production
Risk per Trade	1%	2%	Conservative vs Aggressive
Safety Ratio	2.0x	1.5x	More vs Less Safety
Max Positions	3	5	Fewer vs More Trades
RSI Levels	30/70	25/75	Conservative vs Aggressive
Signal Cooldown	30 min	15 min	Slower vs Faster Trading
Testnet	✅ Yes	❌ No	Safe Testing vs Real Money

🛠️ Configuration Usage

For Learning/Testing:

# Automatically uses paper_trading_config.json
python3 -m trading_system.cli paper start --balance 1000

For Live Trading:

# Automatically uses live_trading_config.json  
python3 -m trading_system.cli live start --symbols BTC/USDT --balance 5000

For Analysis:

# Automatically uses exchanges_config.json
python3 -m trading_system.cli volume analyze --enhanced

⚙️ Configuration Override

The system automatically selects the right config based on trading mode:

• Paper Trading: Uses paper_trading_config.json
• Live Trading: Uses live_trading_config.json
• Analysis/Jobs: Uses exchanges_config.json

💡 Pro Tip: Start with paper trading config for safe learning, then switch to live trading config when ready for real money trading!

🔧 Advanced Usage

Position Sizing System

The position sizing system implements sophisticated risk management:

1. Budget Filtering: min_feasible_notional = max(exchange_min_notional, min_qty * current_price)
2. Risk Calculation: position_size = risk_amount / (entry_price - stop_loss_price)
3. Liquidation Safety: safety_ratio = liquidation_buffer / risk_buffer (minimum 1.5x)
4. Exchange Compliance: All positions respect exchange minimum requirements

Safety Guidelines

• Never risk more than 2% per trade
• Maintain 1.5x+ safety ratio (liquidation protection)
• Start with small budgets ($25-50) and conservative risk (0.2-0.5%)
• Use stop-losses religiously
• Test with paper trading first

📈 Performance Examples

Expected Results for Different Budgets:

• $50 Budget: ~5-10 tradeable symbols from top 50 volume markets
• $200 Budget: ~15-25 tradeable symbols from top 50 volume markets
• $500 Budget: ~30-40 tradeable symbols from top 50 volume markets

Live Performance Metrics:

• ✅ Real-time Analysis: Position sizing calculated in seconds
• ✅ Exchange Integration: Fetches live limits from major exchanges
• ✅ Safety Validation: Proper liquidation risk assessment
• ✅ Budget Compliance: Accurate affordability filtering

🐍 Python API Usage

from trading_system import PositionSizingCalculator, RiskManagementConfig, ExchangeLimitsFetcher

# Initialize components
risk_config = RiskManagementConfig(max_budget=50.0, max_risk_per_trade=0.002)
calculator = PositionSizingCalculator(risk_config)
limits_fetcher = ExchangeLimitsFetcher()

# Analyze position sizing
limits = limits_fetcher.fetch_symbol_limits("binance", "DOGE/USDT")
result = calculator.analyze_position_sizing(inputs)

print(f"Tradeable: {result.is_tradeable}")
print(f"Safety Ratio: {result.safety_ratio:.2f}x")

🔬 Development

Setup Development Environment

git clone https://github.com/augustan-trading/augustan.git
cd augustan
pip install -e ".[dev]"

Run Tests

python -m pytest tests/

Code Formatting

black augustan/
flake8 augustan/
mypy augustan/

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: This README and built-in help (aug --help)
• Issues: GitHub Issues
• Discussions: GitHub Discussions

⚠️ Disclaimer

This software is for educational and research purposes only. Trading cryptocurrencies involves substantial risk and may not be suitable for all investors. Past performance is not indicative of future results. Always do your own research and consider your risk tolerance before trading.

---

Built with ❤️ for the crypto trading community

Start trading smarter, not harder with Augustan! 🚀📈💰