AI Hedge Fund (aihf): LLM investor agents, hash-chained paper ledgers and a trading app that never trades

Paper funds run on real market days and fake money, and nothing reaches a broker

AI Hedge Fund is a proof of concept for using AI to make trading decisions, released for educational and research purposes only. The system does not actually make any trades. That framing shapes every feature. The paper trading mode gives each fund a ledger of real market days and fake money, so you see how a strategy would have acted on actual sessions without capital at risk. The disclaimer is blunt: the project is not intended for real trading or investment, offers no investment advice or guarantees, and its creator assumes no liability for financial losses. The consequence for readers is simple. If you came looking for a bot that connects to a brokerage and places orders, this is not it, and nothing in the app is built to do that. What it offers is a sandbox for watching LLM investor agents and quant alpha models reason about tickers, then measuring the result on paper.

One package, aihf, installed with pipx, uv or pip

The app is published as the aihf package and needs Python 3.11 or newer (the pyproject sets python = "^3.11"). The recommended install puts it in its own isolated environment:

pipx install aihf

uv tool install aihf works the same way, and pip install aihf puts it into an environment of your choice. After that, a single command launches it from any directory:

aihf

The aihf command maps to hedge_fund.run:main. With no arguments it opens the interactive terminal app, which is built on Textual. The choice of installer matters mostly for upgrades and conflicts: pipx and uv tool keep aihf's pinned dependencies, such as langchain-anthropic 0.3.5 and python-dotenv 1.0.0, away from your other projects, while a plain pip install into a shared environment can collide with other versions of those same libraries.

Keys are prompted on first use and saved to ~/.hedge-fund/.env, but shell exports win

There is nothing to configure before the first run. The app asks for each key the first time it needs one and saves it to ~/.hedge-fund/.env. A .env in your working directory also works, and .env.example in the repository shows every variable. Two kinds of keys are required. One is market data: a Financial Datasets key in FINANCIAL_DATASETS_API_KEY for prices, fundamentals and earnings. The other is a single model API key for the investor agents. Supported providers are Anthropic, OpenAI, DeepSeek, Google, xAI, Kimi and TypeSafe; for TypeSafe you select Jev in the model picker or pass --model jev-1.13.0. One LLM key is enough. The rule to remember is precedence: keys exported in your shell always win over the saved file. If you rotate a key through the app's prompt but an old value is still exported in your shell profile, the app keeps using the old one, and the fix is in your shell, not in ~/.hedge-fund/.env.

Paying for data with an x402 wallet caps history at 365 days

Instead of a Financial Datasets API key, the app can pay per call with x402 from a Base wallet holding USDC. That route needs the optional extra:

pip install 'aihf[x402]'

You then set X402_WALLET_PRIVATE_KEY, and every data call pays for itself. The tradeoffs are spelled out. x402 serves only the last 365 days of data, and only for non-professional use. If both the API key and the wallet are set, the API key is used. The project advises using a small, separate wallet. Two consequences follow. First, a backtest that needs more than a year of history will not get it on the wallet route, so long replays require the API key. Second, the wallet's private key ends up in the same .env file as your model keys, which is exactly why a dedicated wallet with a small balance is the sensible setup rather than your main one.

Every paper session is appended to a hash-chained ledger, so NAV cannot be reset

In paper trading mode, each fund sits in a list. Highlighting a fund shows what its next run will do. Pressing enter runs it through the next completed session, and an approval step shows the exact decision about to execute before anything is recorded. The s key opens the fund's full session history, and h or r trigger the kill switch. New funds are built from the same list by choosing strategies, capital, cadence and tickers. Every session is appended to a hash-chained ledger under ~/.hedge-fund/paper/<name>/. The point is that net asset value becomes a track record rather than a number you can quietly restart. The cost is the same property seen from the other side: a fund that went badly stays on the record, and the way to start over is a new fund, not an edit to the old ledger.

Fund mandates carry no tickers, so each backtest picks its own universe

The second mode, backtesting, replays a fund over history and draws its equity curve against a benchmark. Results are saved to ~/.hedge-fund/research/. Fund definitions, called mandates, live in ~/.hedge-fund/mandates/ and deliberately carry no tickers; you choose the universe each time you run a backtest. This separation lets one strategy be tested across different sets of stocks without copying the definition. It also means a backtest result is only meaningful together with the universe you picked for it. Two runs of the same mandate on different tickers are different experiments, and comparing their curves without noting the universe compares unlike things. On the x402 data route the replay window is also limited to the last 365 days, which narrows how far back any of these experiments can go.

Three patch releases in a week, and a Poetry plus Textual dev loop

The project moves fast. Version 2.6.2 shipped on 2026-10-27, 2.6.3 on 2026-10-30 and 2.6.4 on 2026-11-01, and the last push to main was on 2026-11-02. Contributors work from a clone with Poetry:

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

The Makefile adds a dev target that runs the app under Textual's dev tools through watchfiles: app.tcss reloads live, any change under hedge_fund/ restarts the app, and print and log output go to a separate console target in a second terminal. Pull requests are asked to stay small and focused, and feature requests go in issues tagged enhancement. For users, the release pace means pipx or uv upgrades arrive often; checking the version before comparing results with someone else avoids comparing two different builds.

Editorial conclusion

AI Hedge Fund suits developers and students who want to see how LLM investor agents and quant models behave on paper and over history, and who are comfortable paying for a Financial Datasets key and one model provider. It is the wrong tool for anyone who wants an account that places real orders: the system does not trade, and the project disclaims any investment use. Before running it, decide whether you will use an API key or an x402 wallet for data, keep any wallet small and separate, and check which keys are exported in your shell, because those override the saved file.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes