ContestTrade is an innovative multi-agent (Multi-Agent) trading framework. With ContestTrade you can easily build a dedicated AI trading team: just set the analysis time, and it will autonomously scan the whole market without human intervention, mine potential event-driven investment opportunities from massive data, and, through an internal selection mechanism, construct the most trustworthy investment portfolio for you.

ContestTrade is a multi-agent trading framework focused on event-driven stock selection. The system's goal is to automatically discover, evaluate, and track event-driven opportunities with investment value without human intervention, and finally output executable asset allocation recommendations.

Core features:

• Automatic stock selection: whole-market scanning and signal generation that automatically outputs tradable candidate stock lists without manual screening.
• Event-driven: triggered by catalysts such as news, announcements, capital flows, and policy; focuses on opportunities with significant information impact.
• Personalized configuration: supports user-defined agent research preferences and strategies to flexibly adapt to different investment styles.

The workflow of ContestTrade operates through a structured two-stage pipeline, simulating the dynamic decision-making process of an investment firm. This dual-contest framework ensures that final decisions are driven only by the most robust and effective insights, maintaining strong adaptability and resilience in complex markets.

1. Data Processing Stage: First, raw market data from multiple sources is fed into the Data Team. Multiple Data Analysis Agents work in parallel to refine this raw data into structured "textual factors." At this stage, the internal contest mechanism evaluates the potential value of the factors generated by each data agent and constructs an optimal "factor portfolio."

2. Research and Decision-Making Stage: This optimal factor portfolio is then passed to the Research Team. Multiple Research Agents, each with their unique "Trading Beliefs" and access to a powerful set of financial tools, conduct parallel, in-depth analyses of these factors and submit their respective trading proposals. A second round of internal contests then evaluates these proposals, ultimately synthesizing a unified and reliable asset allocation strategy as the final output.

# 1. Clone the project repository
git clone https://github.com/FinStep-AI/ContestTrade.git
cd ContestTrade

# 2. (Recommended) Create and activate a virtual environment
conda create -n contesttrade python=3.10
conda activate contesttrade

# 3. Install project dependencies
pip install -r requirements.txt

Or deploy with Docker:

docker run -it --rm --name contest_trade -v $(pwd)/config.yaml:/ContestTrade/config.yaml finstep/contesttrade:v2.0

Before running ContestTrade, you need to configure the necessary API keys and LLM parameters.

Edit the config_us.yaml file and enter your API keys. The table below lists all required and optional keys:

Note: You need to apply for the LLM API and VLM API by yourself. Fill in the URL, API Key, and model name according to the platform and model you use.

Each Research Agent corresponds to a "trading belief". The system will generate investment signals based on these beliefs combined with data and tools (each belief outputs up to 5 signals). The configuration file is located at contest_trade/config/belief_list.json, and its format is a JSON array of strings.

Example 1 — preference for short-term event-driven (more aggressive):

[
  "Focus on short-term event-driven opportunities: prioritize company announcements, M&A and restructuring, sudden order increases, technological breakthroughs and other catalysts; prefer mid/small-cap, high-volatility thematic stocks, suitable for aggressive arbitrage strategies."
]

Example 2 — preference for stable events (more conservative):

[
  "Focus on stable, high-certainty events: pay attention to dividends, buybacks, earnings forecast confirmations, major contract signings and policy tailwinds; prefer large-cap blue-chips with low volatility and high certainty, suitable for conservative allocation."
]

Default configuration:

[
  "Based on the provided information, comprehensively consider each company's business dynamics, industry trends and potential market impact. Recommend stock portfolios with short-term investment potential for two groups: Group 1 — risk-seekers (prefer high volatility, high returns, mid/low market cap stocks); Group 2 — conservative investors (prefer low volatility, stable returns, large-cap stocks).",
  "Based on recent sudden events, policy adjustments and company announcements as catalysts, combined with market sentiment transmission paths and capital game features. Screen event-driven opportunities for two different styles: Group 1 — aggressive arbitrage (prefer restructuring expectation, sudden order increases, technical breakthroughs in small-cap stocks); Group 2 — defensive arbitrage (prefer dividend increases, large buybacks, acquisition of franchise rights in blue-chip stocks). Pay attention to northbound capital movement and institutional seat trends on the trading leaderboard for resonance effects."
]

You can easily start ContestTrade using the Command Line Interface (CLI).

python -m cli.main run

After the program starts, you will enter the terminal interactive interface and can choose the market you want to analyze. The default analysis time is the current time.

After all agents have finished running, you can view the signals they provide in the results summary.

You can choose to view a more detailed research report.

You can also choose to view a more detailed data analysis report.

All the above reports will be saved in the contest_trade/agents_workspace/results directory in Markdown format for your future reference and sharing.

We firmly believe that the era of AGI is approaching, and we hope to leverage the power of the open-source community to explore new paradigms of quantitative trading in the AGI era.

The project is dedicated to developing more robust infrastructure and a wider variety of agents, exploring the boundaries of AI in financial trading, and creating a stable, trustworthy, and scalable agent trading framework.

V1.1 (Finished): Framework Stability Enhancement & Core Experience Optimization

• [✓] The core data source module is decoupled to achieve adaptors for multiple data sources. (data-provider refactor)
• [✓] Optimized CLI logging and interaction experience.

V2.0 (Finished): Market and Function Expansion

• [✓] Access to US stock market data.
• [✓] Introduced richer factors and signal sources.

Future Plans:

• Support for Hong Kong stocks and other markets
• Visual backtesting and analysis interface
• Support for scaling up more agents

ContestTrade is a community-driven open-source project, and we welcome contributions in any form!

If you are a developer, you can refer to our Contributing Guide (CONTRIBUTING.md) to become a contributor to ContestTrade.

We also value non-code contributions, including:

• Proposing feature suggestions or reporting bugs: Go to Issues page
• Providing feedback on your testing results: Including test results, user experience, etc.

Important Disclaimer: This project, ContestTrade, is an open-source quantitative trading research framework intended for academic and educational purposes only. The examples, data, and analysis results included in the project do not constitute any form of investment advice.

Risk Warning:

• Market Risk: This project does not constitute any form of investment, financial, legal, or tax advice. All outputs, including trading signals and analyses, are the results of AI model deductions based on historical data and should not be considered a basis for any buy or sell operations.
• Data Accuracy: The data sources used by the framework may be subject to delays, inaccuracies, or incompleteness. We do not guarantee the reliability of the data.
• Model Hallucination: AI models (including Large Language Models) have inherent limitations and are subject to the risk of "hallucination." We do not guarantee the accuracy, completeness, or timeliness of the information generated by the framework.
• Liability: The developers assume no liability for any direct or indirect losses resulting from the use of or inability to use this framework. Investing involves risks; enter the market with caution.

Before using this framework for any actual trading decisions, be sure to fully understand the associated risks.

If you use ContestTrade in your research, please cite our paper:

@misc{zhao2025contesttrade,
      title={ContestTrade: A Multi-Agent Trading System Based on Internal Contest Mechanism}, 
      author={Li Zhao and Rui Sun and Zuoyou Jiang and Bo Yang and Yuxiao Bai and Mengting Chen and Xinyang Wang and Jing Li and Zuo Bai},
      year={2025},
      eprint={2508.00554},
      archivePrefix={arXiv},
      primaryClass={q-fin.TR}
}

This project is licensed under the Apache 2.0 License.