HKUDS/Vibe-Trading

What it does

Vibe-Trading is a Python-based trading and research agent with a CLI, a React web app, an HTTP API and an MCP server. It turns finance questions into research reports, runnable backtests and paper portfolios, and can be authorized to place live orders through a supported broker within limits the user sets and can halt; funds stay with the broker. The project targets people doing equity, crypto, futures and options research who want an LLM-driven workflow with inspectable run records.

Core areas include market research (filings, 13F holdings, ETF look-through, DCF and comparable valuation), quant research (the Alpha Zoo across Qlib, Alpha101, GTJA and academic/fundamental libraries, multiple backtest engines, Options Lab, portfolio risk), paper trading with daily NAV tracking, an importing "Shadow Account" that replays a broker trade journal against rule-based alternatives, and 30 preset research teams for committee-style or scheduled briefs.

Quick start

Requirements: Python 3.11+ and a model provider with an API key. Terminal path:

pip install vibe-trading-ai
vibe-trading init
vibe-trading

The setup wizard selects a provider and model. Then try a backtest from the shell:

vibe-trading run -p "Backtest a BTC-USDT 20/50 moving-average crossover for 2024. Compare it with buy-and-hold and report maximum drawdown."

Results are saved as a run; open Run Detail to compare against buy-and-hold, inspect individual trades and check the data source recorded on the run card. The package bundles the CLI, API and MCP server. For the web app, clone the repository, copy agent/.env.example to agent/.env, set the provider and key, then run docker compose up --build and open http://localhost:8899.

For MCP clients such as Claude Desktop, add {"mcpServers": {"vibe-trading": {"command": "vibe-trading-mcp"}}} to the client config and restart it. The HTTP API can be started with vibe-trading serve --port 8899, exposing /runs, /sessions and interactive docs at /docs.

Data and market coverage

Market data comes from 28 configured sources with ordered fallback. With source: "auto", the market is inferred from the symbol: A-shares and Hong Kong start with Tencent then Eastmoney, US equities start with Yahoo then Stooq and Sina, crypto tries OKX, Binance and CCXT, and Chinese futures use AKShare or local bars. Global futures require locally supplied bars. Installing the ashare extra adds the token-free BaoStock loader for daily A-share bars; per-source credentials are documented in the data source reference.

Constraints

• Live trading is experimental and has not been verified against a real broker account by the maintainers; broker coverage differs by capability. 19 connectors are listed, but only some declare live order support (for example Alpaca, Binance, eToro, Futu, MT5, OKX, Robinhood and Tiger), and each profile has its own read, simulation and live permissions.
• Live orders only run within configured symbol, order and exposure limits, and a kill switch halts activity. Trading is not investment advice and past performance does not guarantee future results.
• Interactive and API workflows need an LLM provider key; sessions and settings should be protected accordingly.
• Not every market rule is universal: backtests refuse codes that no market rule recognizes rather than silently applying A-share rules.
• Licensed under MIT.

HotRepo's take

On HotRepo's daily all-language records Vibe-Trading moved from 13,555 stars on 2026-06-27 to 24,097 on 2026-07-16, with daily gains usually in the hundreds and peaks of 1,148 and 1,265 on July 13 and 14. There is then a gap in records until 2026-11-15, when a Python-language snapshot showed 38,281 stars with 83 gained and a best position of 14 on that language list. The project's own README also cites topic rankings from November 2026 (#1 in backtesting, #3 in algorithmic trading, #4 in quantitative finance), which are a separate measure from HotRepo's daily ranking. The repository's extensive PR history and contributor notes show continued correctness work on backtest semantics, data loaders and broker safety, which matters more for a trading tool than star momentum alone.

Project source and documentation