Tutorial · Beginner Guide
This guide is for readers with no finance training and little trading experience. It does not teach you a “can’t-lose strategy”. Instead, it explains what factors, strategies, backtests, data sources, broker connectors and Shadow Account are in Vibe-Trading, and how to start using them in a safe order.
To begin with, think of Vibe-Trading as a workbench for trading research. You ask a question in plain language, and the project breaks it into steps: reading data, computing factors, writing a strategy, backtesting, reporting and connecting to accounts. It is not a broker and it never holds your money. Its real value is that every research step can be run, checked again later, and kept.
You ask a question, for example “backtest a momentum strategy on a set of large-cap stocks”.
Loaders fetch market data for stocks, crypto, futures, forex and more.
Factor or strategy code turns the data into buy and sell signals.
The backtest engine simulates the trades under that market’s rules.
Out come metrics, charts, a report, a run card and artifacts you can check again.
agent/backtest/loaders/ handles price and financial data. For each type of market it picks a public source, an optional source that needs a key, a source behind a broker gateway, or your own local files, and falls back to another source where one is available.
agent/src/factors/ ships 462 alphas. A factor is a numeric signal that scores stocks. It is not an order rule, and it is not a promise of returns.
agent/backtest/ runs simulated trading from config.json and code/signal_engine.py. Stocks, crypto, futures, forex and multi-asset portfolios each have their own engines.
agent/src/trading/ puts every broker behind the same set of profiles: account, positions, orders, quotes, historical bars, placing orders and cancelling them. This is different from a loader: a loader reads market data, while a connector reads, or acts on, your brokerage account.
agent/src/tools/ exposes these capabilities as tools the agent can call, such as backtest, factor_analysis, trading_positions and analyze_trade_journal.
agent/src/shadow_account/ pulls your habits out of your trade history as rules, backtests a “rule-based version of you”, and then works out where and why it differs from your real trades.
Put the jargon into everyday words first, and the code becomes much easier to read. The terms below come up again and again in the README, the Alpha Zoo, backtests and broker connectors.
| Term | In plain English | Where it lives in the project |
|---|---|---|
| Symbol / instrument | The thing you research or trade, such as AAPL.US, BTC-USDT or 600519.SH. |
codes in the backtest config; symbol in the broker tools. |
| Bar (candlestick) / OHLCV | The opening, highest, lowest and closing price, plus the volume traded, over one period of time. | The basic price columns a loader returns: open/high/low/close/volume. |
| VWAP | Volume-weighted average price. Roughly, “the average price the market actually traded at during this period”. | Some alphas need a vwap column. |
| amount | Turnover in money: the value traded, usually price times volume. | Used by some volume, liquidity and short-horizon factors; some stock data sources provide it. |
| Factor / alpha | A formula that scores a group of stocks. A high score might mean a stock is more worth buying, or more worth selling; that has to be checked with IC, backtests and an economic explanation. | agent/src/factors/zoo/. |
| Strategy | Turns signals into trading rules: what to buy, how much, when to sell, how many positions to hold at most, and how to cut losses. | signal_engine.py and the backtest config. |
| Signal Engine | The Python class that holds a strategy’s logic in this project. It reads bars or a panel and outputs target positions or buy and sell signals. | code/signal_engine.py in a backtest run dir. |
| Backtest | Uses historical data to simulate “what would have happened if I had traded by these rules back then”. It can only show past performance; it cannot prove future returns. | agent/backtest/runner.py and each market’s engine. |
| IC | Information Coefficient. Here it is the Spearman correlation between how a factor ranks stocks on a given day and how those stocks later rank by return. A positive IC means high-scoring stocks were more likely to go up afterwards. | compute_ic_series(). |
| IR | Mean IC divided by the volatility of IC. Roughly, “how steady is this factor?” | One of the ranking metrics in alpha bench. |
| lookahead | Peeking at future data: for example, using information only known after today’s close while pretending you knew it before today’s open. | Factor operators forbid a negative shift; backtests execute on the next bar to reduce the risk of peeking. |
| PIT | Point-in-time: using only data that was already public and available at that moment. | Financial fields, Shadow Account entry context and backtest validation all stress this boundary. |
| warmup | At the start of a rolling window there is not enough data yet. For example, a 20-day moving average has no valid value for the first 19 days. | min_warmup_bars in alpha metadata. |
| NaN | A missing value. In financial data a missing value is not 0; it often means a trading halt, a gap in the data source, or a window that is not full yet. | Factor operators keep NaN and never silently fill it with 0. |
| Slippage | The gap between the price you wanted to trade at and the price you actually got. | Each market engine has its own simplified slippage parameters. |
| Drawdown | How far the account’s value falls from a peak to a low. Maximum drawdown is a key measure of how painful a strategy is to live with. | Backtest metrics. |
| benchmark | The yardstick you compare against, such as the CSI 300, the Hang Seng Index or SPY. A strategy is judged not only on whether it made money, but also on whether it beat its yardstick. | The backtest report and its benchmark comparison. |
| paper / live | Paper is a simulated account; live is a real account. Be very careful with a real account. | environment in a connector profile. |
| mandate | The limits you authorize for live trading: which instruments may be traded, how large a single order may be, the maximum total exposure, how many trades are allowed per day, and so on. | The risk gate on the live-order path. |
Factors are the part of Vibe-Trading that most often confuses readers without a finance background. Think of a factor as a “ranking formula”: every day it gives each of many stocks a score, and then you check whether the high-scoring group went on to do better.
Important: a factor is not a strategy. A factor only answers “which instrument scores higher”. A strategy also has to answer how much to buy, when to buy, when to sell, what the trading costs are, whether concentrated positions are allowed, and whether the orders could actually be filled.
The Alpha Zoo in the current repository holds 462 alphas in five zoos:
| Zoo | Count | How to think about it |
|---|---|---|
academic |
12 | Academic-style factors such as momentum, reversal, the 52-week high and illiquidity. A good place to start. |
alpha101 |
101 | Formulaic alphas; many of the formulas mix price, volume, ranks and rolling correlations. |
gtja191 |
191 | Short-horizon trading factors published by Guotai Junan Securities, rooted mainly in the China A-share market. |
qlib158 |
154 | Features from Qlib’s Alpha158 set, often used as inputs to machine-learning models. |
fundamental |
4 | Factors built from point-in-time financial statements: return on equity, gross profitability, earnings yield and asset growth. |
Common themes can be read like this:
Browse with the CLI first, rather than reading 462 source files straight away:
vibe-trading alpha list --zoo academic
vibe-trading alpha show academic_mkt_rf
vibe-trading alpha bench --zoo academic --universe sp500 --period 2020-2025 --top 10alpha bench tests factors on a universe of stocks. The project’s built-in classification is: alive when the mean IC is above 0.02, at least 55% of the IC readings are positive and the t-statistic is significant; reversed when the IC is significantly negative; dead for everything else. This is not a “you can buy it” verdict, only the first filter at the research stage.
A strategy turns a research idea into rules that can be executed. A very simple strategy might be: “Hold when the 20-day moving average is above the 60-day moving average; otherwise stay out of the market.” A multi-factor strategy might be: “Within a pool of stocks, combine momentum, quality and volatility into one score, buy the top 20, and rebalance once a month.”
In Vibe-Trading, a strategy usually ends up as a run dir:
my_run/
config.json
code/
signal_engine.pyconfig.json tells the backtest system the symbols, the start and end dates, the data source, the bar interval and which market engine to use. signal_engine.py tells it what signal to produce on each bar or trading day.
The most common beginner mistake is to treat “the factor score is high” as “buy with everything I have, right now”. A real strategy also needs position limits, a rebalancing frequency, trading costs, handling for trading halts and daily price limits, risk control and a benchmark comparison.
A backtest is not a forecaster; it is a simulator of the past. Its value is that, before you put real money in, you can see what a set of rules went through in historical data: how much it made, its largest loss, how often it traded, whether it only worked in one particular year, and whether fees ate the profits.
vibe-trading run -p "Backtest a momentum strategy on a broad equity universe from 2020 to 2025. Include benchmark comparison, drawdown, turnover, and a short explanation."If the agent creates a run dir, it will eventually call the backtest tool. That tool checks config.json and code/signal_engine.py, then runs agent/backtest/runner.py.
Different markets do not share one set of trading rules. In the project, stocks, crypto, futures, forex and multi-asset portfolios go through different engines. Some stock markets have to handle T+1 (a share bought today cannot be sold until the next trading day), daily price limits, board lots (the minimum number of shares per order), commissions, stamp duty, settlement fees and slippage; others may allow T+0 same-day round trips, short selling or fractional shares.
This means you cannot judge a signal only by how accurate it is; you also have to see whether it can actually be filled under real market rules, how high the costs are, and whether positions become too concentrated. Many short-term strategies that look great fall apart once slippage and fees are added.
When new users try the project for the first time, the things they mix up most are the “market”, the “data source” and the “brokerage account”. The market decides the trading rules; the data source decides where the historical data comes from; a brokerage account only comes in when you need to read a real account or place simulated or real orders.
Good for getting started, ordinary price data and quick trial runs. The upside is a low barrier to entry; the downside is that coverage, rate limits, adjustment for splits and dividends, field quality and availability vary from source to source.
Good for steadier research and richer fields, such as index constituents, financial data, fundamental fields or professional market data. The downside is that you need to apply for a token or pay.
The local loader can read your own CSV, Parquet or DuckDB data. For cleaned historical data, offline research and reproducible experiments, local data is usually the easiest to keep under control.
CompositeEngine supports research on portfolios that span markets. For example, when one strategy holds stocks, crypto and futures at the same time, each market is handled by its own engine.
Keep connectors and loaders apart: a loader reads market data, while a connector links to your brokerage account. Typical connector capabilities include reading the account, positions, orders, quotes and historical bars, and, under a profile that allows it, placing or cancelling orders.
vibe-trading connector list
vibe-trading connector use <profile-id>
vibe-trading connector checkWhen you look at a connector, don’t start by asking “can it trade automatically?”. Look at the profile’s safety properties first:
| Profile type | What it means | When to use it |
|---|---|---|
readonly |
Only reads the account, positions, orders or quotes; it never submits an order. | Use this first when you connect a real account for the first time. |
paper |
Connects to a simulated or sandbox account; even when it places orders, no real money is involved. | For checking a strategy, order fields, fill reports and the cancel flow. |
live |
Connects to a real account. Every write action must pass the authorized limits, the kill switch, fail-closed checks and the audit log. | Only once you fully understand the risks and have tested with read-only and paper first. |
If you just want to learn the project, stick to read-only and paper at first. Once you can explain why every simulated order was produced, then think about connecting a real account.
Shadow Account is a feature for reviewing yourself. Instead of finding a generic strategy online, it reads your trade history, pairs up buys and sells, finds the rules that keep recurring in your profitable trades, and then backtests a rule-based shadow strategy.
Trade-history parsing currently supports several common broker export formats and a generic CSV. It reports behavioural diagnostics such as holding period, win rate, profit/loss ratio, drawdown, the disposition effect (holding losing positions longer than winning ones), overtrading, chasing rallies and anchoring. Shadow Account then extracts up to five if-then rules, generates strategy code, runs backtests across markets, and finally renders an HTML/PDF report.
vibe-trading --upload trades_export.csv
vibe-trading run -p "Analyze my trading behavior, extract my shadow strategy, and compare it with my actual trades."If you want to add this path for a new broker, the best place to start is normalizing its official API or user-exported trade records into the project’s TradeRecord format, then reusing the existing Trade Journal and Shadow Account flow.
vibe-trading setup; pip install alone ships no built Web UI). Ask a question about something you know well. No broker connection, no orders.academic zoo: read formulas with alpha show and check IC/IR with alpha bench. No rush to trade.A starter set of commands:
pip install vibe-trading-ai
vibe-trading init
vibe-trading
vibe-trading serve --port 8899
vibe-trading alpha list --zoo academic
vibe-trading alpha bench --zoo academic --universe sp500 --period 2020-2025 --top 10
vibe-trading connector listIf you want to contribute to the project, you don’t need to start with live order placement. A steadier route is to begin with docs, examples, parsers and tests.
TradeRecord and plug it into Trade Journal and Shadow Account.Neither this guide nor Vibe-Trading is investment advice. Any real trade should first go through your own judgement, your broker’s confirmation, testing on a paper account, and risk control.