Skip to content
Get packs

Guide · Open source

How to use ai-hedge-fund: install, run and paper trade

Updated · written with AI from the project's own documentation and checked against our catalogue data

ai-hedge-fund is an open-source Python proof of concept that uses AI agents, modeled on different investor styles, to explore how AI might make trading decisions. The project is for educational purposes only, and its README states the system does not actually make any trades. This guide shows you how to install the aihf command, add the API keys it needs, and use its paper trading and backtesting modes.

AI Hedge Fundvirattt/ai-hedge-fund · ★ 64.4k · MIT

Quick start

  1. 1Check prerequisites. Make sure Python is installed, plus one of pipx, uv or pip.
  2. 2Install the package. Run pipx install aihf, or use uv tool install aihf or pip install aihf.
  3. 3Launch the app. Run aihf from any directory to open the interactive terminal app.
  4. 4Enter API keys. When prompted, provide a Financial Datasets key and one supported model provider key. They are saved to ~/.hedge-fund/.env.
  5. 5Try backtesting. Open backtesting, choose a fund and the tickers for the run, then review the equity curve against its benchmark.
  6. 6Try paper trading. Build or highlight a fund, review the approval step, and run it through the next completed session to build its ledger.

What you need before you install

The project is installed as a Python package. The README lists Python, pipx, uv, or pip as the prerequisites.

The app needs two kinds of API key to function: a Financial Datasets API key for prices, fundamentals and earnings, and an API key for one supported AI model provider.

  • Python
  • pipx, uv, or pip
  • A Financial Datasets API key (financialdatasets.ai)
  • One model API key from Anthropic, OpenAI, DeepSeek, Google, xAI, Kimi, or TypeSafe (Jev)

Install ai-hedge-fund with pipx, uv or pip

The package is named aihf. The README recommends pipx. You can also use uv or pip into an environment of your choice.

Once installed, run the app from anywhere in the terminal.

  • With pipx: install the package, then run the command.
  • With uv: uv tool install aihf.
  • With pip: pip install aihf into the environment you want to use.
pipx install aihf aihf

Add your API keys

You do not need to configure anything up front. The app asks for keys the first time it needs them and saves them to ~/.hedge-fund/.env.

Keys exported in your shell always take priority over the saved file.

Use the interactive terminal app

Running aihf with no arguments launches the interactive terminal app. It has two modes: paper trading and backtesting.

Paper trading gives you simulated funds, each with a ledger of real market days and fake money. Each session is appended to a hash-chained ledger in ~/.hedge-fund/paper/<name>/. Before anything trades, an approval step shows the exact decision about to execute.

Backtesting replays a fund over history and draws its equity curve against a benchmark. Results are saved to ~/.hedge-fund/research/. Fund definitions live in ~/.hedge-fund/mandates/ and carry no tickers, so you pick the universe for each backtest.

  • Paper trading: highlight a fund to see its next run, press enter to run it through the next completed session, press s for session history.
  • Kill switch: h or r keys, as described in the README.
  • Backtesting: pick the tickers per run, then view the equity curve against the benchmark.
aihf

Run the project from source for development

If you want to study or change the code, the README shows a Poetry-based workflow: clone the repository, install dependencies, run the app, then run the tests.

The README asks contributors to keep pull requests small and focused.

git clone https://github.com/virattt/ai-hedge-fund.git cd ai-hedge-fund poetry install poetry run aihf poetry run pytest hedge_fund

What people use it for

  • Studying how multi-agent AI workflows are structured in a Python codebase
  • Replaying a simulated fund over historical market data in backtesting
  • Practising paper trading with simulated funds and a session ledger
  • Comparing how different investor-style agents would behave on the same tickers

Frequently asked questions

Is ai-hedge-fund free to use?

The project is released under the MIT License, as stated in its README. The app still needs a Financial Datasets API key and a key from a supported AI model provider to function.

Does ai-hedge-fund make real trades?

No. The README says the system does not actually make any trades. It is an educational proof of concept, and it is not intended for real trading or investment.

How do I install ai-hedge-fund?

Run pipx install aihf, then run aihf. The README also lists uv tool install aihf and pip install aihf as alternatives.

What API keys do I need?

You need a Financial Datasets API key for prices, fundamentals and earnings, plus one API key from Anthropic, OpenAI, DeepSeek, Google, xAI, Kimi, or TypeSafe (Jev). The app asks for them the first time it needs them.

Where are my API keys and results stored?

Keys are saved to ~/.hedge-fund/.env. Paper trading ledgers go to ~/.hedge-fund/paper/<name>/, and backtest results go to ~/.hedge-fund/research/.

What are good alternatives to ai-hedge-fund?

Comparable projects named in this directory are FinRL, TradingAgents, Freqtrade and Qlib. Each has a different focus, so check its documentation to see which fits your goal.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

ai-hedge-fund suits students, developers and hobbyists who are comfortable in a terminal and want to study multi-agent trading code or experiment with paper trading and backtesting. It is not suited to anyone expecting real returns or financial advice, or anyone who needs a no-code tool.

Install options & downloads