Helios

Disclaimer: This is a starter codebase for a multi-agent LLM-based trading framework. It is intended for educational and research purposes only. It is not production-ready for live trading and does not constitute financial advice. Use at your own risk.

Overview

Helios is a production-ready starter codebase for a multi-agent LLM-based cryptocurrency trading framework, inspired by the paper "TradingAgents: Multi-Agents LLM Financial Trading Framework" [1]. The framework is designed to be modular, extensible, and easy to use, providing a solid foundation for building sophisticated algorithmic trading strategies.

This implementation adapts the core concepts of the TradingAgents paper to the cryptocurrency markets, using fast-agent [2] for agent orchestration and Kraken [3] for market data. The goal is to create a clean and well-structured starting point that can be expanded with live execution, backtesting, and additional data sources.

Architecture Overview

The framework follows a multi-agent architecture that mirrors the collaborative dynamics of a real-world trading firm. Each agent has a specialized role, and their collective intelligence is synthesized to make a final trading decision. This approach promotes modularity, explainability, and robust decision-making.

Key Components

1. Analyst Agents: These agents are responsible for gathering and analyzing market data from different perspectives:

   • Technical Analyst: Analyzes OHLCV price data to identify trends, patterns, and technical indicators (RSI, MACD, moving averages).
   • Sentiment Analyst: Gauges market sentiment from social media and news (stubbed for future integration).
   • Fundamental Analyst: Assesses on-chain metrics and project fundamentals (stubbed for future integration).

2. Bull/Bear Researchers: These agents engage in a structured debate to construct bullish and bearish arguments based on the analyst reports. This adversarial process ensures that both sides of the trade are considered before making a decision, reducing confirmation bias.

3. Risk Manager: This agent assesses the trading opportunity against risk parameters, recommends position sizing (capped at 75% of capital), and sets risk constraints to ensure capital preservation.

4. Trader Agent: The final decision-maker, this agent synthesizes all the information from the analysts, the bull/bear debate, and the risk manager to produce a final, actionable trading decision: BUY, SELL, or HOLD.

5. Workflow Orchestrator: The TradingWorkflow class uses fast-agent to manage the entire process, running agents in parallel where appropriate and chaining them together in a logical sequence.

This multi-agent design, inspired by the division of labor in human financial institutions, allows for a more comprehensive and nuanced analysis of the market, leading to more robust and well-reasoned trading decisions.

Architectural Adaptations from TradingAgents to Crypto

The original TradingAgents framework was designed for equity markets, but Helios successfully translates its principles to cryptocurrency trading with the following adaptations:

Analyst Team: The framework includes three types of analysts, each adapted for crypto markets. The Technical Analyst is fully implemented and analyzes OHLCV data using indicators like RSI, MACD, and moving averages—techniques that are directly applicable to crypto. The Sentiment Analyst is designed to process social media and community sentiment, which is particularly important in crypto markets where social dynamics play a larger role than in traditional finance. The Fundamental Analyst has been reimagined to focus on crypto-specific metrics like on-chain data (network hash rate, active addresses, token supply) and project fundamentals (development activity, use case, adoption) rather than traditional financial statements.

Bull/Bear Debate Mechanism: This adversarial debate process from the original paper is preserved and enhanced. The bull and bear researchers construct opposing arguments based on the analyst reports, ensuring that both optimistic and pessimistic perspectives are considered. This debate runs for multiple rounds, allowing for deeper exploration of the trading opportunity.

Risk Management: The risk manager agent assesses trading decisions against volatility and market conditions, which is especially critical in crypto markets where price swings can be extreme. The framework enforces conservative position sizing and requires clear risk constraints before any trade is executed.

Trader Decision: The trader agent acts as the final decision-maker, synthesizing all inputs from analysts, the debate, and risk management to produce a clear, actionable decision with specific position sizing and detailed reasoning.

Integration with fast-agent and Kraken

The framework leverages fast-agent for all agent definitions and workflow orchestration. Each agent is defined using the @fast.agent() decorator with specific instructions, model configurations, and request parameters. The workflow uses fast-agent's async capabilities to run analyst agents in parallel (using asyncio.gather()), maximizing efficiency. The framework also demonstrates the use of different models for different tasks: fast models (like gpt-4.1-mini) for quick analysis and data retrieval, and deeper models (like gemini-2.5-flash) for complex reasoning and debate.

For market data, the framework implements a KrakenDataProvider that uses Kraken's public /0/public/OHLC REST API endpoint. This implementation includes symbol normalization (mapping common symbols like BTCUSD to Kraken's format XBTUSD), robust error handling, and clear documentation of Kraken's limitations (maximum 720 recent candles). The data provider is designed with an abstract interface, making it easy to add other data sources in the future.

Project Structure

helios/
├── README.md                              # This file
├── Architecture Documentation.md          # Detailed architecture documentation
├── requirements.txt                       # Python dependencies
├── fastagent.config.yaml                  # fast-agent MCP server configuration
├── settings.example.yaml                  # Example configuration file
│
├── docs/                                  # Documentation and research
│   ├── 2412.20138v7.pdf                  # TradingAgents paper
│   └── api_notes.md                      # API integration notes
│
├── src/                                   # Source code
│   ├── agents/                           # Agent definitions
│   │   ├── technical_analyst.py          # Technical analysis agent
│   │   ├── sentiment_analyst.py          # Sentiment analysis agent (stubbed)
│   │   ├── fundamental_analyst.py        # Fundamental analysis agent (stubbed)
│   │   ├── bull_researcher.py            # Bull researcher for debate
│   │   ├── bear_researcher.py            # Bear researcher for debate
│   │   ├── risk_manager.py               # Risk management agent
│   │   └── trader.py                     # Final trading decision agent
│   │
│   └── core/                             # Core modules
│       ├── schemas.py                    # Pydantic models for type-safe data structures
│       ├── state.py                      # State management for shared agent state
│       └── data_providers.py             # Kraken data provider implementation
│
├── workflows/                             # Workflow orchestration
│   └── multi_agent_workflow.py           # Main workflow orchestrator
│
└── run/                                   # Execution scripts
    ├── simulate_day.py                   # Run workflow for a single time step
    └── simulate_backtest.py              # Placeholder for backtesting implementation

Key Features

1. Modular and Extensible Design

The framework is built with modularity in mind. Each component is cleanly separated, with clear interfaces and minimal coupling. The abstract CryptoDataProvider interface makes it easy to add new data sources. The agent definitions are self-contained, making it straightforward to add new agents or modify existing ones.

2. Type-Safe Data Structures

All data passed between agents is validated using Pydantic models. This ensures type safety, catches errors early, and provides clear documentation of the data structures. The AgentState object serves as the central data container that flows through the workflow.

3. Async/Await Throughout

The entire framework is built on Python's async/await pattern, enabling efficient concurrent execution. Analyst agents run in parallel using asyncio.gather(), maximizing throughput. The workflow is designed to be non-blocking and scalable.

4. Multi-Model Strategy

Following the TradingAgents paper's recommendation, the framework uses different models for different tasks. Fast models are used for data analysis and retrieval, while deeper models are used for reasoning, debate, and final decision-making. This balances cost, latency, and quality.

5. Robust Error Handling

The Kraken data provider includes comprehensive error handling for HTTP errors, API errors, and data parsing errors. The workflow includes fallback logic for parsing LLM responses, ensuring the system can handle unexpected outputs gracefully.

6. Clear Documentation and TODOs

Every module includes detailed docstrings explaining its purpose and usage. Stubbed components (sentiment, fundamental) include clear TODOs outlining what needs to be implemented.

Getting Started

1. Installation

Clone the repository and install the required Python packages:

git clone https://github.com/nathandelcid/helios.git
cd helios
pip install -r requirements.txt

2. Configuration

Before running the framework, you need to configure your API keys and model preferences.

1. Copy the example configuration file:

   cp settings.example.yaml settings.yaml

2. Edit settings.yaml:

   llm_provider:
     provider: openai
     api_key: "YOUR_OPENAI_API_KEY"  # Your OpenAI or compatible API key
     models:
       fast_model: "gpt-4.1-mini"    # Model for quick analysis tasks
       deep_model: "gemini-2.5-flash" # Model for debate and reasoning
   
   kraken:
     # API keys are not needed for public market data but are included for future use
     api_key: "YOUR_KRAKEN_API_KEY"
     api_secret: "YOUR_KRAKEN_API_SECRET"

   You can also set your API keys as environment variables (OPENAI_API_KEY, KRAKEN_API_KEY, KRAKEN_API_SECRET), which will override the values in the config file.

3. Using Kraken for Market Data

The framework uses Kraken as the primary data provider for cryptocurrency market data. The KrakenDataProvider is implemented to fetch OHLC data from Kraken's public REST API.

Pair Naming

Kraken uses specific pair names that may differ from common tickers. The data provider includes a mapping for common pairs, but you may need to use Kraken's format directly.

• Bitcoin/USD: XBTUSD
• Ethereum/USD: ETHUSD
• Bitcoin/Tether: XBTUSDT

Data Limitations

It is important to be aware of a key limitation of Kraken's /0/public/OHLC endpoint: it returns a maximum of 720 recent data points. This is sufficient for real-time analysis but not for extensive historical backtesting. The simulate_backtest.py file includes notes on how to address this for a full backtesting implementation.

4. Running the Simulation

The simulate_day.py script provides an example of how to run the entire multi-agent workflow for a single time step. It fetches the latest market data, runs all the agents, and prints the final trading decision.

To run the simulation for the default pair (XBTUSD) and timeframe (60 minutes):

python -m run.simulate_day

You can also specify a different symbol, timeframe, or number of debate rounds:

python -m run.simulate_day --symbol ETHUSD --timeframe 15 --rounds 2

This will execute the full workflow and output the final decision along with the reasoning from the Trader agent.

Example Output

The script will print:

1. OHLC data fetching status
2. Analyst reports (technical, sentiment, fundamental)
3. Bull/bear debate arguments for each round
4. Risk assessment (risk level, position size)
5. Final trading decision (action, position size, confidence, reasoning)
6. Execution summary with timing

Component Details

Core Modules

src/core/schemas.py: Defines all Pydantic models used throughout the framework. Key models include OHLCData (candlestick data), AnalystReport (analyst output), DebateArgument (bull/bear arguments), RiskAssessment (risk manager output), TradingDecision (final trader output), and AgentState (shared state object). These models provide type safety, validation, and clear data structures.

src/core/state.py: Implements the StateManager class, which manages the shared state across all agents. It provides methods to add data (e.g., add_ohlc_data, add_analyst_report, add_bull_argument) and query the state (e.g., get_latest_price, get_analyst_summaries).

src/core/data_providers.py: Defines the CryptoDataProvider abstract interface and implements the KrakenDataProvider. The Kraken implementation fetches OHLC data from the /0/public/OHLC endpoint, handles symbol normalization, validates timeframe intervals, and includes robust error handling. It also documents Kraken's 720-candle limitation and includes commented placeholders for future authenticated trading endpoints.

Agent Definitions

Each agent file includes a detailed instruction prompt and helper functions for formatting input data:

src/agents/technical_analyst.py: Fully implemented technical analysis agent. Includes functions to calculate SMA, RSI, and format OHLC data with indicators. The instruction prompt guides the LLM to analyze technical indicators and identify trends.

src/agents/sentiment_analyst.py: Stubbed sentiment analysis agent with TODOs for integrating Twitter/X, Reddit, and news APIs. The instruction prompt is designed for sentiment analysis, but the data formatting function returns a placeholder message.

src/agents/fundamental_analyst.py: Stubbed fundamental analysis agent with TODOs for integrating on-chain data (Glassnode, IntoTheBlock) and development activity (GitHub API). The instruction prompt focuses on long-term value drivers.

src/agents/bull_researcher.py: Bull researcher agent that constructs bullish arguments based on analyst reports. Includes a helper function to format context with analyst summaries and current price.

src/agents/bear_researcher.py: Bear researcher agent that constructs bearish arguments. Can optionally receive the bull thesis to counter-argue against it.

src/agents/risk_manager.py: Risk management agent that assesses risk level, recommends position sizing (capped at 75%), and sets constraints. The instruction prompt emphasizes capital preservation.

src/agents/trader.py: Final decision-making agent that synthesizes all inputs and produces a BUY/SELL/HOLD decision with reasoning. The instruction prompt guides the LLM to respect risk constraints and be decisive but not reckless.

Workflow Orchestration

workflows/multi_agent_workflow.py: The core orchestration logic. The TradingWorkflow class defines all agents using fast-agent decorators, runs analysts in parallel, executes the bull/bear debate in rounds, runs risk assessment, and makes the final trading decision. It includes helper methods to parse LLM responses into Pydantic models and manages the entire workflow lifecycle.

Execution Scripts

run/simulate_day.py: Command-line script to run the workflow for a single time step. It handles configuration loading (from YAML or environment variables), argument parsing (symbol, timeframe, rounds), and execution timing. It prints a detailed summary of the final decision.

run/simulate_backtest.py: Placeholder script that outlines the steps needed to implement a full backtesting pipeline. It includes TODOs for handling Kraken's data limitations, implementing the backtesting loop, calculating performance metrics, and generating reports.

Extending the Framework

This codebase is designed to be a starting point. Here are some ways you can extend it:

1. Live Trading Integration

Implement authenticated Kraken endpoints for order placement, balance queries, and position management. The KrakenDataProvider includes placeholder comments for integrating Kraken's authenticated trading endpoints (/0/private/AddOrder).

2. Backtesting Engine

Build a robust backtesting pipeline that handles Kraken's 720-candle limitation (via trade aggregation or external data), calculates performance metrics (Sharpe ratio, max drawdown), and generates detailed reports. The simulate_backtest.py file outlines the steps needed.

3. Sentiment Data Integration

Integrate real-time sentiment data from Twitter/X API, Reddit API, and crypto news sources to enhance the sentiment analyst.

4. On-Chain Data Integration

Add on-chain analytics from Glassnode, IntoTheBlock, or similar providers to enhance fundamental analysis with metrics like network hash rate, active addresses, and token supply.

5. Advanced Workflows

Explore fast-agent's router, orchestrator, and MAKER patterns for more sophisticated agent coordination.

6. Portfolio Management

Extend the framework to manage a portfolio of multiple cryptocurrencies with diversification and rebalancing logic.

7. Reinforcement Learning

Use RL to optimize agent behavior and decision-making based on historical performance.

8. Additional Agents

Create new analyst agents with different specializations (e.g., an arbitrage agent, a news-specific agent, a volatility specialist).

9. Refine Agent Instructions

The prompts in the src/agents/ directory can be customized to improve agent performance and reasoning.

Future Enhancement Roadmap

The framework is designed as a starting point. Here are the key areas for future development:

1. Live Trading Integration: Implement authenticated Kraken endpoints for order placement, balance queries, and position management.

2. Backtesting Engine: Build a robust backtesting pipeline that handles Kraken's 720-candle limitation (via trade aggregation or external data), calculates performance metrics (Sharpe ratio, max drawdown), and generates detailed reports.

3. Sentiment Data Integration: Integrate real-time sentiment data from Twitter/X API, Reddit API, and crypto news sources.

4. On-Chain Data Integration: Add on-chain analytics from Glassnode, IntoTheBlock, or similar providers to enhance fundamental analysis.

5. Advanced Workflows: Explore fast-agent's router, orchestrator, and MAKER patterns for more sophisticated agent coordination.

6. Portfolio Management: Extend the framework to manage a portfolio of multiple cryptocurrencies with diversification and rebalancing logic.

7. Reinforcement Learning: Use RL to optimize agent behavior and decision-making based on historical performance.

Conclusion

Helios successfully translates the TradingAgents multi-agent architecture to cryptocurrency trading, providing a clean, modular, and extensible foundation for building sophisticated algorithmic trading strategies. It demonstrates best practices in software architecture, type safety, async programming, and LLM agent orchestration using fast-agent. The codebase is production-ready in the sense that it is well-structured, documented, and testable, though it requires additional work (live trading, backtesting, data integration) before being used in a real trading environment.

References

[1] Xiao, Y., Sun, E., Luo, D., & Wang, W. (2024). TradingAgents: Multi-Agents LLM Financial Trading Framework. arXiv preprint arXiv:2412.20138. https://arxiv.org/abs/2412.20138

[2] fast-agent Documentation. (2025). https://fast-agent.ai

[3] Kraken API Documentation. (2025). https://docs.kraken.com/api

---