AgentX User Guide

A comprehensive guide to using the AgentX Crypto Trading Framework

Table of Contents

Introduction

Welcome to AgentX, a hierarchical agent-based system for cryptocurrency trading. This user guide will walk you through the setup, configuration, and operation of the AgentX system.

AgentX is designed to function like a professional hedge fund structure, with various AI agents working together to research, analyze, make decisions, and execute trades in the cryptocurrency market.

Getting Started

Installation

Before you begin, ensure your system meets the following requirements:

  • Python 3.10 or higher
  • Node.js 20.0 or higher
  • 8GB RAM minimum (16GB recommended)
  • Modern multi-core CPU
  • Internet connection for market data access

For detailed installation instructions, please refer to the Installation Guide.

Exchange API Setup

To use AgentX for live trading, you'll need to set up API access with supported cryptocurrency exchanges:

  1. Create accounts on supported exchanges (Binance, Coinbase, etc.)
  2. Generate API keys with trading permissions
  3. Add API keys to your configuration file
For security reasons, we recommend creating API keys with IP restrictions and only the minimum required permissions.

System Configuration

Configuration File Structure

The main configuration file is located at config/local.json. Here's an overview of the key sections:

{
  "system": {
    "name": "AgentX Trading System",
    "update_interval": 1.0,
    "log_level": "INFO"
  },
  "agents": {
    "executive": {
      "chief_coordinator": {
        "update_frequency": 0.5,
        "allocation_limits": {
          "max_per_asset": 0.2,
          "max_per_strategy": 0.3
        }
      },
      "risk_manager": {
        "update_frequency": 0.5,
        "risk_limits": {
          "max_drawdown": 0.1,
          "max_volatility": 0.2,
          "max_correlation": 0.7
        }
      },
      "performance_analyst": {
        "update_frequency": 0.5,
        "metrics": ["returns", "sharpe", "drawdown", "win_rate"]
      }
    },
    "strategy": {
      // Strategy agent configurations...
    },
    "execution": {
      // Execution agent configurations...
    }
  },
  "exchanges": {
    "binance": {
      "api_key": "YOUR_API_KEY",
      "api_secret": "YOUR_API_SECRET"
    },
    "coinbase": {
      "api_key": "YOUR_API_KEY",
      "api_secret": "YOUR_API_SECRET"
    }
  },
  "assets": {
    "monitored_pairs": [
      "BTC/USDT", "ETH/USDT", "BNB/USDT", "SOL/USDT", "ADA/USDT"
    ]
  }
}

Important Configuration Parameters

System Settings

  • update_interval: How frequently the system updates (in seconds)
  • log_level: Logging verbosity (DEBUG, INFO, WARNING, ERROR)

Risk Parameters

  • max_drawdown: Maximum allowed drawdown before risk alerts trigger
  • max_volatility: Maximum allowed portfolio volatility
  • max_correlation: Maximum allowed correlation between assets

Allocation Limits

  • max_per_asset: Maximum allocation to any single asset
  • max_per_strategy: Maximum allocation based on a single strategy

Exchange Settings

  • api_key: Your exchange API key
  • api_secret: Your exchange API secret

Using the Dashboard

Accessing the Dashboard

Once the system is running, access the dashboard at:

http://localhost:5000

Dashboard Sections

Overview

The main dashboard page provides a high-level overview of system status, including:

  • System status (running/stopped)
  • Uptime
  • Active agents count
  • Performance summary
  • Active trades
  • Recent alerts
Dashboard Overview

Agents

The Agents section displays the status of all agents in the system:

  • Agent ID
  • Agent type
  • Current status
  • Actions (restart)

Performance

The Performance section shows detailed trading performance metrics:

  • Returns over time
  • Drawdowns
  • Sharpe ratio
  • Win rate
  • Volatility

Trades

The Trades section displays:

  • Active trades
  • Trade history
  • Trade statistics
  • Execution performance

Portfolio

The Portfolio section shows:

  • Current asset allocation
  • Asset performance
  • Historical allocation changes

Alerts

The Alerts section displays:

  • Risk alerts
  • System alerts
  • Performance alerts

Settings

The Settings section allows you to configure:

  • Risk parameters
  • Allocation limits
  • Execution settings
  • System settings

Dashboard Controls

System Controls

  • Start: Start the trading system
  • Stop: Stop the trading system
  • Restart: Restart the trading system

Agent Controls

  • Restart Agent: Restart a specific agent

Trading Operations

Starting Trading

  1. Configure your system parameters in the configuration file
  2. Start the system:
    python src/main.py
  3. Access the dashboard and click "Start" to begin trading

Monitoring Trades

  1. Navigate to the "Trades" section of the dashboard
  2. View active trades and trade history
  3. Monitor execution performance

Risk Management

  1. Set appropriate risk parameters in the configuration file
  2. Monitor the "Alerts" section for risk warnings
  3. Adjust parameters as needed through the Settings page

Performance Analysis

  1. Navigate to the "Performance" section of the dashboard
  2. Analyze returns, drawdowns, and other metrics
  3. Export performance reports for further analysis

Troubleshooting

Common Issues

System Won't Start

  • Check log files in the logs directory
  • Verify configuration file syntax
  • Ensure all dependencies are installed

API Connection Errors

  • Verify API keys are correct
  • Check internet connection
  • Ensure exchange is operational

Agent Failures

  • Check agent-specific logs
  • Restart the problematic agent
  • Check for configuration issues

Logging

Log files are stored in the logs directory:

  • system.log: Main system log
  • agents/*.log: Individual agent logs
  • dashboard.log: Dashboard server log

Advanced Usage

Adding Custom Agents

  1. Create a new agent class that extends the appropriate base class
  2. Implement required methods (update, handle_message, etc.)
  3. Register the agent in the system configuration
from src.strategy.base_strategy import BaseStrategyAgent
from src.protocols import MessageType, AgentType

class MyCustomStrategyAgent(BaseStrategyAgent):
    def __init__(self, agent_id, router, config_file=None, logger=None):
        super().__init__(
            agent_id=agent_id,
            agent_type=AgentType.CUSTOM_STRATEGY,
            router=router,
            config_file=config_file,
            logger=logger
        )
        
    def update(self):
        # Custom strategy logic here
        pass
        
    def handle_market_data(self, message):
        # Process market data
        pass
        
    def generate_signals(self):
        # Generate trading signals
        recommendation = {
            "asset": "BTC/USDT",
            "action": "buy",
            "confidence": 0.8,
            # Additional details...
        }
        
        # Send recommendation to chief coordinator
        self.broker.send(
            to="chief_coordinator",
            message_type=MessageType.TRADE_RECOMMENDATION,
            content={"recommendation": recommendation}
        )

Customizing Strategies

  1. Modify strategy agent parameters in the configuration file
  2. Create custom strategy implementations by extending base classes
  3. Implement custom indicators and signal generation logic

Backtesting

  1. Set the system to backtesting mode in the configuration
  2. Provide historical data sources
  3. Run the system and analyze performance in the dashboard

Security Considerations

  • Store API keys securely
  • Use read-only API keys when possible
  • Set appropriate trading limits
  • Monitor system regularly
  • Keep software updated
Never share your API keys or configuration files containing sensitive information.

Support and Resources

  • GitHub Issues: Report bugs and request features
  • Documentation: Refer to the docs directory for detailed documentation
  • Community: Join our community forum for discussions and support