Vibe-Trading Finance Toolkit

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

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:

{
  "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.

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 (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 (76)

<sub>*A-share symbols require TUSHARE_TOKEN. HK/US/Canada/crypto are free. Trading connector rows use the selected connector profile, e.g. IBKR local TWS/Gateway or Robinhood MCP OAuth.</sub>