English | 中文 | 日本語 | 한국어 | العربية | Español | Bahasa Indonesia

Vibe-Trading: Your Personal Trading Agent

One Command to Empower Your Agent with Comprehensive Trading Capabilities

Website  ·  Docs  ·  News  ·  Features  ·  Shadow Account  ·  Demo  ·  Quick Start  ·  Examples  ·  API / MCP  ·  Roadmap  ·  Contributing

🔍 Self-Improving Trading Agent • Natural-language market research • Strategy drafts and file/web analysis • Memory-backed workflows	🐝 Multi-Agent Trading Teams • Investment, quant, crypto, and risk teams • Streaming progress and persisted reports • Workers grounded with fetched market data
📊 Cross-Market Data & Backtesting • A / HK / US / Canada / UK / India / Korea equities, crypto, futures, and forex • Data fallback and composite backtests • PIT data, validation, and run cards	👥 Shadow Account • Broker-journal behavior diagnostics • Rule-based Shadow Account comparisons • Exportable audit reports and strategy code

` or the connection center) and never falls back to a default account; its equity positions are listed unpriced until the quote reply is mapped, and an account that also holds options, crypto, futures, event contracts, mutual funds or fixed income fails the source instead of showing an equity-only view. A new built-in connector or local plugin defaults to **Experimental** until its portfolio contract fixtures are added. ### AI-friendly connector onboarding Built-in SDK connectors publish one machine-readable onboarding contract: authentication type, required credential fields, optional dependency, install command, and the read-only operation used for verification. `trading_connections` exposes the same contract to MCP clients, while the Portfolio connection center renders it as a generic form. The contract contains field names only — never credential values. For a terminal-first setup, let the CLI collect secrets locally instead of putting them in a prompt or shell arguments: ```bash vibe-trading connector setup okx-live-sdk-readonly \ --connection-id main-okx \ --label "Main OKX" ``` The CLI prompts in the local terminal, stores values under that connection id in the OS keyring, and runs the connector's read-only check. The equivalent Web flow is **Portfolio → Manage accounts → Open connection center → choose a template → save to keyring → test connection**. MCP read tools may use `connection_id`; the process resolves its credentials from the vault, so keys never travel through MCP. Existing `~/.vibe-trading/.json` and environment configurations remain a compatibility fallback until a connection has a complete vault credential set. Do not paste broker API keys into an AI chat. Let the AI choose the connector, install the declared dependency, and interpret diagnostics; enter secrets only in the local hidden terminal prompt or local connection form. Read-only connectors you install yourself stay outside the checkout, in `~/.vibe-trading/connectors//`: a `connector.json` manifest plus an `adapter.py` implementing `check_status` / `get_account_snapshot` / `get_positions`. A manifest declaring any write capability is rejected. ```bash vibe-trading connector init my-broker --destination /tmp vibe-trading connector validate /tmp/my-broker vibe-trading connector install /tmp/my-broker ``` Their credentials go to the OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service) with `pip install "vibe-trading-ai[keyring]"`, never into the config files. Nothing on this path can place or cancel an order. --- ## 🧪 Research Workflow Most runs follow the same evidence path: route the request, load the right market context, execute tools, validate outputs, and keep the artifacts inspectable. The agent stops with a visible recovery request after eight consecutive tool-call iterations without a new successful observation. Repeating the same read result or a failed call does not reset this budget. An identical call is refused from its SECOND failure onward — one retry after a transient failure (a rate limit, a network blip, a tool timeout) still runs — until a successful state-changing tool executes or a new run starts; changed arguments can always execute. The recovery asks for an artifact path or permission to rerun the missing research step, and the run remains failed even if older metrics exist. This guard is separate from the wall-clock activity watchdog. | Layer | What happens | |-------|--------------| | **Plan** | Selects the relevant finance skills, tools, data sources, and swarm preset when useful. | | **Ground** | Pulls A-shares, HK/US/Canada/UK equities, crypto, futures, forex, documents, or web context through the available loaders. | | **Execute** | Generates testable strategy code, runs tools, and uses the matching backtest engine or analysis workflow. | | **Validate** | Adds metrics, benchmark comparison, Monte Carlo, Bootstrap, Walk-Forward, run cards, and warnings where applicable. | | **Deliver** | Returns reports, artifacts, tool traces, and exports for TradingView, TDX, MetaTrader 5, MCP clients, or later sessions. | --- ## 📡 Data Sources & Smart Fallback One `get_market_data` call, **28 market-data sources**, one of them the optional **QVeris** premium marketplace. Set `source: "auto"` — the loader picks by symbol, then walks a per-market chain ordered by **IP-ban risk**: never-banned public sources first, throttled / key-gated ones last. Zero config, no single point of failure. | Source | Markets | Auth | Role | |--------|---------|------|------| | `tencent` · `mootdx` | A-share + HK | none | never IP-banned (`mootdx` = 通达信 TCP) | | `eastmoney` | A / US / HK | none | OHLCV + deep fundamentals & flow tools (throttled) | | `baostock` · `akshare` | A (+ US/HK/futures/macro/fx) | none | free fallbacks | | `tushare` | A / HK / futures / fund / macro | token | richest A-share | | `gildata` | A-share | token (Settings / `GILDATA_TOKEN`) | Hundsun Juyuan (恒生聚源) commercial feed — forward-adjusted dailies, joins the A-share chain tail | | `yahoo` | US / HK / Canada / UK | none | direct chart/quotes/options; TSX `.TO` / TSXV `.V`; LSE `.L` with declared-currency normalization | | `sina` · `stooq` | US | none | K-line to 1984 · EOD CSV | | `yfinance` | US / HK / Canada / UK | none | wrapper; TSX `.TO` / TSXV `.V`; LSE `.L` under the same GBP/GBp contract | | `longbridge` | US / HK | App Key + App Secret + Access Token | optional historical OHLCV source; install the optional SDK | | `finnhub` · `alphavantage` · `tiingo` · `fmp` | US | key | optional providers | | `qveris` | global multi-asset | key · credits | **premium marketplace** — 63+ providers via one key (explicit-only, never in auto fallback) | | `nobitex` · `wallex` | crypto (Iranian Toman pairs) | none | public UDF endpoints; **explicit-only** — the only Toman-quoted sources, so they never join the crypto chain where a USD-quoted series could stand in for one | | `okx` · `ccxt` · `binance` | crypto | none | OKX + 100+ exchanges + Binance historical / USD-M perps | | `futu` | HK / A | OpenD | optional local FutuOpenD | | `mt5` | forex / metals | MT5 terminal | MetaTrader 5 (Exness-style) forex / metal bars, 1m–1D | | `tickerall` | forex / metals | key + account (read-only) | same broker MT5 feed, **hosted** — no local terminal, any OS (explicit-only, never in auto fallback) | | `pykrx` | Korea (KRX: KOSPI/KOSDAQ) | none | daily KOSPI / KOSDAQ bars for `.KS` / `.KQ` (optional `krx` extra) | | `india_broker` | India (NSE/BSE) | broker login | read-only Zerodha / Shoonya / Dhan bars for `.NS` / `.BO` (fallback-chain tail) | | `local` | any | none | your own CSV / Parquet / DuckDB via `local:` prefix | **Fallback chains (by IP-ban risk):** - **A-share** → `tencent` · `mootdx` · `eastmoney` · `baostock` · `akshare` · `tushare` · `gildata` · `local` - **US** → `yahoo` · `stooq` · `sina` · `eastmoney` · `yfinance` · `tiingo` · `fmp` · `finnhub` · `alphavantage` · `longbridge` · `akshare` · `local` - **HK** → `tencent` · `eastmoney` · `yahoo` · `futu` · `akshare` · `yfinance` · `tushare` · `longbridge` · `local` - **India (NSE/BSE)** → `yahoo` · `yfinance` · `india_broker` · `local` - **Korea (KOSPI/KOSDAQ)** → `pykrx` · `yahoo` · `yfinance` · `local` - **UK (LSE)** → `yahoo` · `yfinance` · `local` *(declared GBP/GBp quotes only)* - **Crypto** → `okx` · `ccxt` · `binance` · `yfinance` · `local` - **Forex / metals** → `mt5` · `yfinance` · `akshare` · `local`  ·  *(futures / fund / macro → `tushare`/`akshare` → `local`)* ### Using Longbridge explicitly Longbridge is an optional US/HK historical OHLCV loader. Install its SDK with: ```bash pip install "vibe-trading-ai[longbridge]" ``` Configure the three credentials in `.env`: ```dotenv LONGBRIDGE_APP_KEY=... LONGBRIDGE_APP_SECRET=... LONGBRIDGE_ACCESS_TOKEN=... ``` For a backtest, set `source` in `config.json`: ```json { "codes": ["QQQ.US"], "start_date": "2025-01-01", "end_date": "2025-01-10", "interval": "1D", "source": "longbridge" } ``` In an Agent conversation, ask explicitly: **"Use Longbridge to fetch QQQ.US historical data."** The explicit source request is separate from `source: "auto"`; `auto` keeps the normal per-market fallback chain. Beyond OHLCV, **22 read-only data tools** reach into fundamentals & flow — fund flow, dragon-tiger, northbound, margin, block trades, shareholder count, lockup, sector, research reports, news, SEC filings, financial statements, options chains, stock profile, market screening, symbol search, macro, iwencai, institutional holdings (13F), ETF look-through, prediction markets, and research papers — all exposed over MCP. An explicit `local:` symbol never silently falls back to a network source. ### 💎 Optional premium data — QVeris **Data: free routing or premium, your choice.** Free stays the default: 23 built-in sources with ban-risk fallback, no key, no cost. Premium via QVeris adds 10,000+ capabilities (per QVeris) across 63+ providers for options Greeks, premium fundamentals, China/HK/global data, macro, crypto, news, and filings; failed calls are not charged. Enable it in Settings -> QVeris or `vibe-trading data mode paid`. *QVeris disclosure: [signing up through the Vibe-Trading referral link](https://qveris.ai/?ref=Vyjjo5G_1cAHJA) gets you **+1,000 bonus credits** and supports the project.* --- ## 🔩 Detailed Capabilities Detailed inventories are folded below to keep the main README scannable. Open them when you want to inspect the available building blocks.

Finance Skill Library _{90 skills across 9 categories}

- 📊 90 specialized finance skills organized into 9 categories - 🌐 Complete coverage from traditional markets to crypto & DeFi - 🔬 Comprehensive capabilities spanning data sourcing to quantitative research | Category | Skills | Examples | |----------|--------|----------| | Data Source | 10 | `data-routing`, `tushare`, `yfinance`, `okx-market`, `akshare`, `mootdx`, `ccxt`, `eastmoney`, `sec-edgar`, `qveris` | | Strategy | 19 | `strategy-generate`, `cross-market-strategy`, `technical-basic`, `candlestick`, `ichimoku`, `elliott-wave`, `smc`, `multi-factor`, `ml-strategy` | | Analysis | 23 | `factor-research`, `correlation-regime`, `macro-analysis`, `global-macro`, `valuation-model`, `investor-lenses`, `credit-analysis`, `dividend-analysis` | | Asset Class | 9 | `options-strategy`, `options-advanced`, `convertible-bond`, `etf-analysis`, `asset-allocation`, `sector-rotation` | | Crypto | 7 | `perp-funding-basis`, `liquidation-heatmap`, `stablecoin-flow`, `defi-yield`, `onchain-analysis` | | Flow | 8 | `hk-connect-flow`, `us-etf-flow`, `edgar-sec-filings`, `financial-statement`, `adr-hshare` | | Tool | 10 | `backtest-diagnose`, `report-generate`, `pine-script`, `doc-reader`, `web-reader`, `vnpy-export`, `trade-journal` | | Research | 3 | `alpha-zoo`, `strategy-dev-manager`, `strategy-discovery` | | Risk Analysis | 1 | `ashare-pre-st-filter` |

Custom Data Source _{register your own historical OHLCV loader}

Need a market or vendor we don't ship a loader for? Add your own historical-bar loader and select it with `source=""`. The steps edit package source, so run from a clone (`pip install -e .`). 1. **Write the loader** — create `agent/backtest/loaders/_loader.py` with a class that satisfies `DataLoaderProtocol` (duck-typed, no base class needed) and is tagged with `@register`: ```python import pandas as pd from backtest.loaders.registry import register @register class DataLoader: name = "mysource" # the value you pass as source= markets = {"us_equity"} # a_share/us_equity/hk_equity/crypto/futures/fund/macro/forex requires_auth = False def is_available(self) -> bool: return True # token present? network reachable? def fetch(self, codes, start_date, end_date, *, interval="1D", fields=None): # return {symbol: DataFrame indexed by trade_date, # columns: open, high, low, close, volume} ... ``` 2. **Register the module** so `@register` fires — add `"backtest.loaders._loader"` to `_loader_modules` in `agent/backtest/loaders/registry.py`. 3. **Allow the name** through config validation — add `"mysource"` to `_VALID_SOURCES` in `agent/backtest/runner.py`. 4. *(Optional)* slot it into a market's `FALLBACK_CHAINS` in `registry.py` so `source="auto"` can reach it. 5. **Use it** — `source="mysource"` in a backtest config, or via the CLI / agent. > **Real-time ticks / order-book depth are out of scope for loaders** — the > loader layer is point-in-time historical bars only. Live market data flows > through the broker connectors instead: `okx` / `binance` / `ccxt` for crypto, > `futu` / `tiger` for equities.

Broker Connectors _{18 brokers — read + paper, bounded-live where supported}

Connector-first profiles. Most do read + paper-account order placement — IBKR is read-only, Robinhood is live-only (no paper account), Scalable Capital is read-only (no paper account exists at all), and Trading 212 and Toss Securities refuse order placement entirely, paper included; live order placement is bounded by a user-defined mandate (symbol allowlist, order-size / exposure caps, daily trade cap, instant kill switch) and never holds funds — the broker executes. Order-placing tools stay off MCP (agent + CLI only). Research / backtest paths are structurally barred from any live endpoint. | Broker | Markets | Capabilities | |--------|---------|--------------| | **IBKR** | global | local TWS / Gateway, read-only | | **Robinhood** | US | Agentic MCP (desktop OAuth) — read + bounded live | | **Scalable Capital** | DE / EU | Agentic MCP (desktop OAuth) — fully read-only; no paper account exists | | **Tiger** | US / HK / A | read + paper + bounded live | | **Alpaca** | US | read + paper + bounded live (+ TAP credential-isolation mode) | | **OKX** · **Binance** | crypto | read + paper + bounded live | | **Futu** | HK / US / A | read + paper + bounded live | | **eToro** | global | read + paper + bounded live (Public API; demo keys reach only `/demo` paths, plus copy-trading workflows) | | **MetaTrader 5** | forex / CFD | read + paper + bounded live (Exness-style; demo ⇔ paper identity guard) | | **KIS** (한국투자증권) | Korea (KOSPI/KOSDAQ) | read + genuine paper (모의투자, a real broker-side sandbox on a separate host) — live order placement not yet wired for this market | | **Longbridge** · **Dhan** · **Shoonya** · **Zerodha** · **Upbit** | US / HK · India (NSE/BSE) · Korea (crypto) | read + paper only — no runtime paper/live discriminator, so live order placement is hard-refused | | **Trading 212** · **Toss Securities** | UK / EU · Korea/US | fully read-only — `place_order` / `cancel_order` hard-refuse even paper (no verified sandbox) | Paper-vs-live is a **structural per-broker runtime guard** (account-id format, host separation, demo flag, or trade environment), never a config flag the agent can flip. A broker exposing no such discriminator is capped at paper + read-only.

Preset Trading Teams _{30 swarm presets}

- 🏢 30 ready-to-use agent teams - ⚡ Pre-configured finance workflows - 🎯 Investment, trading & risk management presets | Preset | Workflow | |--------|----------| | `investment_committee` | Bull/bear debate → risk review → PM final call | | `global_equities_desk` | A-share + HK/US + crypto researcher → global strategist | | `crypto_trading_desk` | Funding/basis + liquidation + flow → risk manager | | `earnings_research_desk` | Fundamental + revision + options → earnings strategist | | `macro_rates_fx_desk` | Rates + FX + commodity → macro PM | | `quant_strategy_desk` | Screening + factor research → backtest → risk audit | | `technical_analysis_panel` | Classic TA + Ichimoku + harmonic + Elliott + SMC → consensus | | `risk_committee` | Drawdown + tail risk + regime review → sign-off | | `global_allocation_committee` | A-shares + crypto + HK/US → cross-market allocation | _{Plus 20+ additional specialist presets — run vibe-trading --swarm-presets to explore all. Bring your own: drop preset YAMLs into ~/.vibe-trading/swarm/presets/ — they are listed alongside the bundled roster (same-name files override it, like user skills) and survive upgrades.}

Alpha Zoo _{462 pre-built quant alphas across 5 families}

- 🧬 462 cross-sectional alphas, lookahead-banned at the operator layer - 📈 IC + IR + alive/reversed/dead categorisation in one CLI command - 🔬 AST purity gate + 300-row lookahead sentinel test + `pytest-socket` network kill-switch - 📦 Apache-2 attribution for Qlib; per-zoo `LICENSE.md` declaring formulas as mathematical content - 🤝 Developer Certificate of Origin (DCO) sign-off workflow for community PRs | Zoo | Count | Source | License | |-----|-------|--------|---------| | **qlib158** | 154 | Microsoft Qlib `Alpha158` (Apache-2.0, commit-pinned) | Apache-2.0 | | **alpha101** | 101 | Kakushadze (2015), "101 Formulaic Alphas", arXiv:1601.00991 | Formulas are mathematical content | | **gtja191** | 191 | Guotai Junan (2014), "191 Short-period Trading Alpha Factors" | Formulas are mathematical content | | **academic** | 12 | Fama-French 5 + Carhart momentum + Jegadeesh reversal + George-Hwang 52-week-high + Amihud illiquidity + Harvey-Siddique skew + Frazzini-Pedersen betting-against-beta + correlation-rewiring stability (price-based proxies) | Public academic literature | | **fundamental** | 4 | PIT-safe SEC company facts — earnings yield, ROE, gross profitability, asset growth (filed-date anchored) | Public financial data | Run `vibe-trading alpha list` to browse, `vibe-trading alpha show ` for formulas + source, `vibe-trading alpha bench --zoo X --universe Y --period Z` to score a whole zoo, and `vibe-trading alpha compare --all` to rank zoos side by side.

Backtest Engines _{10 engines + options portfolio, cross-market composite}

| Engine | Market | Notes | |--------|--------|-------| | **ChinaA** | A-share | T+1, price limits, pre-ST filter | | **GlobalEquity** | US / HK / Canada / UK | same-session trading; market-specific lots, ticks, settlement currencies, and costs | | **IndiaEquity** | India (NSE/BSE) | T+1, circuit bands, config-driven STT / stamp / SEBI / GST cost stack | | **KoreaEquity** | Korea (KRX: KOSPI/KOSDAQ) | long-only, ±30% band judged at execution time on the unified tick grid, 2026 0.20% transaction tax | | **VietnamEquity** | Vietnam (HOSE) | long-only, T+2 settlement hold, ±7% band on the 10/50/100-VND tick grid, 100-share lots, 0.1% sell-side tax | | **Crypto** | crypto spot / USD-M perps | funding settlements, execution/mark split | | **ChinaFutures** · **GlobalFutures** | futures | margin, contract multipliers | | **Forex** | FX / metals | via the `mt5` loader (local terminal) or the hosted `tickerall` loader (no terminal, any OS) | | **Composite** | cross-market | one shared capital pool across markets (`source="auto"`) | | **options_portfolio** | options | multi-leg, Greeks, payoff/scenario | Intraday bars: 1m / 5m / 15m / 30m / 1H / 4H / 1D. 15 metrics + benchmark comparison, **5 portfolio optimizers** (equal-volatility / risk-parity / mean-variance / max-diversification / turnover-aware), and 3 validation tools (Monte Carlo / Bootstrap / Walk-Forward).

Quant Library _{306 tested functions across 23 modules, callable from every transport}

`src/quantlib` holds one tested implementation of each piece of finance math the agent needs. Skills **import** these rather than carrying formulas inside markdown code blocks — if you find a pricing formula living in a `SKILL.md`, that is a bug, not a pattern. | Module | What it covers | |--------|----------------| | `options` | Black-Scholes price + greeks, implied-volatility inversion | | `fixedincome` | Bond math, Nelson-Siegel / Svensson curve fitting | | `credit` | Altman Z-score, Merton / KMV distance-to-default | | `timeseries` | Stationarity, cointegration, GARCH, bootstrap | | `risk` · `var_backtest` | VaR / CVaR / EVT and their backtests | | `attribution` | Brinson-Fachler decomposition | | `performance` · `fundmath` | TWR / MWR / Modified Dietz; XIRR / MOIC / DPI / TVPI | | `factormodel` · `eventstudy` | Factor regressions, event studies | | `multipletesting` · `crossvalidation` | Deflated significance, purged CV | | `impact` | Market-impact models | | `volatility` | Heston (1993) stochastic-volatility pricing | | `portfolio` | Hierarchical Risk Parity allocation | | `copula` | Gaussian and Archimedean copulas | | `microstructure` | VPIN, Roll spread, Amihud illiquidity, Kyle's lambda | The read-only `quantlib_call` tool reaches all of it through one contract, so the finance math works on the CLI, the Web UI, the REST API and MCP — including deployments where `bash` is gated off. It is structurally not a shell — module allowlist, `__all__`-only dispatch, `export_*` refused. Econometrics needs the `stats` extra (`pip install "vibe-trading-ai[stats]"`); those functions lazy-import and tell you which one is missing.

Valuation & Institutional Research _{DCF, comps, three-statement, and six research commands}

A valuation engine that refuses to invent its own inputs. The one rule in `contracts.py`: **a missing input makes a model NOT RUNNABLE and is never silently defaulted** — every default in a valuation model is an opinion wearing a constant's clothes. | Model | Behaviour worth knowing | |-------|-------------------------| | `run_dcf` | FCFF bridge, WACC build, mid-year discounting, net-debt bridge, WACC×g sensitivity grid. Dual terminal value: each method is cross-checked against the other's implied multiple and implied g | | `run_comps` | EV bridge, LTM + calendar-year calendarisation, multiple matrix. A peer with a non-positive denominator is **excluded and reported**, never averaged in as a negative multiple | | `threestatement` | Linked projection with a hard balance assertion, an explicit revolver plug, and an iterated interest↔debt circularity that must converge or raise | Artifacts are input-hashed and versioned, with xlsx / pptx export. Six slash commands drive the workflows — `/comps` `/dcf` `/attrib` `/memo` `/earnings` `/screen` — each carrying a step skeleton and an arithmetic-consistent worked example (the Brinson decomposition sums exactly to active return; the earnings bridge sums exactly to the EPS delta). The `investor-lenses` skill stacks named-investor reasoning frameworks on top as analysis overlays: each lens is an operating procedure — priority signals, disqualifying conditions, typical misuse — not a biography, and names no tool. Beyond bars, `src/entities` ingests irregular dated cash flows (NAVs, capital calls, coupons) and `cashflow_performance` reports XIRR / MOIC / DPI / TVPI / TWR / Modified Dietz / MWR over them. This path is deliberately parallel to the bar engines so a `nav` column can never reach one and get priced as a close.

Governance & Audit Trail _{answer "what methodology produced that number?"}

Every run writes a **manifest** hashing the prompt, the skill contents, the tool registry and the package versions, so a number produced last month can be traced to the exact methodology that produced it. The **audit ledger** chains each record to its predecessor's hash and fsyncs, so editing or deleting a record is detectable — and an edit that recomputes its own hash is still caught one record later via `prev_hash_mismatch`. Timestamps are always caller-supplied; no module here calls `datetime.now()`. Trace redaction is **sink-aware**: tool-call arguments and the live audit ledger use a fail-closed sink where `content` stays redacted, while the tool-result sink releases it and pattern-scrubs its string leaves. `env` is never released in either.

## 🎬 Demo

https://github.com/user-attachments/assets/4e4dcb80-7358-4b9a-92f0-1e29612e6e86	https://github.com/user-attachments/assets/3754a414-c3ee-464f-b1e8-78e1a74fbd30
☝️ Natural-language backtest & multi-agent swarm debate — Web UI + CLI

--- ## 🚀 Quick Start ### One-line install (PyPI) ```bash pip install vibe-trading-ai ``` Then run a first research task: ```bash vibe-trading init vibe-trading run -p "Backtest a BTC-USDT 20/50 moving-average strategy for 2024 and summarize return and drawdown" ``` > **Upgrading from an older version?** 0.1.10 moved to LangChain 1.x. If imports break after `pip install -U vibe-trading-ai` over a pre-0.1.10 install (e.g. langgraph fails to import), recreate the venv or run `pip install --force-reinstall vibe-trading-ai`. A fresh install is unaffected. > **Package name vs commands:** The PyPI package is `vibe-trading-ai`. Once installed, you get three commands: > > | 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.) | ```bash vibe-trading init # interactive .env setup vibe-trading # launch CLI vibe-trading serve --port 8899 # launch web UI vibe-trading-mcp # start MCP server (stdio) ``` ### Or choose a path | Path | Best for | Time | |------|----------|------| | **A. Docker** | Try it now, zero local setup | 2 min | | **B. Local install** | Development, full CLI access | 5 min | | **C. MCP plugin** | Plug into your existing agent | 3 min | | **D. ClawHub** | One command, no cloning | 1 min | ### Prerequisites - An **LLM API key** from any supported provider — or run locally with **Ollama** (no key needed) - **Python 3.11+** for Path B - **Docker** for Path A - OpenAI Codex can also be used with ChatGPT OAuth: set `LANGCHAIN_PROVIDER=openai-codex`, then run `vibe-trading provider login openai-codex`. This does not use `OPENAI_API_KEY`. - GitHub Copilot can be used with an active Copilot subscription instead of a separately billed LLM API key. See [GitHub Copilot SDK provider](#github-copilot-sdk-provider). > **Supported LLM providers:** OpenRouter, OpenAI, Anthropic (native Messages API), DeepSeek, OpenCode (Go / Zen), Gemini, Groq, DashScope/Qwen, Zhipu, Moonshot/Kimi, MiniMax, SiliconFlow (CN + Global), Xiaomi MIMO, Novita AI, iFlytek Spark, Z.ai, NVIDIA NIM, ModelScope, GitHub Copilot, Ollama (local). When no `*_BASE_URL` is set, each provider falls back to its canonical endpoint, so just a key is enough. See `.env.example` for config. > **Tip:** All markets work without any API keys thanks to automatic fallback. yfinance/Yahoo (HK/US/Canada/UK), OKX (crypto), mootdx (A-shares, TCP-direct, no IP throttle), and AKShare (A-shares, US, HK, futures, forex) are all free. LSE `.L` quotes must declare GBP or GBp so pence can be normalized before GBP accounting. Tushare token is optional — mootdx is the preferred no-token A-share fallback, with AKShare as a broader backup. ### GitHub Copilot SDK provider The official GitHub Copilot SDK ships as an optional extra, so install it alongside Vibe-Trading with `pip install "vibe-trading-ai[copilot]"`; installing the Copilot CLI is optional. Authenticate with any one of these supported methods: ```bash gh auth login # use GitHub CLI credentials # or run `copilot` and sign in # stores credentials in the OS keychain # or export COPILOT_GITHUB_TOKEN=gho_xxx ``` Then configure `agent/.env`: ```dotenv LANGCHAIN_PROVIDER=copilot LANGCHAIN_MODEL_NAME=claude-sonnet-5 # COPILOT_GITHUB_TOKEN=gho_xxx # optional; recommended for Docker/CI ``` Start Vibe-Trading normally. Its preflight reports whether the SDK can authenticate: ```bash vibe-trading ``` Authentication priority is `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`, stored Copilot CLI credentials, then `gh` credentials. Vibe-Trading does not copy or persist SDK credentials. Host keychain credentials are not automatically available inside Docker, so containers should receive `COPILOT_GITHUB_TOKEN`. ### Path A: Docker (zero setup) ```bash git clone https://github.com/HKUDS/Vibe-Trading.git cd Vibe-Trading cp agent/.env.example agent/.env # Edit agent/.env — uncomment your LLM provider and set API key docker compose up --build ``` Open `http://localhost:8899`. Backend + frontend in one container. > [!NOTE] > **OpenAI Codex OAuth with Docker:** the browser login needs a terminal so you > can paste the callback URL. Run it through Compose, which allocates an > interactive terminal automatically: > > ```bash > docker compose exec vibe-trading vibe-trading provider login openai-codex > ``` > > If you use `docker exec` directly, pass `-it` before the container name. Docker publishes the backend on `127.0.0.1:8899` by default and runs the app as a non-root container user. If you intentionally expose the API beyond your own machine, set a strong `API_AUTH_KEY` and send `Authorization: Bearer ` from clients. > [!NOTE] > **Using Ollama with Docker:** the container reaches a host-side Ollama via `host.docker.internal`, not `localhost` (inside the container `localhost` is the container itself). `docker-compose.yml` defaults `OLLAMA_BASE_URL` to `http://host.docker.internal:11434`; export `OLLAMA_BASE_URL` (or set it in a top-level `.env`) to point elsewhere. This relies on the `host-gateway` mapping in `extra_hosts`, which requires **Docker Engine ≥ 20.10 / Compose v2** (provided automatically on Docker Desktop). Your data survives updates: persistent memory, the cross-session search index, user-created skills, shadow accounts, broker connector config, web sessions, backtest runs, swarm history, and uploads all live in named Docker volumes, so `git pull && docker compose up --build` keeps them. In-progress Web replies are checkpointed too, so a restart restores the partial response and marks the attempt interrupted instead of silently dropping it. Data is deleted only by `docker compose down -v`. ### Path B: Local install ```bash git clone https://github.com/HKUDS/Vibe-Trading.git cd Vibe-Trading python -m venv .venv # Activate source .venv/bin/activate # Linux / macOS # .venv\Scripts\activate.bat # Windows CMD # .venv\Scripts\Activate.ps1 # Windows PowerShell pip install -e . cp agent/.env.example agent/.env # Edit — set your LLM provider API key vibe-trading # Launch interactive TUI ``` > [!NOTE] > **On Windows:** `cp` is a PowerShell alias for `Copy-Item`, so the snippets above work as-is in PowerShell. CMD has no `cp` — use `copy agent\.env.example agent\.env` instead (this applies to the Docker snippet above too). If PowerShell refuses to run `Activate.ps1`, run `Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned` first; it applies to that shell session only.

Start web UI (optional)

```bash # Terminal 1: API server vibe-trading serve --port 8899 # Terminal 2: Frontend dev server cd frontend && npm install && npm run dev # requires Node >= 22.22 ``` Open `http://localhost:5899`. The frontend proxies API calls to `localhost:8899`. **Production mode (single server):** ```bash cd frontend && npm run build && cd .. vibe-trading serve --port 8899 # FastAPI serves dist/ as static files ``` > [!NOTE] > `vibe-trading serve` binds `0.0.0.0` and is loopback-only by default: opening the UI on the **same machine** (`http://localhost:8899`) works with zero config. If you browse from **another machine, a VM host, or a phone on your LAN**, sensitive endpoints return `403` and the chat shows "Remote API access requires an API key" — set a strong `API_AUTH_KEY` in `agent/.env`, restart, and enter the same key once in **Settings**. (Docker Desktop's host gateway: set `VIBE_TRADING_TRUST_DOCKER_LOOPBACK=1` with the default `127.0.0.1` port bind.)

### Path C: MCP plugin See [MCP Plugin](#-mcp-plugin) section below. ### Path D: ClawHub (one command) ```bash npx clawhub@latest install vibe-trading --force ``` The skill + MCP config is downloaded into your agent's skills directory. See [ClawHub install](#-mcp-plugin) for details. --- ## 🧠 Environment Variables Copy `agent/.env.example` to `agent/.env` and uncomment the provider block you want. Each provider needs 3-4 variables: | Variable | Required | Description | |----------|:--------:|-------------| | `LANGCHAIN_PROVIDER` | Yes | Provider name (`openrouter`, `deepseek`, `groq`, `ollama`, etc.) | | `_API_KEY` | Yes* | API key (`OPENROUTER_API_KEY`, `DEEPSEEK_API_KEY`, etc.) | | `_BASE_URL` | Yes | API endpoint URL | | `LANGCHAIN_MODEL_NAME` | Yes | Model name (e.g. `deepseek-v4-pro`) | | `LANGCHAIN_REASONING_EFFORT` | No | Reasoning effort (`none`, `low`, `medium`, `high`, or `max`) | | `LANGCHAIN_USE_RESPONSES_API` | No | Responses transport override: literal `true` uses `/v1/responses` when the endpoint supports it; native adapters retain their own transport; all other values use Chat Completions | | `TUSHARE_TOKEN` | No | Tushare Pro token for A-share data (falls back to AKShare) | | `TIMEOUT_SECONDS` | No | LLM call timeout, default 120s | | `API_AUTH_KEY` | Recommended for network deployments | Bearer token required when the API is reachable from non-local clients | | `VIBE_TRADING_ENABLE_SHELL_TOOLS` | No | Explicit opt-in for shell-capable tools in remote API/MCP-SSE style deployments | | `VIBE_TRADING_ALLOWED_FILE_ROOTS` | No | Extra comma-separated roots for document and broker-journal imports | | `VIBE_TRADING_ALLOWED_RUN_ROOTS` | No | Extra comma-separated roots for generated-code run directories | | `VIBE_TW_STOCK_DB` | No | Path to a Taiwan-market SQLite snapshot; the read-only `taiwan_stock_data` tool registers only when it is schema-valid | | `VIBE_TRADING_EXTRA_CORS_ORIGINS` | No | Comma-separated origins **added** to the loopback CORS defaults (`CORS_ORIGINS` replaces them instead) | | `CONTENT_FILTER_WARNING_THRESHOLD` | No | Content-filter warning ratio threshold (default 0.05 = 5%). When the ratio of LLM responses blocked by content moderation exceeds this, the run card warns you to switch providers. | _{* Ollama does not require an API key. OpenAI Codex uses ChatGPT OAuth and stores tokens via `oauth-cli-kit`, not in `agent/.env`. GitHub Copilot authentication is handled by the official SDK.} **Free data (no key needed):** A-shares via AKShare, HK/US/Canada/UK equities via Yahoo/yfinance, crypto via OKX, 100+ crypto exchanges via CCXT. The system automatically selects the best available source for each market. ### 🎯 Recommended Models Vibe-Trading is a tool-heavy agent — skills, backtests, memory, and swarms all flow through tool calls. Model choice directly decides whether the agent *uses* its tools or fabricates answers from training data. | Tier | Examples | When to use | |------|----------|-------------| | **Best** | `anthropic/claude-opus-4.7`, `anthropic/claude-sonnet-4.6`, `openai/gpt-5.5-pro`, `google/gemini-3.5-flash` | Complex swarms (3+ agents), long research sessions, paper-grade analysis | | **Sweet spot** (default) | `deepseek-v4-pro`, `deepseek/deepseek-v4-pro`, `x-ai/grok-4.20`, `z-ai/glm-5.1`, `moonshotai/kimi-k2.6`, `qwen/qwen3-max-thinking` | Daily driver — reliable tool-calling at ~1/10 the cost | | **Avoid for agent use** | `*-nano`, `*-flash-lite`, `*-coder-next`, small / distilled variants | Tool-calling is unreliable — the agent will appear to "answer from memory" instead of loading skills or running backtests | The default `agent/.env.example` ships with DeepSeek official API + `deepseek-v4-pro`; OpenRouter users can use `deepseek/deepseek-v4-pro`. --- ## 🖥 CLI Reference The interactive TUI (`vibe-trading`) now uses a terminal-native transcript: a startup banner, prompt rule, previous-turn recap, live activity rail, Markdown/table rendering, and run timing all stay in the CLI. Non-interactive invocations such as `vibe-trading run`, pipes, and `--json` remain script-friendly. ```bash vibe-trading # interactive TUI vibe-trading run -p "..." # single run vibe-trading serve # API server vibe-trading alpha list # browse 462 pre-built alphas; show / bench / compare / export-manifest sub-commands available vibe-trading playbook list # five scheduled-research templates; show / create sub-commands available vibe-trading channels status --local # inspect IM channel config and install hints vibe-trading provider doctor # print redacted provider/proxy/package diagnostics ```

Slash commands inside TUI

| Command | Description | |---------|-------------| | `/help` | Show keyboard shortcuts and command list | | `/model` | Switch LLM provider and model | | `/memory` | Show / manage persistent memory | | `/history` | Browse and resume prior sessions | | `/goal` | Start / inspect a finance research goal | | `/search` | Full-text search across all sessions | | `/swarm` | Multi-agent presets (committee / quant / risk) | | `/skill` | List / load / unload skills | | `/show` | Show prior run by id | | `/clear` | Clear current conversation | | `/pine` | Export current strategy as Pine Script | | `/journal` | Analyze trade journal CSV | | `/shadow` | Train / view shadow account | | `/export` | Export current session (md / json) | | `/debug` | Toggle debug panel (token usage / latency) | | `/comps` | Comparable company analysis (peer multiples -> implied range) | | `/dcf` | Discounted cash flow valuation with sensitivity grid | | `/attrib` | Brinson-Fachler attribution (allocation vs selection) | | `/memo` | Investment memo — thesis, variant view, scenarios, kill criteria | | `/earnings` | Earnings review — surprise bridge from revenue to EPS | | `/screen` | Systematic idea screen — hypothesis, funnel, survivor queue | | `/playbook` | Scheduled research templates (list / run / schedule) | | `/connector` | Trading connector profiles (status / start / halt) | | `/halt` | Kill switch — halt ALL live trading now | | `/resume` | Clear the kill switch (re-enable live trading) | | `/data` | Data routing mode | | `/quit` | Exit (also: q, exit, :q) |

Single run & flags

```bash vibe-trading run -p "Backtest BTC-USDT MACD strategy, last 30 days" vibe-trading run -p "Analyze AAPL momentum" --json vibe-trading run -f strategy.txt echo "Backtest 000001.SZ RSI" | vibe-trading run ``` ```bash vibe-trading -p "your prompt" vibe-trading --skills vibe-trading --swarm-presets vibe-trading --swarm-run investment_committee '{"topic":"BTC outlook"}' vibe-trading --list vibe-trading --show vibe-trading --code vibe-trading --pine # Export indicators (TradingView + TDX + MT5) vibe-trading --trace vibe-trading --continue "refine the strategy" vibe-trading --upload report.pdf ``` ```bash vibe-trading alpha list --zoo gtja191 --limit 10 vibe-trading alpha show gtja191_171 vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20 ```

IM channels

IM channel adapters connect outside chat apps to the same session runtime used by the Web UI and CLI. Configure enabled adapters under `channels` in `~/.vibe-trading/agent.json`; SDK-backed adapters are optional extras, and missing SDKs report recovery hints instead of crashing the runtime. For long-running channel tasks, tune the central assistant-reply wait budget with `replyTimeoutS` (seconds, default `600`): ```json { "channels": { "replyTimeoutS": 1800, "feishu": { "enabled": true } } } ``` This controls how long the shared channel runtime waits for the agent session to produce an assistant message; adapter HTTP/socket timeouts remain adapter-specific. ```bash vibe-trading channels status --local # inspect config and missing SDK hints without API vibe-trading channels status # query the running API runtime vibe-trading channels start # start enabled adapters through the API vibe-trading channels stop # stop enabled adapters through the API vibe-trading channels login weixin # run an adapter login hook when needed vibe-trading channels pairing --channel telegram list ``` `vibe-trading channels login feishu` saves the QR-authorized app credentials to `~/.vibe-trading/agent.json` with owner-only file permissions before reporting login success. The built-in adapters cover `websocket`, `telegram`, `slack`, `discord`, `matrix`, `whatsapp`, `signal`, `qq`, `napcat`, `weixin`, `wecom`, `feishu`, `dingtalk`, `msteams`, `email`, and `mochat`. Use narrow extras such as `pip install "vibe-trading-ai[telegram]"`, or install the full channel set with `pip install "vibe-trading-ai[channels]"`. **In-chat slash commands** (channel-agnostic, work in all 16 adapters): | Command | Description | |---------|-------------| | `/new` | Reset the current session — the next message starts a fresh conversation | | `/reset` | Alias for `/new` | | `/newsession` | Alias for `/new` | | `/pairing list` | Show pending sender-pairing requests (operators only) | Commands are case-insensitive and must be sent as the entire message (e.g. `hello /new` is treated as a regular message, not a reset). > **`/pairing` is operator-gated.** In-chat pairing-control commands are rejected unless the sender is listed as an operator — set `channels.operators` (cross-channel authority) or a channel section's own `operators` list in your channels config. With no operators configured, in-chat `/pairing` is refused (fail-closed) and pairing is managed only through the authenticated CLI (`vibe-trading channels pairing …`) and the auth-gated REST endpoint. This prevents any allow-listed group member from taking over pairing across channels. **Configure from the Web UI**: the **IM Channels** panel on the Settings page configures channels without hand-editing files. Expand a channel to open its config panel: fields render from backend metadata, and secret values are never returned to the browser, only masked (`****` plus the last 4 characters). DingTalk is the first fully-guided channel: create an app at [open-dev.dingtalk.com](https://open-dev.dingtalk.com/), add the bot capability, enable Stream Mode (no public callback URL needed), copy the AppKey into Client ID and the AppSecret into Client Secret, then publish the app. QQ has joined it as a fully-guided channel: register a bot on the QQ Open Platform ([q.qq.com](https://q.qq.com/)), copy the AppID and AppSecret into the form, verify with **Test connection** before saving, then enable; no public callback URL is needed (WebSocket via the official botpy SDK). **Test connection** probes the values in the form before anything is saved and answers with an honest result code (`ok`, `invalid_credentials`, `network`, or `unsupported`). **Enable** applies immediately: a running channel runtime hot-swaps that one adapter with no process restart, and enabling auto-verifies credentials unless you explicitly choose **Enable anyway** after a failed check. Disabling a channel keeps its stored credentials, so re-enabling needs no re-entry. Only the built-in adapters are listed here; entry-points plugin channels remain file-configured. Saves write the `channels.` section of `~/.vibe-trading/agent.json` atomically. YAML config files are read-only for the web UI (JSON is required to edit from the browser), and the panel says so instead of failing. Channels without a dedicated guide render a generic form derived from their defaults.

--- ## 💡 Examples ### Strategy & Backtesting ```bash # Moving average crossover on US equities vibe-trading run -p "Backtest a 20/50-day moving average crossover on AAPL for the past year, show Sharpe ratio and max drawdown" # RSI mean-reversion on crypto vibe-trading run -p "Test RSI(14) mean-reversion on BTC-USDT: buy below 30, sell above 70, last 6 months" # Multi-factor strategy on A-shares vibe-trading run -p "Backtest a momentum + value + quality multi-factor strategy on CSI 300 constituents over 2 years" # After backtesting, export to TradingView / TDX / MetaTrader 5 vibe-trading --pine ``` For calendar-triggered partial rebalancing, keep the strategy signal dense and select execution bars in `config.json`: ```json { "position_adjustment": "rebalance", "rebalance_mask": "MS" } ``` `MS` executes the aligned target on the first observed trading bar of each month. Weekly/quarterly pandas offset aliases (for example `W-FRI` and `QS`) and explicit ISO date lists are also accepted. An alias must not be finer than the aligned bar interval. Period aliases select the first observed bar in each period; `W-FRI` starts a Friday-anchored week and therefore normally executes on the following Monday, not on Friday itself. Omit `rebalance_mask` to preserve the existing every-bar rebalance behavior. A mask is deliberately incompatible with `position_adjustment="hold"`. **Bench a pre-built alpha zoo** (one line): ```bash vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20 ``` **Browse the catalogue** and inspect a single alpha: ```bash vibe-trading alpha list --zoo gtja191 --theme reversal --limit 10 vibe-trading alpha show gtja191_171 ``` **Compose a multi-factor signal** from the zoo (Python): ```python from src.skills.multi_factor.zoo_signal_engine import ZooSignalEngine engine = ZooSignalEngine.from_zoo(["gtja191_171", "gtja191_111", "gtja191_163"]) panel = ... # your wide OHLCV panel signal = engine.compute_signal(panel) ``` ### Market Research ```bash # Equity deep-dive vibe-trading run -p "Research NVDA: earnings trend, analyst consensus, option flow, and key risks for next quarter" # Macro analysis vibe-trading run -p "Analyze the current Fed rate path, USD strength, and impact on EM equities and gold" # Crypto on-chain vibe-trading run -p "Deep dive BTC on-chain: whale flows, exchange balances, miner activity, and funding rates" ``` ### Swarm Workflows ```bash # Bull/bear debate on a stock vibe-trading --swarm-run investment_committee '{"topic": "Is TSLA a buy at current levels?"}' # Quant strategy from screening to backtest vibe-trading --swarm-run quant_strategy_desk '{"universe": "S&P 500", "horizon": "3 months"}' # Crypto desk: funding + liquidation + flow → risk manager vibe-trading --swarm-run crypto_trading_desk '{"asset": "ETH-USDT", "timeframe": "1w"}' # Global macro portfolio allocation vibe-trading --swarm-run macro_rates_fx_desk '{"focus": "Fed pivot impact on EM bonds"}' # Resume a failed or cancelled run while keeping its completed tasks vibe-trading --swarm-retry --swarm-resume ``` ### Cross-Session Memory ```bash # Save your preferences once vibe-trading run -p "Remember: I prefer RSI-based strategies, max 10% drawdown, hold period 5–20 days" # The agent recalls them in future sessions automatically vibe-trading run -p "Build a crypto strategy that fits my risk profile" ``` ### Upload & Analyze Documents ```bash # Analyze a broker export or earnings report vibe-trading --upload trades_export.csv vibe-trading run -p "Profile my trading behavior and identify any biases" vibe-trading --upload NVDA_Q1_earnings.pdf vibe-trading run -p "Summarize the key risks and beats/misses from this earnings report" ``` --- ## 🌐 API Server ```bash vibe-trading serve --port 8899 ``` | Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/runs` | List runs | | `GET` | `/runs/{run_id}` | Run details | | `GET` | `/runs/{run_id}/pine` | Multi-platform indicator export | | `POST` | `/sessions` | Create session | | `POST` | `/sessions/{id}/messages` | Send message | | `GET` | `/sessions/{id}/events` | SSE event stream | | `POST` | `/upload` | Upload a document, data file, or image | | `GET` | `/swarm/presets` | List swarm presets | | `POST` | `/swarm/runs` | Start swarm run | | `GET` | `/swarm/runs/{id}/events` | Swarm SSE stream | | `GET` | `/alpha/list` | List alphas (filter by zoo/theme/universe) | | `GET` | `/alpha/{alpha_id}` | Alpha metadata + source code | | `POST` | `/alpha/bench` | Start a bench job (returns `job_id`) | | `GET` | `/alpha/bench/{job_id}/stream` | SSE progress stream | | `GET` | `/settings/llm` | Read Web UI LLM settings | | `PUT` | `/settings/llm` | Update local LLM settings | | `GET` | `/settings/data-sources` | Read local data source settings | | `PUT` | `/settings/data-sources` | Update local data source settings | | `GET` | `/channels/status` | Read IM channel runtime and adapter status | | `POST` | `/channels/start` | Start configured IM channel adapters | | `POST` | `/channels/stop` | Stop configured IM channel adapters | | `POST` | `/channels/pairing/command` | Run a sender-pairing command against the shared store | | `POST` | `/scheduled-runs` | Create a scheduled research job (interval-ms or cron) | | `GET` | `/scheduled-runs` | List scheduled jobs | | `GET` | `/scheduled-runs/status` | Executor state and configured delivery targets | | `GET` | `/scheduled-runs/{job_id}` | Read one scheduled job | | `DELETE` | `/scheduled-runs/{job_id}` | Cancel a scheduled job | | `POST` | `/scheduled-runs/proposals/{proposal_id}/commit` | Confirm an agent-proposed create/cancel | | `POST` | `/scheduled-runs/proposals/{proposal_id}/discard` | Discard an agent proposal | | `GET` | `/scheduled-runs/playbooks` | List the research templates | | `GET` | `/scheduled-runs/playbooks/{slug}` | Show one template, with its variables | | `POST` | `/scheduled-runs/playbooks/{slug}` | Schedule a job from a template | | `POST` | `/sessions/{id}/cancel` | Stop the session's in-flight run (recorded as cancelled, not failed) | | `POST` | `/sessions/{id}/title/auto` | Summarize the first exchange into a session title (never overwrites a manual rename) | | `GET` | `/correlation/regime` | Correlation edge-density regime timeline | | `GET` | `/agents.json` · `POST` `/v1/query` | OpenBB Workspace bridge — registered only with the optional `openbb` extra; `/v1/query` requires auth | Interactive docs are available at `http://localhost:8899/docs` in keyless loopback development mode. When `API_AUTH_KEY` is configured, `/docs` and `/redoc` are disabled; authenticated tooling can fetch `/openapi.json` with an `Authorization: Bearer ` header. ### Security defaults For localhost development, `vibe-trading serve` keeps the browser workflow simple. For any non-local client, sensitive API endpoints require `API_AUTH_KEY`; use `Authorization: Bearer ` for JSON/upload requests. Browser EventSource streams are handled by the Web UI after you enter the same key once in Settings. Shell-capable process tools (`bash` / `background_run` / `cancel_background`) are enabled only for the interactive local CLI. Every other surface — the HTTP/SSE API and the MCP server on **all** transports (stdio included) — keeps them off unless you explicitly opt in with `VIBE_TRADING_ENABLE_SHELL_TOOLS=1` (or pass `--enable-shell-tools` to `vibe-trading-mcp`). Transport type never implicitly grants shell access. `cancel_background` stops only the tracked task ID returned by `background_run`; broad Python process-name termination is refused because it could terminate Vibe-Trading itself. Document and journal readers are limited to upload/import roots by default; place files under `~/.vibe-trading/uploads`, `~/.vibe-trading/runs`, `./uploads`, `./data` (or the legacy `agent/uploads` / `agent/runs`), or add a dedicated directory through `VIBE_TRADING_ALLOWED_FILE_ROOTS`. Sessions, runs, swarm runs, uploads, and the `sessions.db` index live under `~/.vibe-trading` (relocatable via the `VIBE_TRADING_HOME` shell environment variable); pre-existing history is moved there automatically on first run. Generated backtest code runs as a local Python subprocess and can make network requests through the configured market-data loaders. Its environment is intentionally narrow: the runner keeps OS/Python basics, proxy/certificate settings, `VIBE_TRADING_ALLOWED_RUN_ROOTS`, and read-only market-data keys such as `TUSHARE_TOKEN`, `FMP_API_KEY`, `FRED_API_KEY`, and `VIBE_TRADING_IWENCAI_KEY`. It does not pass LLM provider keys, API auth tokens, shell-tool switches, broker trading secrets, or live/advisory toggles to generated strategy code by default. ### Web UI Settings The Web UI Settings page lets local users update the LLM provider/model, base URL, generation parameters, reasoning effort, and optional market data credentials such as the Tushare token. Settings are persisted to `agent/.env`; provider defaults are loaded from `agent/src/providers/llm_providers.json`. Settings reads are side-effect free: `GET /settings/llm` and `GET /settings/data-sources` never create `agent/.env`, and they only return project-relative paths. Settings reads and writes can expose credential state or update credentials/runtime environment, so they require `API_AUTH_KEY` when configured. If `API_AUTH_KEY` is unset for dev mode, settings access is accepted only from loopback clients. The same Settings page includes an **IM Channels** panel for local operators. It polls `/channels/status`, shows configured/enabled/available/loaded/running states, surfaces adapter recovery hints, and can start or stop the configured channel runtime without going back to the terminal. ### Scheduled research Run a research prompt or backtest on a repeating schedule — from the **Scheduled** page in the web UI or over REST. The background executor is **off by default** — start the server with `VIBE_TRADING_ENABLE_SCHEDULER=1` to enable it: ```bash VIBE_TRADING_ENABLE_SCHEDULER=1 vibe-trading serve --port 8899 ``` Then create jobs over REST. `schedule` is either a bare integer (interval in **milliseconds**) or a 5-field cron expression (`min hour dom mon dow`; each field takes `*`, `*/n`, numbers, comma lists, or low-high ranges like `1-5`). Cron runs on the wall clock of the job's optional `timezone` (an IANA key), so the cadence holds across DST transitions — a spring-forward gap time is skipped, and a fall-back ambiguous time runs once, at its first occurrence. Jobs without a `timezone` keep plain UTC semantics: ```bash # every 6 hours (cron) curl -X POST http://localhost:8899/scheduled-runs \ -H "Content-Type: application/json" \ -d '{"prompt":"Scan CSI300 for momentum breakouts and backtest the top 5","schedule":"0 */6 * * *"}' # weekdays at 23:30 Auckland wall time — DST-proof curl -X POST http://localhost:8899/scheduled-runs \ -H "Content-Type: application/json" \ -d '{"prompt":"Pre-open scan of NZX names","schedule":"30 23 * * 1-5","timezone":"Pacific/Auckland"}' # list / cancel curl http://localhost:8899/scheduled-runs curl -X DELETE http://localhost:8899/scheduled-runs/ ``` Each fire runs the `prompt` through a fresh agent session (optional backtest parameters go in `config`), and jobs persist under `~/.vibe-trading/` so they survive restarts. Without the flag, the `/scheduled-runs` endpoints still record jobs but nothing fires. Add `-H "Authorization: Bearer "` to each call when `API_AUTH_KEY` is set. The agent sees exactly one scheduling tool, `scheduled_research`. Its read actions inspect status/jobs/playbooks; `propose_create` and `propose_cancel` only persist a short-lived confirmation proposal. They never mutate the job store. Web renders a deterministic confirmation card, CLI asks `y/N`, and IM conversations require an exact `confirm` (`确认`) or `cancel` (`取消`); only that surface action calls the commit endpoint. Create drafts carry `title`, `source`, `schedule`, `end_at`, and `delivery`. Once `end_at` passes, the retained job becomes `expired` and is not dispatched again. Scheduled delivery is channel-agnostic. Configure reusable opaque target refs under `channels.deliveryTargets`; the agent tool and its confirmation surfaces expose the ref, label, and channel but never the provider's raw chat/user id. The existing direct REST/admin fields remain available for backward compatibility: ```json { "channels": { "deliveryTargets": { "research-team": { "label": "Research Team", "channel": "feishu", "target": "" } } } } ``` Any configured channel adapter can be selected. Delivery status is `accepted` when an adapter succeeded without a provider receipt, and `sent` only when the adapter returned a provider message id (currently implemented end to end for Feishu). Failures remain retryable in the persisted outbox. **Five ready-to-schedule templates** ship with the scheduler — `premarket-brief`, `earnings-season-tracker`, `portfolio-checkup`, `a-share-money-flow`, `institutional-holdings-diff`. Each states the data a run needs in plain language instead of naming tools, so a template keeps working as the tool surface grows, and each is required to name a missing input rather than fill it from memory. Reach them from the CLI, over REST, or with `/playbook` in the TUI: ```bash vibe-trading playbook list # the five templates vibe-trading playbook show premarket-brief # body, declared variables, suggested cadence vibe-trading playbook create premarket-brief \ --var home_market="US equities" --var watchlist="AAPL, MSFT, NVDA" \ --timezone America/New_York curl http://localhost:8899/scheduled-runs/playbooks curl http://localhost:8899/scheduled-runs/playbooks/premarket-brief curl -X POST http://localhost:8899/scheduled-runs/playbooks/premarket-brief \ -H "Content-Type: application/json" \ -d '{"variables":{"home_market":"US equities","watchlist":"AAPL, MSFT, NVDA"}}' ``` Posting `{}` schedules a template on its own suggested cadence with its declared defaults. The rendered body becomes the job prompt verbatim, and an undeclared variable is rejected rather than silently ignored. --- ## 🔌 MCP Plugin Vibe-Trading exposes 74 MCP tools for any MCP-compatible client. Runs as a stdio subprocess — no server setup needed. Core research tools work with zero API keys for HK/US/crypto; trading connector tools use the selected connector profile, and `run_swarm` needs an LLM key. **Environment variables:** the client spawns the server itself, so a shell `export` never reaches it — set them in the client's `env` block. Generated backtest code is sandboxed to the allowed run roots, so writing results into a workspace of your own needs `VIBE_TRADING_ALLOWED_RUN_ROOTS`: ```json { "mcpServers": { "vibe-trading": { "command": "vibe-trading-mcp", "env": { "VIBE_TRADING_ALLOWED_RUN_ROOTS": "C:\\Users\\me\\research" } } } } ```

Claude Desktop

Add to `claude_desktop_config.json`: ```json { "mcpServers": { "vibe-trading": { "command": "vibe-trading-mcp" } } } ```

OpenClaw

Add to `~/.openclaw/config.yaml`: ```yaml skills: - name: vibe-trading command: vibe-trading-mcp ``` For a first research-only smoke test, confirm tool discovery and run a market data or backtest request before selecting a trading connector profile. Core research tools can run without broker credentials; connector-backed `trading_*` tools should be used only after you intentionally select and check a connector profile. `run_swarm` requires an LLM key.

Cursor / Windsurf / other MCP clients

```bash vibe-trading-mcp # stdio (default) vibe-trading-mcp --transport http # Streamable HTTP (current MCP spec default) at http://127.0.0.1:8900/mcp vibe-trading-mcp --transport sse # legacy SSE (deprecated) for older clients ``` For HTTP clients (QwenPaw, and any client that negotiates by POSTing an `InitializeRequest`), use `--transport http` and point the client at the single `/mcp` endpoint — e.g. `http://127.0.0.1:8900/mcp`. Do **not** point an HTTP client at `/sse`; that path belongs to the deprecated two-endpoint SSE transport and will return `405 Method Not Allowed` on `POST`. Override the bind address with `--host` / `--port`.

**MCP tools exposed (74):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `list_strategies`, `query_strategies`, `get_strategy_evidence`, `refresh_strategy_evidence`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`, `quantlib_call`, `cashflow_performance`, `orderbook_depth`, `sentiment`, `technical_indicators`, `get_fundamentals`. ### SWARM external MCP tools `run_swarm` workers can call operator-approved tools from external MCP servers. Configure the server-side allowlist in `VIBE_TRADING_SWARM_AGENT_CONFIG`, `~/.vibe-trading/swarm-agent.json`, or the fallback `~/.vibe-trading/agent.json`; then list remote tools in a swarm preset using the local MCP wrapper name, such as `mcp_internal_kb_search`. Caller-provided `variables` stay template data only and cannot inject MCP URLs, commands, environment variables, or allowlist overrides.

Install from ClawHub (one command)

```bash npx clawhub@latest install vibe-trading --force ``` > `--force` is required because the skill references external APIs, which triggers VirusTotal's automated scan. The code is fully open-source and safe to inspect. This downloads the skill + MCP config into your agent's skills directory. No cloning needed. Browse on ClawHub: [clawhub.ai/skills/vibe-trading](https://clawhub.ai/skills/vibe-trading)

OpenSpace — self-evolving skills

All 90 finance skills are published on [open-space.cloud](https://open-space.cloud) and evolve autonomously through OpenSpace's self-evolution engine. To use with OpenSpace, add both MCP servers to your agent config: ```json { "mcpServers": { "openspace": { "command": "openspace-mcp", "toolTimeout": 600, "env": { "OPENSPACE_HOST_SKILL_DIRS": "/path/to/vibe-trading/agent/src/skills", "OPENSPACE_WORKSPACE": "/path/to/OpenSpace" } }, "vibe-trading": { "command": "vibe-trading-mcp" } } } ``` OpenSpace will auto-discover all 90 skills, enabling auto-fix, auto-improve, and community sharing. Search for Vibe-Trading skills via `search_skills("finance backtest")` in any OpenSpace-connected agent.

--- ### MetaTrader 5 (Exness and other MT5 brokers) Connects to a **locally running MT5 terminal** through the official `MetaTrader5` package (**Windows only**): ```bash pip install "vibe-trading-ai[mt5]" ``` Configure `~/.vibe-trading/mt5.json` (create it yourself; `chmod 600` where supported): ```json { "login": 12345678, "password": "...", "server": "Exness-MT5Trial8", "symbol_suffix": "m", "max_order_volume": 1.0, "max_order_notional_usd": 10000 } ``` Then: ```bash vibe-trading connector use mt5-paper-sdk vibe-trading connector check vibe-trading connector account vibe-trading connector quote EURUSD vibe-trading connector history EURUSD ``` | Profile | Account | Orders | |---------|---------|--------| | `mt5-paper-sdk` | demo | read-only | | `mt5-live-sdk-readonly` | real | read-only | | `mt5-paper-trade` | demo | direct placement (connector per-order size guards apply) | | `mt5-live-trade` | real | mandate + kill-switch gated | Safety boundary: **"paper" means the broker's own demo account**, re-verified on every call — the terminal reports `account_info().trade_mode` and the logged-in account number, so pointing a paper profile at a real-money account (or the reverse) is refused outright. MT5 sizes orders in **lots** (1 lot EURUSD = 100,000 EUR); the live mandate gate prices lots through the connector's USD hook, and the connector's own `max_order_volume` / `max_order_notional_usd` guards apply on demo as well as live, failing closed when a notional cannot be priced. On hedging accounts (the Exness default), note that an opposing order **opens a hedge position** — close by ticket instead (pass the position ticket to `trading_cancel_order`) so the fill is pinned to that position and can only reduce exposure. Rollback / halt path: the kill switch blocks new live orders, while cancellation stays available and is written to the audit log. Mandate limits are denominated in USD; a non-USD account currency is margined by the broker in its own currency. The `mt5` market-data loader — the head of the forex fallback chain — shares this same `mt5.json`. With no such file it attaches read-only to the most recently used terminal that is already logged in. --- ## 🔌 eToro Public API Connector Connects to [eToro's Public API](https://builders.etoro.com/) for demo and real accounts via API key pair (`x-api-key` + `x-user-key`). Demo and real environments are separated structurally: demo keys only reach `/demo` API paths. Configure `~/.vibe-trading/etoro.json` (create it yourself; `chmod 600` where supported): ```json { "api_key": "YOUR_PUBLIC_API_KEY", "user_key": "YOUR_USER_KEY", "profile": "paper" } ``` Alternatively set `ETORO_API_KEY` and `ETORO_USER_KEY` in `~/.vibe-trading/.env`. Then: ```bash vibe-trading connector use etoro-paper-sdk vibe-trading connector check vibe-trading connector account vibe-trading connector positions vibe-trading connector quote BTC ``` | Profile | Account | Orders | |---------|---------|--------| | `etoro-paper-sdk` | demo | read-only | | `etoro-live-sdk-readonly` | real | read-only | | `etoro-paper-trade` | demo | direct placement on demo paths | | `etoro-live-trade` | real | mandate + kill-switch gated | Symbol lookup uses eToro's `internalSymbolFull` search (e.g. `BTC` → instrument id `100000`). Use the `etoro_search_instruments` agent tool to resolve tickers before trading. Safety boundary: demo and real are path-separated and key-bound (`paper_guard: path_separated_key_bound`). Live risk-increasing actions (open and copy-start/increase) require an authorized mandate, a clear halt state, and a verified USD account for copy-notional enforcement. Validated full and partial position closes, open-order cancellation, and copy close remain available when halted and are audit-logged. Cancelling a pending close or editing position stops is paper-only: the live path fails closed because those operations can increase exposure or transfer extra margin without enough API data to quantify the incremental USD risk. Copy amounts are denominated in the eToro account currency, and every copy start/adjust requires a caller-supplied 1-35 character URL-safe reference id for polling. eToro-specific write tools (`etoro_close_position`, `etoro_copy_*`, etc.) are agent tools only — not exposed via MCP or CLI. Rollback: revert the connector commit(s) or disable profiles; halt blocks new live risk-increasing actions. --- ## 🔌 Loading Tools from External MCP Servers (MCP Client Mode) > **This is the opposite direction from the MCP Plugin above.** > The MCP Plugin lets *other* agents call Vibe-Trading tools. > This section lets the *built-in* Vibe-Trading agent call tools from *your* external MCP servers. ### Quick start Create `~/.vibe-trading/agent.json`: ```json { "mcpServers": { "my-server": { "command": "uvx", "args": ["my-mcp-server"] } } } ``` Run any CLI command — tools from ordinary external servers are automatically injected into the agent's registry after local tools: ```bash vibe-trading run "use my-server to do X" ``` ### Official IBKR MCP read-only probe Vibe-Trading can connect directly to Interactive Brokers' official remote MCP endpoint in read-only mode. Add this to `~/.vibe-trading/agent.json`: ```json { "mcpServers": { "ibkr": { "type": "streamableHttp", "url": "https://api.ibkr.com/v1/api/mcp-public", "auth": { "type": "oauth", "scopes": ["mcp.read"], "clientName": "Vibe-Trading", "cacheDir": "~/.vibe-trading/live/ibkr/oauth" }, "enabledTools": ["*"] } } } ``` Then start the browser OAuth flow: ```bash vibe-trading connector authorize ibkr-live-official-mcp-readonly ``` The wildcard is accepted only for IBKR's `mcp.read` probe. Authorizing this profile confirms access to IBKR's official read scope; generic `trading_account` and `trading_positions` calls stay disabled until IBKR publishes stable read tool names that Vibe-Trading can map safely. A config that adds `mcp.write` must pin an explicit tool allowlist and still passes through the live order guard. If IBKR issues a pre-registered OAuth client, add `clientId` and `clientSecret` inside `auth`. ### Trading connectors: fastest path For users who cannot wait for IBKR OAuth client approval, connect to a local TWS or IB Gateway session. Credentials stay inside IBKR's desktop app; Vibe- Trading only connects to `127.0.0.1` and exposes it as a connector profile. Install the optional SDK: ```bash pip install "vibe-trading-ai[ibkr]" ``` Open TWS paper trading or IB Gateway paper, enable API socket clients, then run: ```bash vibe-trading connector list vibe-trading connector use ibkr-paper-local vibe-trading connector configure ibkr-paper-local --yes vibe-trading connector check vibe-trading connector account vibe-trading connector positions vibe-trading connector orders vibe-trading connector quote AAPL vibe-trading connector history AAPL --duration "30 D" --bar-size "1 day" ``` Default local ports: | App | Paper | Live read-only | |-----|-------|----------------| | TWS | `7497` | `7496` | | IB Gateway | `4002` | `4001` | The agent exposes connector-scoped tools named `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, and `trading_history`. Live-broker raw MCP tools are not registered directly as `mcp__*`. No IBKR order-placement tool is registered. ### 🔐 TAP Mode — full credential isolation & human-approved writes **Opt-in, off by default.** If the `TAP_*` variables below are unset, the connector behaves exactly as before (direct broker SDK) — nothing changes. [TAP](https://tap.human.tech) (Tool Authorization Protocol) is a credential proxy: the agent never holds the raw broker API secret, and consequential writes are gated on **human approval**. With TAP mode on, **every** Alpaca call — order placement, cancel, and the reads (account/positions/orders/quote/bars) — is sent to the TAP proxy's `/forward` endpoint instead of the broker SDK; TAP injects the real key server-side, then forwards upstream. - The agent process holds **no Alpaca key at all** — and doesn't even need `alpaca-py` — because the whole egress goes through TAP. The secret is referenced by name (``) and TAP substitutes it. - **Writes block on human approval.** An order or cancel cannot reach the broker without a human approving it; even a prompt-injected "buy now" is held, and denying it means it never reaches Alpaca. Orders carry a deterministic `client_order_id`, so an approval-race retry is deduplicated rather than double-placed. - **Reads auto-approve.** Account/positions/orders/quote/bars are GETs that TAP forwards without a human step — this is credential *isolation* (no key in the process), not a gate, so there's ~zero added friction. - `allowed_hosts` on the TAP credential pins where the key may be sent, so a tampered target is rejected (403) before injection. **Enable it:** 1. In the TAP dashboard, create a **multi-secret** credential named `alpaca` holding your Alpaca key pair as fields `key_id` and `secret_key`, assigned to your agent, with allowed hosts `paper-api.alpaca.markets` (or the live host `api.alpaca.markets`) **and** `data.alpaca.markets` (the market-data host used by quote/bars). Use **separate TAP credentials for paper and live** (e.g. `alpaca-paper` / `alpaca-live`, selected via `TAP_ALPACA_CREDENTIAL`), each with `allowed_hosts` pinned to its own API host — TAP then structurally refuses to send the paper key to the live host and vice versa, keeping the paper/live separation crisp end to end. 2. Add to `agent/.env`: | Variable | Required | Description | |----------|:--------:|-------------| | `TAP_PROXY_URL` | Yes | TAP proxy base URL (e.g. `https://proxy.tap.human.tech`) | | `TAP_AGENT_KEY` | Yes | Your TAP agent API key (secret) | | `TAP_ALPACA_CREDENTIAL` | No | TAP credential name for Alpaca (default `alpaca`) | | `TAP_APPROVAL_TIMEOUT` | No | Seconds to wait for a human decision (default `300`) | When a write is placed, approve or deny it in your TAP channel (Telegram / dashboard). An approved order/cancel is forwarded to Alpaca; a denied or timed-out one returns an error and is **never sent**. > **Known limitation — approval race.** If the human approves right at the > `TAP_APPROVAL_TIMEOUT` boundary, TAP may forward the order while the poll has > already given up: the gate then reports an error even though the order reached > the broker, and the `max_trades_per_day` counter under-counts by one. The > deterministic `client_order_id` keeps a retry from double-placing that order; > if you rely on a tight trades-per-day cap, check open orders after a TAP > timeout error before retrying. **Scope:** covers Alpaca **order placement, cancel, and all five reads** — the full connector egress, so the process holds no key on any path. HMAC-signed brokers (Binance/OKX) are follow-ups (client-side signing doesn't fit pure egress injection). The hooks are additive — they live inside the Alpaca connector and leave the live mandate gate unchanged. ### Config reference | Field | Type | Default | Description | |-------|------|---------|-------------| | `type` | string | inferred for stdio; required for HTTP | Omit for stdio, or set to `sse` / `streamableHttp` for URL-based servers. | | `command` | string | required for stdio | Executable to spawn for stdio servers. Invalid for `sse` / `streamableHttp` servers. | | `args` | array | `[]` | Command-line arguments for stdio servers only. | | `env` | object | `{}` | Extra environment variables merged into the subprocess env for stdio servers only. | | `url` | string | required for `sse` / `streamableHttp` | Remote SSE / streamable HTTP endpoint URL. Not used for stdio servers. | | `headers` | object | `{}` | Extra HTTP headers for `sse` / `streamableHttp` servers only. | | `toolTimeout` | number | `30` | Per-tool call timeout in seconds | | `initTimeout` | number | unset (`max(toolTimeout, 30)`) | MCP initialize / OAuth authorization timeout in seconds. Use this for slow browser authorization without widening ordinary tool calls. | | `enabledTools` | array | `["*"]` | Tool allowlist. Use `["*"]` to expose all tools from the server | Config file location: `~/.vibe-trading/agent.json` (JSON or YAML). For URL-based transports, `type` is required. The agent no longer guesses between SSE and streamable HTTP from the URL suffix. ### Per-session overrides (API) When creating a session via the API you can pass `mcpServers` inside `session.config` to extend or override the global config for that session only: ```json { "config": { "mcpServers": { "research-server": { "command": "uvx", "args": ["research-mcp"], "enabledTools": ["search", "fetch"] } } } } ``` ### Tool naming Ordinary remote tools are exposed with stable names: `mcp__`. Live-broker MCP servers stay behind the `trading_*` connector surface. If two server names produce the same ASCII-safe local prefix (e.g. `foo-bar` and `foo_bar` both become `foo_bar`), a deterministic hash suffix is appended at the server-segment level so names remain unique. The operator receives a warning: ``` WARNING: Configured MCP server 'foo-bar' collides with another server after local name normalization. Using local tool prefix 'mcp_foo_bar__' to keep generated tool names unique. Rename the server in agent config if you want a different prefix. ``` ### v1 limits | Limit | Detail | |-------|--------| | Transport | stdio, SSE, and streamable HTTP | | Execution | serial only — MCP tools never enter the parallel readonly path | | Surfaces | tools only (resources and prompts excluded in v1) | | Hot reload | not supported — restart the process to pick up config changes | | Swarm path | MCP tools are not available inside Swarm worker registries in v1 | --- ## 📁 Project Structure

Click to expand

``` Vibe-Trading/ ├── agent/ # Backend (Python) │ ├── cli/ # CLI package — interactive TUI + subcommands │ ├── api_server.py # FastAPI server — runs, sessions, upload, swarm, SSE │ ├── mcp_server.py # MCP server — 74 tools for OpenClaw / Claude Desktop │ │ │ ├── src/ │ │ ├── agent/ # ReAct agent core │ │ │ ├── loop.py # 5-layer compression + read/write tool batching │ │ │ ├── context.py # system prompt + auto-recall from persistent memory │ │ │ ├── skills.py # skill loader (90 bundled + user-created via CRUD) │ │ │ ├── tools.py # tool base class + registry │ │ │ ├── memory.py # lightweight workspace state per run │ │ │ ├── frontmatter.py # shared YAML frontmatter parser │ │ │ └── trace.py # execution trace writer │ │ │ │ │ ├── memory/ # Cross-session persistent memory │ │ │ └── persistent.py # file-based memory (~/.vibe-trading/memory/) │ │ │ │ │ ├── tools/ # 107 auto-discovered agent tools │ │ │ ├── backtest_tool.py # run backtests │ │ │ ├── remember_tool.py # cross-session memory (save/recall/forget) │ │ │ ├── skill_writer_tool.py # skill CRUD (save/patch/delete/file) │ │ │ ├── session_search_tool.py # FTS5 cross-session search │ │ │ ├── swarm_tool.py # launch swarm teams │ │ │ ├── web_search_tool.py # DuckDuckGo web search │ │ │ └── ... # bash, file I/O, factor analysis, options, alpha browser + bench, etc. │ │ │ │ │ ├── factors/ # Alpha Zoo — 462 alphas across 5 families │ │ │ ├── base.py # 19 operators (rank/scale/ts_*/delta/decay_linear/safe_div/vwap) │ │ │ ├── registry.py # AST-only metadata load + lazy compute + sanity gates │ │ │ ├── bench_runner.py # IC + alive/reversed/dead categorisation │ │ │ └── zoo/ # qlib158 (154) + alpha101 (101) + gtja191 (191) + academic (12) + fundamental (4) │ │ │ │ │ ├── api/ # FastAPI route modules │ │ │ └── alpha_routes.py # /alpha/list, /alpha/{id}, /alpha/bench, SSE stream │ │ │ │ │ ├── skills/ # 90 finance skills in 9 categories (SKILL.md each) │ │ ├── swarm/ # Swarm DAG execution engine │ │ │ └── presets/ # 30 swarm preset YAML definitions │ │ ├── session/ # Multi-turn chat + FTS5 session search │ │ └── providers/ # LLM provider abstraction │ │ │ └── backtest/ # Backtest engines │ ├── engines/ # 9 engines + composite cross-market engine + options_portfolio │ ├── loaders/ # 28 sources: tushare, okx, nobitex, wallex, binance, yfinance, akshare, baostock, tencent, mootdx, ccxt, futu, pykrx, local, eastmoney, sina, stooq, yahoo, finnhub, alphavantage, tiingo, fmp, longbridge, mt5, qveris, india_broker, tickerall, gildata │ │ ├── base.py # DataLoader Protocol │ │ └── registry.py # Registry + auto-fallback chains │ └── optimizers/ # MVO, equal vol, max div, risk parity │ ├── frontend/ # Web UI (React 19 + Vite + TypeScript) │ └── src/ │ ├── pages/ # Home, Agent, AlphaZoo, RunDetail, Compare, Correlation, Settings │ ├── components/ # chat, charts, layout │ └── stores/ # Zustand state management │ ├── Dockerfile # Multi-stage build ├── docker-compose.yml # One-command deploy ├── pyproject.toml # Package config + CLI entrypoint ├── tools/ # Repo-level CI helpers │ └── ci_grep_gates.sh # rejects yaml.load / trademark / per-stock-data leaks └── LICENSE # MIT ```

--- ## 🏛 Ecosystem Vibe-Trading is part of the **[HKUDS](https://github.com/HKUDS)** agent ecosystem:

NanoBot Ultra-Lightweight Personal AI Assistant

AI-Trader Agent-Native Signal & Copy Trading Platform

CLI-Anything Making All Software Agent-Native

OpenSpace Self-Evolving AI Agent Skills

ClawTeam Agent Swarm Intelligence

--- ## 🗺 Roadmap > We ship in phases. Items move to [Issues](https://github.com/HKUDS/Vibe-Trading/issues) when work begins. | Phase | Feature | Status | |-------|---------|--------| | **Trust Layer** | Reproducible run cards are emitted and shown in Run Detail; v1 adds tool traces and citations | v0 Shipped | | **Hypothesis Registry** | Durable research hypotheses with lifecycle status, data sources, skills, run-card links, and invalidation notes | Backend MVP Shipped | | **Research Autopilot** | Manual-first research loop: hypothesis → deterministic backtest → evidence report | Phase 1–3 Shipped | | **Data Bridge** | Bring-your-own data: local CSV/Parquet/SQL connectors with schema mapping | Local loader Shipped | | **Options Lab** | Vol surface, Greeks dashboard, payoff/scenario explorer | Analytic payoff/scenario tool **Shipped**; surface/dashboard Planned | | **Portfolio Studio** | Risk x-ray, constraints, turnover-aware optimizer, rebalance notes | Turnover-aware optimizer **Shipped 0.1.11**; rest Planned | | **Alpha Zoo** | 462 pre-built alphas (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental) with one-line bench, agent integration, and Web UI | **Shipped 0.1.8**, extended through 0.1.12 | | **Strategy Development Manager** | Register papers / broker research as factors & strategies with a persistent store + automated IC/Sharpe decay lifecycle | **Shipped 0.1.11** | | **Correlation Regime** | Edge-density + hysteresis regime timeline layered on `/correlation` — spot when markets fuse into one bloc | **Shipped 0.1.12** | | **Research Delivery** | Scheduled briefs and live research sessions through Slack / Telegram / email-style IM channels | Scheduler + IM Runtime Shipped | | **Community** | Shareable skills, presets, and strategy cards | Exploring | --- ## Contributing We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. **Good first issues** are tagged with [`good first issue`](https://github.com/HKUDS/Vibe-Trading/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — pick one and get started. Want to contribute something bigger? Check the [Roadmap](#-roadmap) above and open an issue to discuss before starting. --- ## Contributors Thanks to everyone who has contributed to Vibe-Trading! Recent v0.1.14 cycle contributors and credits: - @Shizoqua — a 13-PR correctness sweep across nearly every subsystem: grounding auto-recovers identity and price evidence within a bounded budget (#1092), swarm isolates worker artifacts between retries (#1053), rejects raw `ok`/`success` tool-result envelopes (#1052) and truncates oversized results with the shared notice (#1110), MCP gains offset paging for SEC filings and statements (#1138), routes `load_skill` through the registry so oversized skills page (#1137) and carries market-data provenance on `get_market_data` (#1131), plus `excess_return` consistency (#1058), Wilder-EWM RSI (#1056), the FTS5 tokenizer floor (#1071), non-finite prediction-market fields (#1136), in-flight delivery protection (#1140) and preserved backtest validation evidence (#1139) - @shadowinlife — the run-analysis surface, four pages in one cycle: Options Lab (#1096), the Factor Research panel with its new IC correlation matrix (#1099), positions structure visualization (#1097) and the tearsheet tab (#1091); plus evidence-gated Strategy Discovery Phase 1 (#978) and Phase 2 decay monitoring (#1007), per-market volume units in market-data provenance (#1065) and baostock volume normalized to board lots (#1067) - @pengpengyi92 — five quantlib numerics fixes: `xirr` and money-weighted return survive long-horizon discount underflow (#1119), zero-volatility options discount their forward value (#1066), the fixed-income curve keeps decay inside the requested bounds (#1076), event studies anchor to the prior session (#1078) and cross-validation aligns label ends to the prior observation (#1079) - @cgycorey — reasoning effort honoured in chat completions (#1025), the per-task swarm `ChatLLM` closed to stop a pooled-connection leak (#1145) and the same for one-shot clients (#1153), `gross_profit` derived from revenue minus COGS when the SEC tag is absent (#1111), and `vibe-trading show ` dispatching its run id instead of the flag (#1147) - @lorenzozanee — the test suite stopped escaping into the real config root and its live audit ledger (#1118, closes #1116), recovery steering delivered as user messages with inline system tags (#1112), and unsupported ticker-plus-name symbol queries marked skipped rather than failed (#1114) - @AndyLongest — the interactive backtest research dashboard (#1084), the engine reporting actual post-fill positions (#1082), and grounding ignoring identity constants in rate formulas (#1083) - @ofeksh-tr — eToro runtime UI parity for SDK connector status (#1051) and its crypto browse and flat market-data quotes (#1070), plus an empty `Response` for the `scheduled-runs` DELETE 204 (#1068) - @wiliao — the agent-run reliability pass: grounding false-rejections, the final-answer gate and LLM timeouts (#1105), with prompt wording and support/resistance masking (#1060) - @jay79-boop — a selectable IBKR market-data tier with starved quotes reported as `no_data` (#1075), and strict alpha t-stats surfaced in the bench JSON and HTML report (#1085) - @Robin1987China — DCF refusing non-finite inputs instead of a silent negative share price (#1121), and grounding masking ISO dates that run into CJK text (#1132) - @zzz607 — grounding masking line-leading ordered-list markers before number extraction (#1063), and the East Money research-report endpoint given the time parameters it now requires (#1077) - @Echoandelementwebsites — worker prompts ordered for prompt-cache-friendly prefixes (#1057), and tool-less agents no longer instructed to call `write_file` (#1144) - @549236606-oss — seven extended read-only Futu connector endpoints, each fail-closed through the existing gateway envelope (#1135) - @QCYTSN — the desktop update safety boundary: PID-scoped shutdown, dormant candidate verification, interrupted-attempt recovery, and a tested tampered/unsigned/wrong-publisher/downgrade rejection matrix (#1101) - @honginp — offline USD-M account reconciliation with immutable snapshot contracts and deterministic drift reporting (#1106) - @he-yufeng — each monitor's latest verdict parsed server-side and persisted on the job for the Market Watch list (#1152) - @sykuang — GitHub Copilot as a provider through the official SDK, with no borrowed client ID and no editor-impersonation headers (#990) - @miguelangelo78 — the hosted TickerAll MetaTrader 5 data source, so forex and metals backtests need no local MT5 terminal (#968) - @ngoanpv — Vietnam equity (HOSE) support: `.VN` no longer executes under China A-share rules (#1033) - @jax-novita — Novita AI registered as a built-in OpenAI-compatible provider (#1059) - @daviddaco1 — the Spanish locale and `README_es.md`, the sixth README (#1087) - @1psconstructor — German (Deutsch) UI support (#1117) - @x-lambda — the tencent loader building its SSL context from the certifi CA bundle, unblocking HK quotes (#1113) - @er-s-an — `build_registry()` reporting partial construction instead of silently returning a short tool list (#1129) - @straun-repo — reasoning effort passed through to the Anthropic adapter (#1115) - @nstavros — `connector orders` rendering broker_sdk rows, with SDK enum reprs stripped and class-B tickers left intact (#1150) - @lukiod — `.env.partial` created with owner-only permissions (#1086) - @fixXxerTech — inferred strategy labels marked as inferred in the run dashboard (#1134) - @birdxs — Docker images carrying the Feishu and Telegram channel dependencies, with a GHCR/Docker Hub build workflow (#1088) - @zhiwuyazhe-fjr — a Docker Codex OAuth EOF that explains itself (#1054)

v0.1.12 cycle contributors

- @santhreal — a 30-PR correctness sweep: strict-JSON / finite-number hardening across metrics, factors, pattern, and options (#764/#765/#766/#767/#739/#740/#744), loader correctness (#761 yahoo 1m bars), and session / journal robustness (#762/#763/#768/#769/#770) - @xkam7ar — broad reliability across packaging, web, scheduler, swarm, and CLI (#584), cancellation before the first AgentLoop iteration (#641, closes #638), QVeris session budget + atomic credit accounting (#685/#686), CI / OOS gates (#630/#632), and journal month-filter / side-parse fixes (#626/#628) - @shadowinlife — the Strategy Development Manager skill (#457, closes #455), pluggable OCR + LLM-vision extraction (#548), centralized provider credentials (#563), the 80× signal-alignment vectorization (#698), and swarm MCP-discovery caching (#704) - @ebujinovch — the correlation regime timeline endpoint + UI (#756, closes #719) and its `correlation-regime` skill (#557), plus the `academic_corr_rewire` factor (#705) - @honginp — Binance USD-M routing with execution/mark separation (#470/#716) and the maintenance-bracket decouple that keeps `-PERP` backtests zero-credential (#757) - @StaniellG — the MetaTrader 5 (Exness) broker connector + `mt5` data source (#481) - @tyj147454413-cmd — the Binance fallback loader (#643), bounded OKX history with rate-limit handling (#644), and codex stream-failure classification (#663) - @Marnie0415 — composite sub-engine fallback for unknown symbols (#734) and the frontend `insertBefore` streaming DOM-race fix (#717) - @YZY0108 — the look-ahead-bias fix across all five portfolio optimizers (#487) - @UNHNQ — the SiliconFlow CN + Global providers (#565) - @FenjuFu — the iFlytek Spark provider (#537) - @jelech — the native Anthropic Messages API adapter (#695) - @octo-patch — MiniMax regional API endpoints (#731) - @Thibaultjaigu — the Requesty OpenAI-compatible gateway provider (#474) - @Robin1987China — realized portfolio turnover metrics for every optimizer (#478) - @YogeshModi24 — the Frazzini-Pedersen betting-against-beta academic factor (#480) - @0xZKnw — opt-in TAP mode for Alpaca (#377) - @sambazhu — the fundamental zoo `_VALID_ZOOS` whitelist (#707) - @nareshkps — Robinhood connector `account_number` wiring (#726) - @darkknight4563 — user swarm-presets directory discovery (#570) - @MikeCer — IBKR thread-local connection pool + snapshot quotes (#636) - @Shizoqua — `local` loader interval resampling (#467) - @roberttidball — FastMCP transport import compatibility (#469) - @yxhuang — bare-ticker resolution in the correlation matrix (#472, closes #471) - @Bortlesboat — stale `OPENAI_BASE_URL` provider-switch fix (#484, closes #482) - @ananaymital — preflight `EnvConfig` stale-cache fix (#479, closes #477) - @GabbaTauchi — reported the native zai streaming / base-URL bug (#758) - @warren618 / Haozhe Wu — the correlation regime backend integration, the zai provider streaming + base-URL resolution fix (#758), release integration, and open-PR/issue triage

v0.1.11 cycle contributors

- @shadowinlife — the `api_server` modularization capstone (1,103 → 371 lines, #424 closing #331), centralized env config with the AST CI gate (#440), loader `fetch()` protocol conformance (#437), and the Strategy Development Manager RFC in review (#455/#457) — 12 merged PRs this cycle - @Robin1987China — Research Autopilot Phase 3 loop closure (#267), 4 canonical academic alphas (#277), Shadow Account PIT-safe entry conditions (#302/#314/#316), the turnover-aware portfolio optimizer (#466), scheduled-research route tests (#452), and test-coverage batches for trade-journal / pattern / loader layers (#268/#269/#276) - @muku314115 — first-class Indian equity (NSE/BSE) support: the `IndiaEquityEngine`, cost stack, `.NS`/`.BO` routing, and the `india_broker` bridge (#305) - @mvanhorn — the end-to-end scheduled-research executor (#278), the Trading 212 read-only connector (#321), OpenAI default-model resolution (#319), and Robinhood config validation (#320) - @fei-moss — the `analyze_image` vision tool (#464), NapCat DM pairing (#463), and the IM-media allowed-roots report (#465) - @sambazhu — the value-investing toolkit: financial-rigor + report-audit tools, 4 skills, and the `value_investing_committee` preset (#407/#408) - @Elfsa-Miranda — the evidence-bound alpha research pipeline exploration (#405/#416, since re-scoped into #442) - @Hinotoi-agent — loopback CSRF rejection (#293) and authenticated remote same-origin UI requests (#304) - @dpersek — configurable IM reply timeout (#413) and the provider-preflight redirect fix (#404) - @digger-yu — cross-platform `setup`/`dev` commands (#292) and dev-dependency pre-checks (#349) - @skloxo — tilde expansion + file-roots safety fallback (#299) and reactive zh-CN localization (#301) - @kadaliao — the beginner tutorial (#393) and Alpha Library social cards (#396) - @morluto — CLI resume first-message preservation (#448) and the Codex OAuth default model (#446) - @yxhuang — the Kimi for Coding provider (#435) and the precise #433 diagnosis behind the governance-stack revert - @isaveall — the `validation.json` artifacts-dir fix (#429) and clearer `--swarm-run` errors (#428) - @mustafakamal88 — timezone-aware UTC timestamps (#397) - @irfanallana-oss — the zero-size order guard in `trading_place_order` (#417) - @Shizoqua — the central OHLC-invariant loader guard (#274) - @hobostay — SSRF-guard hardening for CGNAT/mesh ranges + the QQ media redirect fix (#389) - @aeonframework — Pillow / langchain CVE floor bumps (#390) - @hannibal-lee — the pandas version-constraint fix (#329) - @MarkfuGod — dynamic data-source counts + token-gated microcompaction (#296) - @gyx09212214-prog — strict JSON validation outputs (#306) - @LemonCANDY42 — the backtest report library (#224) - @fanfpy — Longbridge Decimal→float serialization (#459) - @asahikiko — packaged SKILL.md capability-count sync + the manifest guard test (#461) - @wison1717-maker — the mandate second-confirmation dialog + unified error toasts (#453) - @imsankz — opencode provider mappings (#444) - @flash1234pku — the tushare reference code-fence fix (#449) - @Penn-Live — the Docker startup route-iteration crash report (#450) - @warren618 / Haozhe Wu — the fundamental factor layer (PIT-safe SEC panels), the QVeris premium track, the IM channel runtime, India-equity integration review, CN search fallbacks, and release integration

v0.1.10 cycle contributors

- @Hinotoi-agent — a security-hardening wave: local-shutdown auth (#241), loopback-host rebinding rejection (#242), agent shell-tool opt-in (#243), settings-write auth (#245), mandate proposal-id containment (#256), persistent-memory type validation (#257), and MCP swarm run-id containment (#258) - @mvanhorn — the opt-in local data cache (#177), Gemini thoughtSignature round-trip over OpenAI-compat tool calls (#176), the custom data loader guide (#194), and the glm/zhipu provider alias + model-name inference (#247) - @gyx09212214-prog — loader robustness for malformed crypto/RSSHub timeout env vars (#227, #240), requested yfinance end-date inclusion (#226), strict run-card JSON for non-finite metrics (#238), and ddgs retry-fallback coverage (#239) - @BillDin — swarm agent status in the chat UI (#188), explicit preset-name handling (#189), the loader-backed market-data tool for swarm workers (#199), and preset-context continuations (#200) - @Robin1987China — the Research Autopilot goal-hypothesis bridge (#260), the local CSV/Parquet/DuckDB data loader (#252), and an assistant-prefill fix + configurable Kimi User-Agent (#248) - @LemonCANDY42 — the read-only runtime status dashboard (#210), persisted AgentLoop usage artifacts (#223), and opt-in Run Detail chart payloads (#225) - @zwrong — the trace.jsonl overhaul with zero truncation + offload (#206) and session-id on exit + `resume ` (#218) - @forge-builder — the AI contributor guide (#173) and the OpenClaw MCP research-only smoke-test docs (#165) - @skloxo — Chinese (zh-CN) frontend localization (adopted from #217) - @LeeCQiang — Chinese docstrings across all 452 Alpha Zoo factors (#180) - @KaiLuettmann — GHCR pre-built image publishing on release (#187) - @ngoanpv — Gemini thought_signature preservation through the AgentLoop dict path (#184) - @ShahNewazKhan — Docker host-Ollama reachability via host.docker.internal (#196) - @sambazhu — frontend sync of completed chat attempts (#236) - @bhlt — baostock-native code format support (#230) - @octo-patch — MiniMax M3 default model upgrade (#162) - @warren618 / Haozhe Wu — the global data layer (8 sources + 18 read-only data tools), the 10 broker SDK connectors, the alpha-compare full stack, the provider-reliability overhaul, multi-engine web_search fallback, responsive Stop + SSE reconnect, and release integration

--- ## Disclaimer Vibe-Trading is research and trading software. It is not investment advice, holds no funds, and runs no execution venue. Trading through a broker channel you explicitly authorize (e.g. Robinhood Agentic Trading) happens only within the limits you set and which you can halt at any time. This broker-trading capability is experimental and not verified by us against a real broker account — use it at your own risk. Past performance does not guarantee future results. ## License MIT License — see [LICENSE](LICENSE) ---

⭐ If Vibe-Trading helps your research, a star helps more people find it.

---

Thanks for visiting Vibe-Trading ✨