vibe-trading

# Vibe-Trading Professional finance research toolkit with AI-powered backtesting (10 engines), multi-agent teams, 90 specialized skills, the **Alpha Zoo** (462 pre-built quantitative alphas across qlib158 / alpha101 / gtja191 / academic / fundamental with one-line CLI benchmarking), and the Shadow Account loop — extract your implicit trading rules from a journal, backtest them across A股/港股/美股/crypto, then see where they would have served you better. ## Setup ```bash pip install vibe-trading-ai ``` > **Package name vs commands:** The PyPI package is `vibe-trading-ai`. Once installed, you get: > > | Command | Purpose | > |---------|---------| > | `vibe-trading` | Interactive CLI / TUI | > | `vibe-trading serve` | Launch FastAPI web server | > | `vibe-trading-mcp` | Start MCP server (for Claude Desktop, OpenClaw, Cursor, etc.) | Add to your agent's MCP config: ```json { "mcpServers": { "vibe-trading": { "command": "vibe-trading-mcp" } } } ``` ### API Key Requirements Core research MCP tools work with zero API keys for HK/US/Canada/crypto. After `pip install`, backtesting, market data, factor analysis, options pricing, chart patterns, web search, document reading, trade journal analysis, shadow-account extraction/backtest/report, the Alpha Zoo (462 pre-built alphas), and all 90 skills are ready to use. IBKR tools require a local TWS / IB Gateway session; `run_swarm` requires an LLM key. | Feature | Key needed | When | |---------|-----------|------| | HK/US/Canada equities & crypto | None | Always free (yfinance / stooq / yahoo + OKX) | | China A-share data | None | Free via akshare / baostock / tencent / sina / eastmoney / mootdx fallback (`TUSHARE_TOKEN` optional for premium quality) | | Premium US fundamentals/quotes | `FINNHUB_API_KEY` / `ALPHAVANTAGE_API_KEY` / `TIINGO_API_KEY` / `FMP_API_KEY` | Only for optional-key providers (graceful fallback to free sources) | | Multi-agent swarm (`run_swarm`) | `OPENAI_API_KEY` + `LANGCHAIN_MODEL_NAME` | Swarm spawns internal LLM workers | ## What You Can Do ### Shadow Account — flagship loop Feed a CSV broker export (同花顺 / 东财 / 富途 / generic), and the agent will: 1. `analyze_trade_journal` — profile your behavior (holding period, win rate, disposition effect, chasing, overtrading, anchoring). 2. `extract_shadow_strategy` — distill 3-5 if-then rules that describe your profitable roundtrips. 3. `run_shadow_backtest` — backtest those rules across A/HK/US/crypto and compute delta-PnL vs your realized trades. 4. `render_shadow_report` — produce an HTML/PDF report (8 sections + charts) with today's matching signals. 5. `scan_shadow_signals` — list today's symbols that match your shadow's entry cadence (research only). ### Backtesting Create and run quantitative strategies across 10 engines (ChinaA, GlobalEquity, IndiaEquity, KoreaEquity, VietnamEquity, Crypto, ChinaFutures, GlobalFutures, Forex + options) with 28 market-data sources (auto-detect + ordered fallback; the hosted forex `tickerall` source is explicit-only): - **HK/US equities** via yfinance / stooq / yahoo (free, no API key); optionally via **Longbridge** historical OHLCV (`longbridge`, requires the optional SDK and `LONGBRIDGE_APP_KEY` / `LONGBRIDGE_APP_SECRET` / `LONGBRIDGE_ACCESS_TOKEN`). To force it for a run, set `"source": "longbridge"` in `config.json`. - **Canada equities (TSX/TSXV)** via yahoo / yfinance using Yahoo's canonical `<TICKER>.TO` (TSX, e.g. `TD.TO`) or `<TICKER>.V` (TSXV, e.g. `PNG.V`) suffixes — free, no API key. The GlobalEquity engine uses CAD identity, whole-share orders, configurable Canadian commission/slippage, and the TSX/TSXV price-increment grid. - **India equities (NSE/BSE)** via yahoo / yfinance using `<SYMBOL>.NS` (NSE, e.g. `RELIANCE.NS`) or `<SCRIP>.BO` (BSE, e.g. `500325.BO`) — free, no API key. The `IndiaEquityEngine` models T+1 delivery, no overnight shorts (set `allow_short` for intraday), configurable circuit bands, 1-share lots, and the STT/stamp-duty/exchange/GST cost stack. Optionally back-fill from your live broker via the `india_broker` source (Shoonya/Dhan; requires broker login). - **Korea equities (KRX: KOSPI/KOSDAQ)** via pykrx using `<CODE>.KS` (KOSPI, e.g. `005930.KS`) or `<CODE>.KQ` (KOSDAQ, e.g. `247540.KQ`) — free, no API key (`pip install "vibe-trading-ai[krx]"`; yahoo/yfinance fallback needs no extra). pykrx serves **daily bars only** (an intraday request falls through to another source) and its adjusted series is Naver-backed rather than a verbatim KRX print. The `KoreaEquityEngine` models same-day round trips (no T+1), the ±30% daily price limit measured from the previous close and quantized to the KRX tick grid, tick-rounded fills, the 0.20% sell-side transaction tax (2026 rate), and 1-share lots. It is **long-only**: `allow_short` is refused, because KRX covered-short and uptick rules cannot be enforced on daily bars. - **Vietnam equities (HOSE)** via yahoo / yfinance using `<TICKER>.VN` (e.g. `VIC.VN`) — no API key. Yahoo officially lists HOSE but not HNX or UPCOM; those venues are unsupported and need the `local` source. yfinance is an unofficial Yahoo client, so availability is best-effort and subject to Yahoo's personal-use terms. The `VietnamEquityEngine` approximates the formal T+2 settlement cycle — shares bought on day T normally become sellable during the afternoon session on T+2, informally called T+1.5 — as a two-bar hold on daily data (`vn_settlement_bars` covers scenario testing and future rule changes). It applies HOSE's normal ±7% band around the reference price, rounding the ceiling down and the floor up to the 10/50/100-VND tick grid, and uses 100-share round lots; odd-lot trading is not modelled. Costs are configurable brokerage plus, for individual investors, 0.1% sell-side personal income tax on gross proceeds. It is **long-only**, because operational cash-equity short selling is not generally available in Vietnam. - **Cryptocurrency** via OKX or CCXT/100+ exchanges (free, no API key) - **China A-shares** via AKShare / baostock / tencent / sina / eastmoney / mootdx (free, no API key) — `TUSHARE_TOKEN` optional for premium quality - **Futures, forex, macro** via AKShare (free, no API key) - **Forex / metals with no local terminal** via the hosted **TickerAll** MetaTrader 5 feed (`source="tickerall"`, `TICKERALL_API_KEY` + `TICKERALL_ACCOUNT_ID`, read-only) — the same broker feed as the `mt5` loader but over a hosted API on any OS. **Explicit-only** (never an automatic fallback). - **HK & A-share equities** via Futu (broker login required, optional) - **Local CSV/parquet bars** via the `local` loader (offline, no network) - **Premium cross-market data** via QVeris (optional API key) - **Premium US data** via optional-key finnhub / alphavantage / tiingo / fmp (graceful fallback to free sources) Factors: the Alpha101 and QLib158 zoos are tagged for the `equity_in` and `equity_kr` universes, so they compute on NSE/BSE and KRX bars (the GTJA191 zoo stays China-only). Live/paper India trading uses the Shoonya / Dhan connectors (paper + read-only live; live order placement is structurally disabled because those brokers expose no paper/live switch). Live/paper Korea equity trading uses the **KIS** connector (한국투자증권; genuine 모의투자 paper sandbox on a separate host/port from 실전투자 live, plus read-only live — no mandate-gated live-trade profile yet). Live/paper Korea crypto trading uses the **Upbit** connector (KRW markets; paper + read-only live — no runtime paper/live discriminator, so live order placement is structurally disabled, same as Shoonya/Dhan). Read-only Korea/US equity access is also available via the **Toss Securities** connector (토스증권) — no verified sandbox, so order placement always refuses, same as Trading 212. Example workflow: 1. Use `list_skills()` to discover strategy patterns 2. Use `load_skill("strategy-generate")` for the strategy creation guide 3. Use `write_file()` to create `config.json` and `code/signal_engine.py` 4. Use `backtest()` to run and get metrics (Sharpe, return, drawdown, etc.) ### Multi-Agent Swarm Teams 30 pre-built agent teams for complex research: - **Investment Committee**: bull/bear debate → risk review → PM decision - **Global Equities Desk**: A-share + HK/US + crypto → global strategist - **Crypto Trading Desk**: funding/basis + liquidation + flow → risk manager - **Earnings Research Desk**: fundamentals + revisions + options → earnings strategist - **Macro/Rates/FX Desk**: rates + FX + commodities → macro PM - **Quant Strategy Desk**: screening → factor research → backtest → risk audit - **Risk Committee**: drawdown, tail risk, regime analysis - And 23 more specialized teams Use `list_swarm_presets()` to see all teams, then `run_swarm()` to execute. ### Alpha Zoo (462 pre-built alphas) One-line cross-sectional IC / IR / alive-reversed-dead categorisation across five bundled zoos: - **qlib158** (154 alphas) — Microsoft Qlib's `Alpha158` feature handler, Apache-2.0 with pinned commit SHA. - **alpha101** (101 alphas) — Kakushadze (2015) "101 Formulaic Alphas" (arXiv:1601.00991), written from the paper appendix. - **gtja191** (191 alphas) — Guotai Junan 2014 "191 Short-period Trading Alpha Factors" research report. - **academic** (12 factors) — Fama-French 5 + Carhart momentum + Jegadeesh reversal + George-Hwang 52-week-high + Amihud illiquidity + Harvey-Siddique skew + Frazzini-Pedersen betting-against-beta (price-based proxies) + a correlation-rewiring stability score (from the in-repo correlation-regime skill). - **fundamental** (4 factors) — PIT-safe earnings yield, ROE, gross profitability, and asset growth from daily fundamental panels. Each alpha ships with `__alpha_meta__` (formula LaTeX + theme + universe + warmup + columns required), guarded by an AST purity gate + 300-row lookahead sentinel test. Use the `vibe-trading alpha {list,show,bench,compare,export-manifest}` CLI, the `/alpha/*` REST routes (browser at `/alpha-zoo`), or compose multi-factor signals via `ZooSignalEngine.from_zoo(...)`. ### Finance Skills (90) Comprehensive knowledge base covering: - Technical analysis (candlestick, Elliott wave, Ichimoku, SMC, harmonic, chanlun) - Quantitative methods (factor research, ML strategy, pair trading, multi-factor) - Risk management (VaR/CVaR, stress testing, hedging) - Options (Black-Scholes, Greeks, multi-leg strategies, payoff diagrams) - HK/US equities (SEC filings, earnings revisions, ETF flows, ADR/H-share arbitrage) - Crypto trading desk (funding rates, liquidation heatmaps, stablecoin flows, token unlocks, DeFi yields) - Behavioral finance, trade journal diagnostics, shadow account - Macro analysis, credit research, sector rotation, and more Use `load_skill(name)` to access full methodology docs with code templates. ## Available MCP Tools (74) | Tool | Description | API Key | |------|-------------|---------| | `list_skills` | List all 90 finance skills | None | | `load_skill` | Load full skill documentation | None | | `start_research_goal` | Create an auditable research goal | None | | `get_research_goal` | Read the current research goal | None | | `add_goal_evidence` | Attach evidence to a research goal | None | | `update_research_goal_status` | Update goal lifecycle status | None | | `backtest` | Run vectorized backtest engine | None* | | `factor_analysis` | IC/IR analysis + layered backtest | None* | | `alpha_zoo` | Browse bundled alpha metadata and registry health | None | | `alpha_bench` | Benchmark one alpha or a complete zoo | None* | | `analyze_options` | Black-Scholes price + Greeks | None | | `analyze_options_payoff` | Multi-leg expiry payoff + spot/IV scenarios | None | | `pattern_recognition` | Detect chart patterns (H&S, double top, etc.) | None | | `get_market_data` | Fetch OHLCV data (auto-detect + ordered fallback across 28 sources) | None* | | `get_fund_flow` | Capital fund-flow (main/retail net inflow) | None* | | `get_dragon_tiger` | Dragon-tiger list (龙虎榜) top buyer/seller seats | None* | | `get_northbound_flow` | Northbound (Stock Connect) net flow | None* | | `get_margin_trading` | Margin trading & short-selling balances | None* | | `get_block_trades` | Block-trade (大宗交易) records | None* | | `get_shareholder_count` | Shareholder-count history per symbol | None* | | `get_lockup_expiry` | Restricted-share lockup release schedule | None* | | `get_sector_info` | Sector / industry constituents & performance | None* | | `get_research_reports` | Sell-side analyst research reports | None* | | `get_stock_news` | Market & company news headlines | None* | | `get_sec_filings` | SEC EDGAR filings (10-K/10-Q/8-K, etc.) | None | | `get_financial_statements` | Income / balance / cash-flow statements | None* | | `get_options_chain` | Options chain (strikes, IV, OI, Greeks) | None* | | `get_stock_profile` | Valuation, analyst estimates & institutional holdings (US/HK) | None | | `screen_market` | Market screener with fundamental/technical filters | None* | | `search_symbol` | Symbol / ticker search across markets | None | | `get_macro_series` | FRED macroeconomic series | FRED_API_KEY | | `iwencai_search` | A-share natural-language research search | IWENCAI_KEY | | `qveris_search` | Search QVeris premium data/tool marketplace (free discovery) | QVERIS_API_KEY + paid mode | | `qveris_inspect` | Inspect QVeris tool schemas before executing (free) | QVERIS_API_KEY + paid mode | | `qveris_execute` | Execute a QVeris capability; budget-bounded, may be billable | QVERIS_API_KEY + paid mode | | `web_search` | Search the web via DuckDuckGo | None | | `read_url` | Fetch web page as Markdown | None | | `read_document` | Extract text from PDF/DOCX/XLSX/PPTX/images | None | | `write_file` | Write files (config, strategy code) | None | | `read_file` | Read file contents | None | | `list_strategies` | Browse discoverable strategies (Alpha Zoo + SDM store) | None | | `query_strategies` | Evidence-gated query: regime / Sharpe / quality / cost filters | None | | `get_strategy_evidence` | Per-regime evidence rows for one strategy | None | | `refresh_strategy_evidence` | Rebuild the disposable strategy-evidence cache from run artifacts | None | | `analyze_trade_journal` | Parse broker CSV → profile + behavior diagnostics | None | | `extract_shadow_strategy` | Distill 3-5 if-then rules from profitable roundtrips | None | | `run_shadow_backtest` | Multi-market backtest + delta-PnL attribution | None* | | `render_shadow_report` | HTML/PDF shadow report (8 sections + charts) | None | | `scan_shadow_signals` | Today's symbols matching the shadow's cadence | None | | `list_swarm_presets` | List multi-agent team presets | None | | `run_swarm` | Execute a multi-agent research team | LLM key | | `get_swarm_status` | Poll swarm run status without blocking | None | | `get_run_result` | Get final report and task summaries | None | | `list_runs` | List recent swarm runs with metadata | None | | `reap_stale_runs` | Finalize stale swarm runs | None | | `retry_run` | Re-run a failed/stale swarm run | LLM key | | `trading_connections` | List selectable connector profiles | None | | `trading_select_connection` | Select the default connector profile | None | | `trading_check` | Check connector readiness | Connector app/OAuth | | `trading_account` | Read account summary from selected connector | Connector app/OAuth |