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

--targets targets.json ``` ### Portfolio connector compatibility | Badge | Meaning | |-------|---------| | **Native adapter** | Dedicated portfolio normalization and valuation behavior exists for the connector. | | **Contract-tested** | Recorded connector-shaped fixtures pass the common account/position contract, but this is not a promise that every broker account variant has been live-tested. | | **Experimental** | The profile is structurally read-only and can be selected, but its currencies, account totals, or instrument semantics still need broker-specific verification. | Every position row must provide a symbol and quantity. Unsupported currencies fail the source explicitly instead of being silently treated as USD. The current valuation core supports USD, HKD and CNY; IBKR, Longbridge and Binance use native handling, while Alpaca and OKX have common-contract coverage. OKX account balance details are adapted into spot holdings alongside any open positions. Robinhood reads the one account you pick from the broker's own list (`vibe-trading connector select-account ` 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. Declared built-in profiles, generated from `agent/src/trading/profiles.py`. Each row keeps its own environment and permissions; a paper order capability never grants live trading. These are declarations, not successful runtime or broker verification. Local plugins and user connection settings are excluded. The quote column shows the declared transport, not a verified endpoint or pricing coverage. Order kinds (market, limit, etc.) are not declared in the registry and are therefore not inferred here. The placement column reports the declared mandate requirement only; it does not attest to cancellation, flattening, copy-trading, or other runtime guard coverage. Paper placement can use a broker sandbox or local simulation. See each profile's notes and the [broker bring-up checklist](CONTRIBUTING.md#broker-bring-up-checklist). | Profile | Connector | Environment | Transport | Mode | Read capabilities | Quote path (declared) | Other capabilities | Placement requirement (declared) | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `alpaca-live-sdk-readonly` | alpaca | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `alpaca-live-trade` | alpaca | live | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place.requires_mandate` | mandate required | | `alpaca-paper-sdk` | alpaca | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `alpaca-paper-trade` | alpaca | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place` | no mandate declared | | `binance-live-sdk-readonly` | binance | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `binance-live-trade` | binance | live | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place.requires_mandate` | mandate required | | `binance-paper-sdk` | binance | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `binance-paper-trade` | binance | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place` | no mandate declared | | `dhan-live-sdk-readonly` | dhan | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `dhan-paper-sdk` | dhan | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `dhan-paper-trade` | dhan | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place` | no mandate declared | | `etoro-live-sdk-readonly` | etoro | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `etoro-live-trade` | etoro | live | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `copy.close`, `copy.poll`, `copy.precheck`, `copy.start`, `orders.cancel`, `orders.cancel_close`, `orders.place.requires_mandate`, `positions.close`, `positions.edit` | mandate required | | `etoro-paper-sdk` | etoro | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `etoro-paper-trade` | etoro | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.cancel`, `orders.cancel_close`, `orders.place`, `positions.close`, `positions.edit` | no mandate declared | | `futu-live-sdk-readonly` | futu | live | broker_sdk | read-only | `acc_cash_flow.read`, `account.read`, `capital_distribution.read`, `capital_flow.read`, `earnings_calendar.read`, `financials.read`, `history.read`, `history_deals.read`, `orders.read`, `positions.read`, `quotes.read`, `rehab.read` | broker_sdk | none declared | disabled (read-only) | | `futu-live-trade` | futu | live | broker_sdk | write-enabled | `acc_cash_flow.read`, `account.read`, `capital_distribution.read`, `capital_flow.read`, `earnings_calendar.read`, `financials.read`, `history.read`, `history_deals.read`, `orders.read`, `positions.read`, `quotes.read`, `rehab.read` | broker_sdk | `orders.place.requires_mandate` | mandate required | | `futu-paper-sdk` | futu | paper | broker_sdk | read-only | `acc_cash_flow.read`, `account.read`, `capital_distribution.read`, `capital_flow.read`, `earnings_calendar.read`, `financials.read`, `history.read`, `history_deals.read`, `orders.read`, `positions.read`, `quotes.read`, `rehab.read` | broker_sdk | none declared | disabled (read-only) | | `futu-paper-trade` | futu | paper | broker_sdk | write-enabled | `acc_cash_flow.read`, `account.read`, `capital_distribution.read`, `capital_flow.read`, `earnings_calendar.read`, `financials.read`, `history.read`, `history_deals.read`, `orders.read`, `positions.read`, `quotes.read`, `rehab.read` | broker_sdk | `orders.place` | no mandate declared | | `ibkr-live-local-readonly` | ibkr | live | local_tws | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | local_tws | none declared | disabled (read-only) | | `ibkr-live-official-mcp-readonly` | ibkr | live | remote_mcp | read-only | `account.read`, `positions.read` | none declared | none declared | disabled (read-only) | | `ibkr-paper-local` | ibkr | paper | local_tws | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | local_tws | none declared | disabled (read-only) | | `kis-live-sdk-readonly` | kis | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `kis-paper-sdk` | kis | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `kis-paper-trade` | kis | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place` | no mandate declared | | `longbridge-live-sdk-readonly` | longbridge | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `longbridge-paper-sdk` | longbridge | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `longbridge-paper-trade` | longbridge | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place` | no mandate declared | | `mstock-live-rest-readonly` | mstock | live | broker_sdk | read-only | `positions.read` | none declared | none declared | disabled (read-only) | | `mt5-live-sdk-readonly` | mt5 | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `mt5-live-trade` | mt5 | live | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place.requires_mandate` | mandate required | | `mt5-paper-sdk` | mt5 | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `mt5-paper-trade` | mt5 | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place` | no mandate declared | | `okx-live-sdk-readonly` | okx | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `okx-live-trade` | okx | live | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place.requires_mandate` | mandate required | | `okx-paper-sdk` | okx | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `okx-paper-trade` | okx | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place` | no mandate declared | | `robinhood-live-mcp` | robinhood | live | remote_mcp | write-enabled | `account.read`, `orders.read`, `positions.read`, `quotes.read` | remote_mcp | `orders.place.requires_mandate`, `runner.manage.requires_mandate` | mandate required | | `robinhood-live-mcp-readonly` | robinhood | live | remote_mcp | read-only | `account.read`, `positions.read`, `quotes.read` | remote_mcp | none declared | disabled (read-only) | | `scalable-live-mcp-readonly` | scalable | live | remote_mcp | read-only | `quotes.read` | remote_mcp | none declared | disabled (read-only) | | `shoonya-live-sdk-readonly` | shoonya | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `shoonya-paper-sdk` | shoonya | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `shoonya-paper-trade` | shoonya | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place` | no mandate declared | | `tiger-live-sdk-readonly` | tiger | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `tiger-live-trade` | tiger | live | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place.requires_mandate` | mandate required | | `tiger-paper-sdk` | tiger | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `tiger-paper-trade` | tiger | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place` | no mandate declared | | `toss-live-sdk-readonly` | toss | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `trading212-live-sdk-readonly` | trading212 | live | broker_sdk | read-only | `account.read`, `instruments.read`, `order_history.read`, `orders.read`, `positions.read` | none declared | none declared | disabled (read-only) | | `trading212-paper-sdk` | trading212 | paper | broker_sdk | read-only | `account.read`, `instruments.read`, `order_history.read`, `orders.read`, `positions.read` | none declared | none declared | disabled (read-only) | | `upbit-live-sdk-readonly` | upbit | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `upbit-paper-sdk` | upbit | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `upbit-paper-trade` | upbit | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place` | no mandate declared | | `zerodha-live-sdk-readonly` | zerodha | live | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `zerodha-paper-sdk` | zerodha | paper | broker_sdk | read-only | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | none declared | disabled (read-only) | | `zerodha-paper-trade` | zerodha | paper | broker_sdk | write-enabled | `account.read`, `history.read`, `orders.read`, `positions.read`, `quotes.read` | broker_sdk | `orders.place` | no mandate declared | 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. For local IBKR and Futu connections, edit **Host / Port** in that connection's card, then click **Test** to save the address and check it. The CLI equivalent uses the same saved endpoint: ```bash vibe-trading connector setup ibkr-paper-local --connection-id my-gateway --host 127.0.0.1 --port 4002 --skip-check ``` The address is scoped to that connection and is also used by agent reads with its `connection_id`. Robinhood equity valuations show the quote's as-of time and use the more recent regular-hours or extended-hours trade. A mismatched symbol, an untraded listing, or an inactive listing cannot silently become a priced position. 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. | ### Versioned research artifacts Completed analyses can be saved as immutable revisions with their subject, universe, data-as-of date, evidence references, verification status, and optional hypothesis, goal, session, or run links. Repeating identical content and provenance returns the existing revision; changed evidence or a new data-as-of date appends a linked revision instead of overwriting the old conclusion. Search returns the latest revision of each series, while the full history remains available in the Web research-artifact library, API, agent tools, and CLI. Historical content is never presented as newly revalidated. ```bash vibe-trading research-artifact save --subject "NVDA fundamental review" --content "Conclusion with evidence." --data-as-of 2026-10-27 --evidence '[{"source_uri":"https://example.com/filing"}]' vibe-trading research-artifact search --query "NVDA" ``` --- ## 📡 Data Sources & Smart Fallback One `get_market_data` call, **29 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` | A-share + HK | none | never IP-banned | | `mootdx` | A-share (explicit-only) | none | retired from the default chain 2026-10: TDX servers stopped answering the client protocol it speaks (#1729) | | `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) | | `b3_cotahist` | Brazil (B3) | none | official daily B3 cash/odd-lot bars (raw, BRL) from the local store populated by `python -m src.br_data sync`; offline fallback for `.SA` | | `local` | any | none | your own CSV / Parquet / DuckDB via `local:` prefix | Local sources can read bar dates from a `DatetimeIndex`, with or without a configured `date_format`; an explicitly mapped date column takes precedence. **Fallback chains (by IP-ban risk):** - **A-share** → `tencent` · `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` · `gildata` · `local` - **India (NSE/BSE)** → `yahoo` · `yfinance` · `india_broker` · `local` - **Brazil (B3 `.SA`)** → `yahoo` · `yfinance` · `b3_cotahist` · `local` - **Korea (KOSPI/KOSDAQ)** → `pykrx` · `yahoo` · `yfinance` · `local` - **Indices** → `yahoo` · `yfinance` · `gildata` · `local` - **UK (LSE)** → `yahoo` · `yfinance` · `local` *(declared GBP/GBp quotes only)* - **Crypto** → `okx` · `binance` · `ccxt` · `yfinance` · `local` - **Forex / metals** → `mt5` · `akshare` · `yfinance` · `local` - **Canada / Vietnam / Argentina** → `yahoo` · `yfinance` · `local` - **China futures** → `akshare` · `local`  ·  **funds** → `tushare` · `akshare` · `local`  ·  **macro** → `akshare` · `tushare` · `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, **29 read-only data tools** reach into fundamentals & flow — fund flow, dragon-tiger, northbound, southbound, margin, block trades, shareholder count, lockup, sector, research reports, broker research search, news, SEC filings, Chinese-market announcements, financial statements, PIT fundamentals, options chains, crypto order-book depth, stock profile, market screening, symbol search, macro, China macro (EDB), iwencai, institutional holdings (13F), ETF look-through, off-exchange fund NAV, 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: 29 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` | The read-only `report_audit` tool preserves signed financial values in Markdown tables and `label: value` lines, so losses are checked as losses rather than profits. Backtest reports ground their figures in the engine's own output for that call. For list results, equivalent references such as `data.positions[0].contribution_pct` and `data.positions.0.contribution_pct` select the same element; an explicit index cannot borrow another element's value. Correction hints suggest exact references without treating the suggestion itself as evidence.

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 _{19 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), mStock (India) is read-only live over its Type B REST API (no paper account), 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) — equity read + bounded live; options order placement is not supported | | **Scalable Capital** | DE / EU | Agentic MCP (desktop OAuth) — fully read-only; no paper account exists | | **mStock** | India (NSE/BSE) | Separate holdings/net-position reads; no portfolio aggregation or orders | | **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 _{478 pre-built quant alphas across 5 families}

- 🧬 478 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** | 20 | PIT-safe SEC company facts (14, filed-date anchored: earnings yield, book-to-market, ROE, ROA, gross profitability, growth, accruals, leverage, cash-flow yields …) + A-share P/B, P/S TTM and dividend yield (3) + their Shenwan industry-neutral variants (3) | 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 _{12 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 | | **BrazilEquity** | Brazil (B3) | BRL, B3 trading + settlement fees, configurable broker fee, 1- or 100-share lots, R$0.01 tick, shorting allowed | | **ArgentinaEquity** | Argentina (BYMA) | ARS, long-only; T+2 → T+1 (2024-05-27), settlement approximated from observed sessions; same-session sale netting; declared CEDEAR ratios and credit dates; explicit tick table/panel (`ar_tick_table`) or per-instrument tick | | **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 | Benchmark selection honors `.SH`, `.SZ`, and `.BJ` A-share suffixes, plus Yahoo's `.SS` spelling for Shanghai, independently of the chosen loader, including offline local sources. Bars: 1m / 5m / 15m / 30m / 1H / 4H / 1D, plus weekly / monthly (1W / 1M, built from daily bars). 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). The turnover-aware optimizer validates per-name and group caps for single-asset allocations too. It preserves feasible supplied allocations (including cash), and raises an error when the singleton allocation exceeds a cap. When the opt-in market-data cache is enabled, local-source cache entries are scoped to the configured file, query, and column mapping. Changing a symbol's source declaration does not reuse bars from its previous source. The settled-data cache policy for an unchanged declaration remains the same. Unusable cached metadata is treated as a cache miss: the declared local source is read again, and the replacement entry can serve subsequent cache hits. The turnover-aware optimizer measures allocation changes in signed position space: reversing a 50% long to a 50% short contributes 0.5 turnover, including both the close and the reopen. Its penalty and recorded allocation turnover include these reversals; execution-derived turnover remains a separate metric. Local data date ranges include the entire UTC end day, including subsecond timestamps; bars at the following midnight are excluded before aggregation. The shared backtest market classifier recognizes `BTC/USD`, `ETH/USD`, `BNB/USD`, `SOL/USD`, `ADA/USD`, and `DOGE/USD` as crypto. Fiat pairs such as `GBP/USD`, `EUR/USD`, and `USD/JPY` retain their forex classification.

Quant Library _{309 tested functions across 25 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; schedules, accrual, key-rate tenors and yield inversion reject non-finite inputs by name. | | `credit` | Altman Z-score, Merton / KMV distance-to-default; CDS premium dates retain their configured frequency, with a final stub when maturity falls between coupons. | | `timeseries` | Stationarity, cointegration, GARCH, bootstrap; OU fits use adjacent observed lag pairs; missing observations never become artificial one-step transitions. | | `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; portfolio style exposure reports incomplete factor rows as unmatched weight. | | `neutralization` | Optional per-observation OLS/WLS factor residualization, audited control quality selection, and cross-sectional PCA at any panel frequency. [Workflow and examples](agent/src/skills/factor-research/references/neutralization.md). | | `combination` | Optional walk-forward IC/ICIR-weighted composite of several factor panels, with per-factor and composite diagnostics; a caller-supplied weight table handles any other method. [Workflow and checklist](agent/src/skills/factor-research/references/combination.md). | | `multipletesting` · `crossvalidation` | Deflated significance, purged CV; purged walk-forward splits omit folds with no training observations left after purging; Sharpe significance summaries reject non-finite inputs by name. | | `impact` | Market-impact models | | `volatility` | Heston (1993) stochastic-volatility pricing; Heston pricing requires finite inputs and a positive integration limit; invalid inputs return a domain error. | | `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. Flows use the holder's sign convention: a transfer into the portfolio is negative, and a transfer out is positive.

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 ``` `vibe-trading update` upgrades PyPI installs in place. Editable checkouts and version-control installs receive manual update guidance so their source revision is not silently replaced by a PyPI release. 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`. In Web Settings, the Codex model picker discovers available models and reasoning levels from the authenticated ChatGPT session. If discovery is unavailable, the default model and manual model entry remain available. - 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). - A local Claude Code login can drive the agent without an API key. See [Claude Code CLI provider](#claude-code-cli-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, Claude Code CLI, 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. MiniMax onboarding defaults to `MiniMax-M3.1-Flash`, with `MiniMax-M3` as the alternative in Settings. Both the global and China API endpoints are supported. Saved model IDs and custom endpoints remain editable; official MiniMax endpoints suggest the current pair, while gateways retain every discovered route, including paid variants. MiniMax uses the API's default thinking depth, and Flash's reasoning is preserved across tool turns. > **Tip:** All markets work without any API keys thanks to automatic fallback. yfinance/Yahoo (HK/US/Canada/UK), OKX (crypto), 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; tencent, baostock and AKShare are the no-token A-share fallbacks. ### 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`. ### Claude Code CLI provider The `claude-cli` provider uses the [Claude Code](https://claude.com/claude-code) CLI you already have installed and logged in. Each agent step runs one headless `claude -p` process that only chooses the next step — call these tools, or give the final answer. Vibe-Trading runs the tools itself, so the evidence ledger, grounding checks and swarm deliverable checks behave exactly as with an API provider. It does not read `ANTHROPIC_API_KEY`. Native CLI tools stay disabled. If the model tries one, Vibe-Trading feeds the refusal back and asks for a host tool call instead of accepting a claim that the tools are unavailable. Log in once with Claude Code, then check that Vibe-Trading can see the login: ```bash claude auth login vibe-trading provider login claude-cli # reports the login; it does not start a new one ``` Then configure `agent/.env`: ```dotenv LANGCHAIN_PROVIDER=claude-cli LANGCHAIN_MODEL_NAME=claude-opus-5-5 # LANGCHAIN_REASONING_EFFORT=high # low|medium|high|xhigh|max; passed as --effort # CLAUDE_CLI_PATH=/opt/homebrew/bin/claude # when `claude` is not on PATH or in ~/.local/bin # VIBE_TRADING_DENY_TOOL_PREFIXES=trading_,etoro_ # any provider; empty offers every tool # VIBE_TRADING_BASH_POLICY=python-only # any provider, or `off` # CLAUDE_CLI_DENY_TOOL_PREFIXES=trading_,etoro_ # legacy alias when the generic name is unset # CLAUDE_CLI_BASH_POLICY=python-only # legacy alias when the generic name is unset ``` - `VIBE_TRADING_DENY_TOOL_PREFIXES` hides tools whose names start with these prefixes from every provider. An explicitly configured `CLAUDE_CLI_DENY_TOOL_PREFIXES` remains the fallback alias across providers. With neither configured, other providers retain their existing tool surface; Claude CLI retains its previous `trading_,etoro_` default (including broker reads). - `VIBE_TRADING_BASH_POLICY=python-only` applies the same rule to every provider: `bash` may run only `python .py`, `python -c ...`, and read-only `ls`/`cat`/`head`/`tail`/`wc`/`pwd` on non-hidden relative paths (so not `.env`); refused calls are returned to the model so it can choose again. `CLAUDE_CLI_BASH_POLICY` remains the fallback alias. `vibe-trading provider doctor` reports the active policy and which variable supplied it. > **Warning:** Both settings are convenience filters, not a security boundary. `python -c` can still run arbitrary code, and external MCP tools (`mcp__`) are not covered by the default prefixes. Live orders stay bound by the mandate gate and kill switch whatever these settings allow. > **Note:** When Settings shows this provider, it loads the models your Claude Code login can run (cached for 5 minutes; **Load models** refreshes), and the reasoning effort menu offers only the levels the selected model accepts. The chosen level is passed to each `claude -p` call as `--effort`; it does not read or change `~/.claude/settings.json`, and "Provider default" means the model's own default. Base URL, temperature and `MAX_RETRIES` have no effect with this provider, and `TIMEOUT_SECONDS` is raised to at least 600 seconds per decision. Image input is not supported. The CLI returns each decision in one piece; while it runs, provider waiting events keep the Web UI active. Transport keepalives alone do not suppress `VIBE_TRADING_SSE_TIMEOUT` (default 90 seconds), and cancellation and the per-decision deadline remain enforced. ### 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`; `claude-cli` takes `low` through `max` plus `xhigh`, and no `none`) | | `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 | | `CLAUDE_CLI_PATH` | No | `claude` executable for the `claude-cli` provider when it is not on PATH or in `~/.local/bin` | | `VIBE_TRADING_DENY_TOOL_PREFIXES` | No | Explicit tool-name filter across every provider; empty offers every tool; unconfigured retains prior provider defaults | | `VIBE_TRADING_BASH_POLICY` | No | Explicit `python-only` or `off` across providers; unconfigured retains prior defaults (`python-only` for Claude CLI, `off` otherwise) | | `CLAUDE_CLI_DENY_TOOL_PREFIXES` | No | Legacy alias for `VIBE_TRADING_DENY_TOOL_PREFIXES`, used when the generic name is unset | | `CLAUDE_CLI_BASH_POLICY` | No | Legacy alias for `VIBE_TRADING_BASH_POLICY`, used when the generic name is unset | | `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_TRADING_ALLOWED_WRITE_ROOTS` | No | Extra comma-separated roots the agent may write or edit (e.g. `~/Documents` for report exports) | | `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. Claude Code CLI uses the local `claude` login and needs no API key or base URL.} **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. **PDF reports:** Ask the agent to save a report as PDF. `write_file` renders a `.pdf` target from Markdown/text with an embedded font; it does not need system Pango/Cairo or a font download. The Web chat provides an authenticated download link, and IM channels that support files receive the PDF as an attachment. External folders must be listed in `VIBE_TRADING_ALLOWED_WRITE_ROOTS`. Successful writes return the resolved path and byte count; a rejected path does not forbid other allowed folders. Generated downloads are staged under `~/.vibe-trading/generated_reports/` (or `VIBE_TRADING_HOME/generated_reports/`). ### 🎯 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` uses OpenRouter + `deepseek/deepseek-v4-pro`; for the DeepSeek official API, select `LANGCHAIN_PROVIDER=deepseek` and `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 478 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. **Telegram quick start (pip installation):** activate the same virtual environment in both terminals, then upgrade the package and install its Telegram adapter: ```bash python -m pip install -U "vibe-trading-ai[telegram]" vibe-trading channels --help ``` Create a bot with `@BotFather`. Merge the following into `~/.vibe-trading/agent.json`, replacing the token and sender ID (do not overwrite other channel settings). `allow_from` accepts your numeric Telegram user ID or username without `@`; listed senders do not need pairing approval. ```json { "channels": { "telegram": { "enabled": true, "token": "YOUR_BOTFATHER_TOKEN", "allow_from": ["YOUR_TELEGRAM_USER_ID"] } } } ``` Run `vibe-trading channels status --local` to check configuration and adapter availability. Start `vibe-trading serve --port 8000` in terminal 1, then run `vibe-trading channels start` in terminal 2 and send your bot a message. For another port, set `VIBE_TRADING_API_URL` to that server's URL in terminal 2. If `channels` is missing, check `python -m pip show vibe-trading-ai` in that same environment and upgrade there; installing into one environment does not update another environment's command. Missing SDK hints from `status --local` mean the optional adapter still needs installation. 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 ``` Telegram long polling permits only one active `getUpdates` poller per bot token. `vibe-trading serve` owns the channel runtime; it starts channels at startup when `VIBE_TRADING_CHANNELS_AUTO_START=true`, and the Web UI controls that same runtime. `vibe-trading channels start` sends a start request to the running API server (`VIBE_TRADING_API_URL`, default `http://127.0.0.1:8000`), so running it against that same server after auto-start does not create another poller. Keep only one API server process with a given Telegram bot token enabled. Separate server processes, or a CLI configured to target a different server, each own a runtime and can conflict when they use the same token. `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). Email and WebSocket have joined as fully-guided channels: Email's **Test connection** probes the IMAP login, the mailbox folder and the SMTP login against your provider without sending anything, while WebSocket — a local server rather than a remote service — validates the TLS certificate/key material and the address availability on this machine; an address held by the already-running server reads as the expected state, not a failure. Saving a WebSocket config hot-swaps the server, so connected clients (including the Web UI chat) briefly disconnect and reconnect. Feishu has joined them as a fully-guided channel: create a custom app on the Feishu Open Platform ([open.feishu.cn](https://open.feishu.cn/), or [open.larksuite.com](https://open.larksuite.com/) for international Lark), add the bot capability, select the matching domain in the form, copy the App ID and App Secret, verify with **Test connection** before saving, then enable; no public callback URL is needed (WebSocket long connection via the official lark-oapi 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 **Daily paper trading** is available in the Web sidebar (`/paper-trading`), `vibe-trading paper`, and the authenticated `/api/paper-accounts` API. Start today or next session with configurable cash/positions; settle completed daily bars and inspect fills, rejections and NAV history. Strategy history stops before the execution date, and each day receives the ledger after preceding fills. The agent/MCP `paper_trade_step` remains a stateless research primitive. `paper_trade_step` also takes `interval="5m"` for A-shares: one step covers one completed session and matches bar by bar against its 48 continuous five-minute bars. The 09:30 label is the opening call-auction print, single-priced on 4 of 5 probed days, and is excluded by policy; labels in 09:15-09:25 or from 14:57 up to but not including 15:00 are auction-window anomalies, and 15:00 is a continuous bar. The 5m leg uses Tushare `stk_mins`, separate from the daily chain, which serves daily bars only. It accepts one order symbol per step: the measured provider budget is 1 call/minute, 1 call/hour and 2 calls/day, and a refused call still consumes the daily budget. It fills all-or-none at each bar's `path_model` reference (`bar_median` or `bar_close`) and requires a non-empty `UNIVERSE` in strategy mode. `session`, `path_model` and `fill_model` default to the daily behaviour, so every existing call is unchanged; `session` is a coherence selector only (`cn_a` requires `market="cn_a"`) and does not change the day boundary. Known limits: a mid-range zero-calendar (HK/US) weekday with no bar for any symbol is inferred closed (`market_closed_inferred` with a warning) with no NAV row, its orders reject `suspended` and positions carry the last available close forward; an all-market zero bar on the target day is `PAPER_DATA_NOT_READY` (retryable), and a saved account advance reports `committed: false` instead of moving the watermark. The provider's bar count is authoritative: a partial session still fills with its `N/48` coverage warning. Payload faults fail closed: off-grid labels (for example a 1m payload served as 5m) and all-NaN continuous bars are `PAPER_DATA_NOT_READY`, while a zero-volume session is a halt. A 5m step with no orders issues no `stk_mins` request and follows the 1d valuation contract: it needs the target daily bar and values from that day's closes. The persistent v1.2 runner/account/store layer is a follow-up branch (`paper-trade-v12-persistence`) and is not wired to any CLI, API or MCP surface in this PR. Execution uses raw prices (Tencent raw for A-shares/HK, raw-capable US providers; Tushare `stk_mins` for the A-share 5m leg). A-shares require a complete ClickHouse calendar. Unavailable data/calendar and unverified split-like events fail visibly without committing a saved ledger; price/volume ratios never authorize multiplying a position. Cash dividends and automatic corporate-action reconciliation are not implemented. See the [paper-trading guide](agent/src/tools/paper_trade/README.md) for CLI/API examples and model limits. Daily-engine backtests report engine-specific unused settings in the run-card warnings. For example, crypto reads `maker_rate` and `taker_rate`, so supplying the A-share `commission_rate` setting warns instead of silently implying that it configured crypto fees. Shared runner/loader settings and keys read by a composite engine's selected sub-engines remain accepted. This conservative source-reader check does not trace conditional branches inside an engine and does not change options-engine configuration handling. Average holding period includes completed same-bar trades (zero bars). The existing `avg_holding_days` compatibility key reports the engine's holding-bar measure; it is not a conversion to calendar days. Standalone revalidation (`python -m backtest.validation `) runs all three validation tools using saved `config.json` validation parameters; missing parameters use the existing defaults. This includes simulation counts, seeds, bootstrap confidence, and walk-forward window count. New BaseEngine `artifacts/trades.csv` files include an `event` column: `entry` marks an opening row and `exit` marks a completed trade, including zero-PnL exits. Validation and strategy-discovery readers use this marker. Files without it retain legacy loading; their zero-PnL exits remain ambiguous. The separate options-engine trade format is unchanged. Validation also recovers entry dates from matching adjacent `entry`/`exit` rows, so walk-forward trade counts and win rates retain entry-window attribution after reload. Unmarked or unmatched rows keep the legacy timestamp fallback. ```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" } ``` Backtest run cards record the provider and model that wrote `config.json` and `code/signal_engine.py`. Set `model_training_cutoff` in `config.json` to an ISO date to record the model's cutoff; a window ending earlier is marked as potentially exposed, and an unset cutoff is treated as unknown and exposed. For strict factor benchmarks, pass `--training-cutoff YYYY-MM-DD` to `vibe-trading alpha bench --strict` to place the out-of-sample segment strictly after the cutoff. `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 ``` Bench results also carry `meta.data_availability`, a field-level contract for the loaded inputs. It records the market adapter, venue, currency, calendar, observed window, serving source, validation coverage, and an explicit status: `verified`, `assumed`, `unknown`, or `failed`. Date-only fundamental filings remain `unknown` when the source does not expose a publication timestamp, even when the bench applies its protective one-bar lag; consumers must not treat them as PIT-safe. New markets can register an adapter without changing this wire shape. Bench results also carry `meta.research`, the versioned factor-research run contract (`factor-research.run/v1`). It records the declared research stage, factor IDs, input lineage, transformations and evaluation settings so a result can be traced from Alpha Zoo inputs through later research steps. The CLI can label a run with `--research-stage`, for example: ```bash vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 \ --research-stage factor_screening ``` The v1 contract is additive provenance metadata. Its `explore`, `strict` and `locked` values describe research intent; they do not by themselves reject unknown data or enforce a locked test set. Those checks remain separate from the existing availability contract until a future policy layer enables them. **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) ``` Correlation market inference recognizes explicit crypto pairs; bare equity tickers such as `ABNB` and `SOL` use the US equity data chain. ### Trade journal fees Journal PnL includes recorded fees. When one fill closes a position and opens an opposite position, its fee is split by quantity between the two legs. Profile win rate and the average-win/average-loss ratio use the resulting net PnL of FIFO matched portions; those portions are not necessarily whole orders. Generic journals accept a complete `datetime` column or separate `date` and `time` columns (case-insensitive). Split columns are combined before sorting and FIFO matching; Excel date serials and time fractions are supported. A complete `datetime` column takes precedence when all three are present. Journal analysis rejects missing or invalid dates in any parsed record, including dividends, before applying filters. Correct those dates and retry. Buy/sell records also require finite, positive quantities before any filter is applied; correct missing or invalid quantities and retry. Cash dividends may have zero quantity. Rows with equal timestamps retain their source-file order for FIFO matching. This preserves the supplied sequence; it does not reconstruct missing fill order. ### 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 ``` Each Swarm task keeps its reports, summary and message log under `artifacts///`, so tasks assigned to the same agent retain their own output during sequential or parallel execution. Retrying a task clears only that task's output; completed task artifacts remain available to downstream workers. Resume also preserves artifacts recorded by older runs. ### 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. A background task and the notice that it finished belong to the session or swarm worker that started them: another conversation cannot list the task, read its output or cancel it, and only the owner is shown the result. 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. For Email PDF reports, an operator can set the private `pdf_password` field in Settings → IM Channels → Email. The Scheduled page then offers optional PDF protection only for PDF delivery. The password stays in Email channel config; jobs persist only the protection boolean, and requesting protection without a configured password is rejected. For CLI playbooks, add `--protect-pdf` alongside `--delivery-format pdf` and an Email destination, for example: ```bash vibe-trading playbook create premarket-brief --delivery-target-ref research-email \ --delivery-format pdf --protect-pdf ``` 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. On the Web UI, scheduled jobs can be edited in place: prompt, cadence/timezone, and delivery settings are updated with `PATCH /scheduled-runs/{job_id}` without deleting the job, so its id and run history stay intact. A job that is currently running refuses edits until that dispatch finishes. Delivery remains operator-controlled: each channel adapter describes the destination label, placeholder, and input type, while the manual target field remains available. Adapters may also expose optional known-destination suggestions; selecting one only fills that same manual field. Telegram, for example, can suggest numeric private-chat ids already present in its local `allow_from` list, while usernames and wildcards are ignored. **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 84 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 (84):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `update_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`, `read_run_artifact`, `list_backtest_runs`, `list_strategies`, `query_strategies`, `get_strategy_evidence`, `refresh_strategy_evidence`, `adapt_strategy`, `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_southbound_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`, `get_fund_nav`, `get_cn_macro_series`, `get_cn_announcements`, `search_broker_reports`, `paper_trade_step`. `web_search` tries its existing Sogou and Bing China fallbacks when ddgs returns no results or fails. Set `VIBE_TRADING_SEARCH_BING_FALLBACK=0` to disable both. This chain returns an empty result only when its enabled sources finish without an unresolved error; an unavailable source produces an actionable error if no other source returns results. To try [Parallel's hosted search MCP](https://docs.parallel.ai/integrations/mcp/quickstart) inside `web_search`, set `VIBE_TRADING_SEARCH_PARALLEL=1`. This is off by default. When enabled, searches try IQS first if `ALIYUN_IQS_API_KEY` is set, then Parallel, then the existing ddgs and regional fallbacks. Parallel receives the search query; no account or API key is required. Anonymous searches use Fast mode at lower rate limits intended for personal agents and exploration. Initialisation and tool-call timeouts are 5 and 10 seconds respectively, with no retry; these are not an overall time limit. Errors, invalid responses, and empty results fall through to the existing sources. Results keep the same title, URL, snippet, and security-warning format; Parallel snippets are capped at 300 characters. Unset `VIBE_TRADING_SEARCH_PARALLEL` or set it to `0` to restore the existing search path. `VIBE_TRADING_SEARCH_BACKENDS` still controls only the ddgs engine list. `quantlib_call` attribution requires finite sector weights and returns, finite Carino return inputs, and a finite non-negative weight-sum tolerance. Invalid data is rejected explicitly rather than returned as an attribution result containing `NaN`. Missing returns for a zero-weight sector may still be inferred from the other side. `quantlib_call` maximum-drawdown analysis measures underwater duration from the latest visit to the peak before the worst trough. An earlier drawdown that already recovered is excluded from that duration. `quantlib_call` VaR backtests count finite return/forecast pairs for coverage. Missing pairs break the consecutive-observation chain for independence testing; they never create a transition between the observations on either side of a gap. `quantlib_call` option analytics use an absolute **price** tolerance for implied-volatility inversion. A finite result must reprice the quote within that tolerance; the underlying analytics function returns `NaN` for an unconverged or volatility-unidentifiable quote rather than an asserted volatility. ### 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 } ``` For broker-confirmed `search_symbol` results, set `terminal_path` in this file to the selected terminal executable. Symbol search reads only `symbol_info` and `symbols_get`, passes no login credentials, and does not read account or position data or alter Market Watch. Without an explicit path it returns no MT5 candidate. If several broker aliases match, specify the exact native symbol (for example, `EURUSDm`) or configure `symbol_suffix`; search never chooses an alias arbitrarily or substitutes a web-search result. Backtest sandboxes receive only a validated `terminal_path` and positive finite `timeout`, not account credentials. 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. ### Live runner model spending Model calls are billed even when a mandate permits only one trade or the agent places no orders. The runner checks safety every minute, but defaults to a model decision every **15 minutes**, at most **26 decisions / 1,000,000 reported tokens per UTC day**. Each decision starts a fresh conversation and reconstructs broker state under the existing mandate gate. Configure cadence, a once-daily wall-clock time/timezone, and daily budgets in **Runtime → Model schedule and spending limits**, or the chat runner panel. Stop the runner before editing. The CLI uses the same authenticated API: ```bash vibe-trading connector runner-settings --profile robinhood-live-mcp vibe-trading connector runner-settings --profile robinhood-live-mcp --file runner-settings.json ``` The JSON accepts `interval_seconds`, optional `daily_at` (`HH:MM`) and `timezone` (IANA, default `America/New_York`), `max_daily_turns`, `max_daily_tokens`, and optional `max_daily_cost_usd`, `input_usd_per_million`, `output_usd_per_million`. Both prices are required for a dollar limit. Use the highest applicable input or cache-write price; estimates ignore cache discounts and auxiliary model calls. Daily projections need measured usage and configured prices; unknown costs stay unknown. The same settings are exposed by `GET` / `PUT /live/runner/settings?broker=robinhood`. Spending history survives restarts. Limits are checked **after each provider response**, so a response can overshoot a token or estimated-dollar budget. Exhaustion or missing usage trips the existing kill switch and cancels the active decision before its tool calls. Existing halt/cancel/flatten behavior applies; inspect the broker and usage before resuming. An unfinished decision after a crash is blocked for inspection, never silently counted as free. ### 🔐 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 — 84 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/ # 118 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 — 478 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 (20) │ │ │ │ │ ├── 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/ # 11 engines + composite cross-market engine + options_portfolio │ ├── loaders/ # 29 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, b3_cotahist │ │ ├── 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** | Run cards display hashed backtest execution records and verified CSV metric references in Run Detail and Markdown; existing cards remain readable | Backtest trace + citation display 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** | 478 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.17 cycle contributors and credits: - @rudycelekli — a 92-PR correctness sweep (13 of them landed as maintainer ports): quant-library guards and edge cases (implied-vol price tolerance #1657, gaps in VaR breach transitions #1658, Heston inputs #1719, scheduled CDS coupons #1716, Carino coincidence #1943, undefined probabilistic-Sharpe and bond-accrual inputs #1821/#1822), missing prices kept out of risk x-ray return pairs and OU lag pairs (#1717/#1713), an undefined three-scenario upside and unbounded journal ratios reported as such (#1921/#1884), document reading that keeps PDF text, Word order, PowerPoint groups and Excel missing-value markers (#1838/#1839/#1840/#1841), session search limits, locking and snippets (#1827/#1828/#1832/#1834), more secret formats redacted (#1874/#1880), A-share board limits and Beijing codes (#1913/#1914), standalone revalidation and attribution on the run's own annualisation (#1915/#1948), and settings the selected engine ignores now warned about (#1947) - @Shizoqua — 25 PRs (2 landed as ports): memory and cross-session search that read back clean and match non-English text (#1682/#1686/#1697/#1771/#1772), skill headings and saved skill names resolved consistently (#1797/#1858), Telegram and Matrix replies no longer dropped when the stream preview never sent and one WeCom stream id per reply (#1860/#1903/#1929), SSE events no longer double-delivered on reconnect (#1798), parallel CLI tool results paired with their own call (#1859), goal evidence confined to the claimed run (#1895), Carhart momentum no longer leaking today's price (#1578), Wilder RSI in the shadow account (#1457), direct-SDK positions priced from `current_price`/`ltp`/`market_val` (#1581), the email SPF/DKIM spoofing check (#1508), and swarm artifacts cleared before each fresh task (#1455) - @he-yufeng — 24 PRs (2 landed as ports): the declared grounding-check registry and the fired checks recorded in the validation artifact (#1628/#1691/#1661), corrections that keep the figures already passed (#1702), percent-named evidence read as points in derived checks (#1823), additive A-share qfq converted to multiplicative when the offsets validate (#1551), mootdx retired from the default A-share chain and the health canary (#1730), the channel-authoring contract (#1630), the compaction-helper split out of `loop.py` (#1631), the first bar's result counted against initial capital in the options engine and per-bar returns (#1750/#1844), config keys nothing reads warned about (#1935), the US early-bell close on half-days (#1706), and the ReportLab fallback for Shadow Account PDFs (#1683) - @shadowinlife — 19 PRs (5 landed as ports): daily paper trading with saved accounts across CLI, API and Web (#1939), the shared scheduler kernel adopted by the research, back-office and live loops (#1893/#1899), token usage in Run Detail, chat and swarm (#1890), `read_run_artifact` and a structured backtest tool summary (#1647/#1646), `get_southbound_flow` and a northbound flow that no longer serves a silent empty envelope (#1486/#1484), guided Web UI setup for Feishu, Slack and Discord with runtime errors surfaced in channel status (#1572/#1764/#1777/#1738/#1737), and thirteen fundamental and valuation factors, industry-neutral A-share value alphas and a monthly-horizon IC bench (#1787/#1788/#1802/#1801) - @zeus229 — 18 PRs (4 landed as ports): grounding that fails closed on unresolved derived refs and suggests exact refs (#1835/#1837/#1638), parses complete derived formulas after labels (#1728), keeps identity in ticker-keyed metrics and blank-corner matrices (#1851/#1850) and leaves execution metadata out of numeric evidence (#1767); rich Email scheduled reports with optional PDF password protection (#1680/#1709), channel-aware scheduled-run editing (#1649), reproducible indicator reads and pinned portfolio snapshots (#1768/#1769), redundant MCP payload copies removed before agent context (#1634), and goal tool-call provenance (#1688) - @alexwan02 — 16 PRs (4 landed as ports): the `claude-cli` provider backed by a local `claude -p` (#1804), Hong Kong orders sized on each symbol's own board lot (#1813), the Longbridge SDK config built through `from_apikey` (#1805), Futu multi-currency balances with average-cost basis (#1814), SDM registration that keeps its trading rules and records bench history for decay monitoring (#1848/#1849), a lightweight run preview built off the event loop (#1853), run trades listed newest first from the full trades.csv (#1865), trades.csv entry rows, offline benchmarks and Brinson weights fixed (#1780/#1781/#1782), and runtime connectors ordered by status (#1845) - @Jackzigen — 13 PRs (2 landed as ports): the first `loop.py` extractions for tool-result helpers, run outcome and tuning (#1636/#1641/#1678), a byte-stable system prompt for prefix caching (#1708), after-close SEC filings kept out of the IC until the next bar (#1794), a free BaoStock fallback for `val:*` panels (#1799), undefined correlation pairs published as null instead of 0.0 (#1933), journal PnL pooled per settlement currency (#1811), `BASE-USDT-PERP` routed to the crypto market (#1864), the mStock read-only profile (#1675), and the shared OHLCV contract assertion in per-loader suites (#1725) - @cgycorey — 12 PRs (3 landed as ports): only the engine's own output grounds a backtest report (#1685), adjusted and raw prices never mixed in one series (#1684), a stooq challenge latch that stops probing and sees every refusal (#1637/#1640), a loader health lane that says why a source is empty and keeps labelled credentials out (#1643/#1698), `get_macro_series` reporting when it caps a series (#1676), env-style credential names, URL userinfo and Basic auth redacted (#1765/#1742/#1744/#1846), and suffixed HK codes normalized for the duplicate-asset guard (#1746) - @MetaAviator — 12 PRs (2 landed as ports): full-sample downside deviation for Sortino in the metrics and options engines (#1693/#1727), initial capital in Monte Carlo path metrics (#1664), missing equity kept out of adjacent validation returns (#1754), standalone revalidation that honours saved settings and entry dates (#1815/#1842), break-even exits and zero-bar trades kept in trade artifacts and holding periods (#1779/#1876), and trade-journal fixes for reversal fees, split date/time columns, equal timestamps and invalid dates (#1891/#1900/#1941/#1942) - @lorenzozanee — unsupported Robinhood option orders gated before the broker (#1585), run cards that flag backtests possibly inside the model's training data (#1618), and option evidence in the broker bring-up checklist (#1770) - @Mikesad — LLM usage accounting extracted from `loop.py` (#1662), swarm presets that take their variables from the prompt (#1674, landed as a port), and the factor registry suite running without symlink privileges (#1696) - @remote-controlled-man — options legs priced on the run's bar cadence (#1753), the Futu journal format claimed only when its value columns exist (#1766), and three-statement balance tolerance threaded into projected periods (#1786, landed as a port) - @Romzhou — a kill-switch sweep that fails closed on its own bookkeeping and input (#1703), and a runner driver kept alive for the scheduler's lifetime (#1704) - @sambazhu — three Gildata research tools with off-exchange fund NAV (#1485), and an env-configurable ReAct iteration cap (#1833) - @wavebyrd — spread and swap rates for Yahoo `=X` forex pairs (#1930), and per-cent multipliers for ICE coffee, sugar and cotton (#1944) - @BHhhh-123 — factor neutralisation and PCA in the quant library (#1817, landed as a port) - @Bortlesboat — Calmar kept finite on explosive equity paths (#1901) - @bygordon130-hub — Pixel Office, a shared manual research-task board, and the Turkish locale (#1616) - @davidalmeida90 — profit factor reported as undefined when no trade lost (#1602) - @DrDLyuan — the equity.csv drawdown peak seeded with initial capital (#1818) - @Emad211 — per-channel configuration, custom providers and the Persian locale (#1264) - @Frank-zhu2000 — Futu profiles no longer pinning the HK trade market (#1812) - @goatyyc — Binance balances that survive clock skew, with unpriced assets marking the snapshot incomplete (#1505) - @hunters1011-ctrl — symlink tests skipped where symlinks are unavailable (#1803) - @incorpore — Brazil (B3) market data and an opt-in ZimaOS template (#1783, landed as a port) - @mdb1230 — five example options strategies and a candidate study of which to paper-trade (#1774) - @mminkus — the interactive message cap raised to match the scheduled-run path (#1701) - @passionbull — KIS reads that see SOR fills and recover from a server-invalidated token (#1726) - @rwxyx518-prog — the Portfolio page's holdings table and history chart following the display currency (#1810) - @ThreeTima — currency identity checked in financial figure grounding (#1905) - @tomaszkubiak-courses — strategy provenance model fields set on the loop, so writing a strategy file no longer raises `AttributeError` (#1673) - @xaritoku — dotenv loaded in the `alpha bench` / `alpha compare` CLI handlers (#1806)

v0.1.16 cycle contributors

- @Shizoqua — a 55-PR correctness sweep (one landed as a port) across nearly every layer: quant-library fixes and input guards (Patell z degrees of freedom #1449, copula ties #1453, Kyle's lambda intercept #1477, HRP labels #1555, non-finite impact and yield-curve inputs #1557/#1558), Alpha Zoo NaN propagation and formula fixes (gtja191_038 #1523, alpha101_074 #1534, qlib158 WVMA #1594, GTJA HIGHDAY/LOWDAY #1604), backtest sizing for negative futures prices and shorts (#1547/#1548), venue bars per year in Monte Carlo validation (#1546), options annual return over elapsed bars (#1458), memory, swarm-store and session robustness (#1450/#1525/#1545/#1536/#1579), DingTalk, Signal, Slack and Discord channel fixes (#1506/#1478/#1524/#1537), Argentina listing identity in grounding (#1575), and a mandate narrowed to zero exposure stored as zero (#1593) - @zeus229 — grounding that reads locale decimals and grouped numbers with precision-aware rounding (#1517/#1588), resolves explicit symbols and exact field refs from observed evidence (#1584/#1586), preserves `latest_date` timestamps (#1590) and keeps corrections text-only (#1600); Argentina (`.BA`) market data through Yahoo (#1543), ISO-4217 portfolio currencies with isolated FX failures (#1510), explicit header names compared case-insensitively (#1568), technical-indicator volume statistics and their replay after compaction (#1571/#1601), and bounded read-only replay after compaction (#1488) - @cgycorey — a read-only extraETF export reader (#1406) and the read-only Scalable Capital MCP connector (#1417), run cards that keep non-scalar metrics (#1424), the backtest tool naming the directory it looked in (#1429), a tool-declared swarm `run_dir` confined to the workspace and worker message logs persisted on every terminal path (#1430/#1439), qlib158 CNTP/CNTN/CNTD NaN propagation (#1459), custom zoo roots that no longer replace the bundled module (#1468), `get_shareholder_count` answering again (#1490), Tencent's A-share and HK calibers stamped correctly (#1497), and QVeris adjusted fields resolved as a complete set (#1527) - @shadowinlife — IM channels configured from the Web UI, with QQ, Email and WebSocket guided setups (#1520/#1529/#1544), stdlib logging placeholders across 12 channel adapters (#1533), Tencent history paginated backward from the end of the window (#1411), `state.json` written by the backtest tool so tool-driven runs are ingestible (#1413), per-worker swarm skill allowlists (#1414), the `1M` interval no longer folding to one minute (#1487), and welcome quick actions with a real selected state (#1500) - @he-yufeng — tail-risk measure and confidence kept through the grounding gate (#1444), full history in the risk x-ray instead of sampled rows (#1462), shareholder-count history from the per-period report (#1518), backtests attaching to a running MT5 terminal without credentials (#1598), a per-read BaoStock socket deadline (#1615), the weekly live-source health canary (#1627), the broker capability matrix generated into the README (#1629), and the channel `stop_all` and WebSocket logger fixes carried over from #1521 - @lorenzozanee — QVeris end dates no longer sent as `indicators` (#1496), dragon-tiger seat reports and lockup expiry data restored (#1512/#1513), malformed Robinhood buying power rejected (#1526), broker-only MT5 symbols resolved in `search_symbol` (#1597), hash-only traces and citations on run cards (#1612), expired Copilot CLI tokens refreshed (#1619), and Telegram polling ownership documented (#1583) - @chiww — the Stooq warning naming the override variable the config layer reads (#1402), A-shares routed by market for sources without a dedicated branch (#1431), the declared interval checked against the served bars before annualising (#1432), and `_NO_NETWORK_FALLBACK_SOURCES` honoured for per-symbol gaps (#1441) - @as950118 — three Korean broker connectors: KIS with separate paper and live hosts (#1407), Upbit capped at paper plus read-only (#1408), and read-only Toss Securities (#1409) - @0xouzm — SDM decay metrics that treat NaN and infinite bench results as missing (#1447) - @alanwilhelm — synchronized cold loader-registry initialization, so concurrent first lookups no longer see an empty registry (#1405) - @modelpath-dev — the description-driven strategy-store adaptation substrate (#1391) - @sambazhu — the Gildata A-share OHLCV loader over its raw-api MCP endpoint (#1474) - @tingkk — broker-neutral SDK diagnostics across all locales (#1436) - @tonydo — OpenCode as a built-in provider, sending the `x-opencode-session` header OpenCode Go requires (#1416) - @woshi77777stars — the `Trigger.market` default restored on non-market triggers (#1599) - @Yoruxyv — the Bahasa Indonesia UI locale and `README_id.md` (#1482)

v0.1.15 cycle contributors

- @Shizoqua — 28 PRs: NaN propagated through 16 GTJA and Alpha101 alphas instead of fabricated values (#1371/#1372/#1373/#1374/#1379/#1380/#1381/#1382/#1383) and Alpha Zoo returns no longer forward-filling gaps (#1172), missing-price gaps preserved in the SDM template and cross-market volatility weights (#1397/#1398), multi-factor and social-media factor evaluation fixes (#1399/#1400), walk-forward ML training without future-label leakage (#1392), China futures product codes parsed for digit-prefixed, month-code-colliding and lower-case symbols (#1369/#1389), composite sub-engines synced before every dispatch (#1370), per-regime position sizing in strategy discovery (#1368), MCP goal sessions isolated per connection with current-goal defaults (#1173/#1331), Codex token usage and model metadata (#1334/#1348), and swarm cancellation reaching the in-flight worker (#1175) - @he-yufeng — 26 PRs, mostly fail-closed live trading and backtest semantics: broker API errors and error envelopes fail closed in position reads and the halt sweep (#1212/#1232), the flatten latch persists across restarts (#1233), market-triggered ticks skip closed markets (#1253) and buy-limit orders are sized at the worse of quote and limit (#1312); the price-adjustment caliber stamped on served frames (#1317) with adjusted Yahoo prices (#1287), unresolved symbols retried down the fallback chain (#1288) and the stooq anti-bot challenge flagged (#1342); short option legs holding margin (#1306), perpetual funding settled by bar span (#1307), A-share and India rules enforced through composite state (#1309) and halted positions marked at the last traded close (#1332); Shadow Account PnL, attribution, FIFO short lots and cache keys (#1217/#1310/#1311/#1314); and each monitor's latest verdict rendered on the list (#1156) - @cgycorey — 23 PRs: UK (LSE `.L`) equity support (#1206), swarm replay/resume of failed runs keeping completed artifacts (#1158), market-data validation of codes, dates and sources with aligned FX/index search and fetch (#1185/#1316), dotted US class shares routed as US equity (#1351), backtest execution fixes — requested targets separated from executed fills, 1x shorts liquidated, option signals filled on the next bar, default IV for HV warm-up and over-committed baskets scaled (#1281/#1298/#1299/#1305/#1344); live halt-sweep envelopes, per-episode latches and MCP buy-limit sizing (#1244/#1254/#1361); grounding clause and metric-table gates (#1326/#1338/#1375/#1378); the registry NaN contract on declared dependencies (#1377); compaction sized by tool-call arguments (#1352); and report audits that fail closed when nothing was verified (#1362) - @santhreal — 16 PRs extending the quant library: factor risk decomposition, event-study rank and sign tests, OU calibration, drawdown analytics, barrier options, single-name CDS, key-rate duration, IC time series, Vasicek credit loss and group-purged CV (#1159–#1168), Heston pricing, HRP allocation, copulas and market microstructure (#1195–#1198), finite-difference barrier Greeks (#1203), and multi-segment test sets in cross-validation (#1204) - @AirHua-byte — multi-file drag-and-drop and paste uploads (#1179), interrupted replies recovered after a service restart (#1180), shared HTTP clients preserved during cleanup (#1182), agent-confirmed scheduled research tasks (#1187), persisted Feishu QR login credentials (#1188), explicit market context kept in grounding (#1269), and the offline harness artifact verifier (#1271) - @lorenzozanee — silent order-plan rejections surfaced through an `_on_plan_rejected` hook (#1245), the temperature self-heal on the OpenAI-compatible path (#1246), escalating stream retry delays that honour Retry-After (#1247), USD-M tolerance calibration (#1248), FMP's Stable endpoint with no silent fallback for an explicit source (#1276), adjusted prices on the FMP and Tiingo paths (#1320), and EPERM handled in desktop updater shutdown checks (#1284) - @goatyyc — the read-only multi-broker portfolio dashboard and connection framework (#1072) with connector onboarding contracts (#1250), IBKR official MCP OAuth with verified read tools (#1190), and an isolated portfolio OAuth reconnect lifecycle with classified failures (#1211/#1251) - @saju01 — the agent loop keeping tool results the model still needs (#1341), compacted results reconciled by exact call identity (#1358), and grounding that no longer reads percentage-point deltas as quoted prices (#1346/#1357) - @aminak58 — symbol identity for bare joined crypto pairs (#1265), FX, metals and futures (#1280), and spot-gold aliases (#1282) - @averatec0773 — the Anthropic static prefix cached with cache usage recorded (#1366), relocated `extra_body.temperature` stripped in the Anthropic self-heal (#1330), and an attempt start persisted so the elapsed clock survives navigation and reload (#1340) - @Elfsa-Miranda — Alpaca submissions owned before broker writes, then recovered by exact client id and exact fills across restarts (#1213/#1221/#1222) - @ethanstoner — skill-relative reference links resolved in `read_file` and on GitHub (#1252/#1328), and strategy-store history that is really newest first (#1347) - @iagop03 — Web UI fixes: a stale `streamingSessionId` cleared on reopen, a scrollable main region with collapsed long prompts, and non-backtest runs pointed to Studio (#1257/#1258/#1259) - @Robin1987China — non-finite inputs refused across valuation and credit-risk functions (#1184/#1215), and Archimedean copula CDFs stabilized under large parameters (#1386) - @Emad211 — cross-platform locks and path handling for Windows (#1261), and read-only Nobitex and Wallex market-data sources (#1263) - @honginp — read-only Binance USD-M account snapshots (#1229) and USD-M drift evidence artifacts (#1230) - @pengpengyi92 — bounded backoff on swarm worker retries (#1210), and crypto pairs resolved through an active Binance connector (#1242) - @ashutoshsinghpr7 — the Zerodha Kite Connect broker for Indian equities (#1193) - @be-student — the no-progress stop for repeated discovery without new evidence (#1363) - @BigFishEmily — paginated Tencent finance history requests (#1154) - @birdxs — Docker CI actions upgraded to Node.js 24 compatible versions (#1359) - @bonyohana — the survivorship-bias disclosure rendered in the HTML bench report (#1289) - @c020627 — the IBKR official read-only MCP seed pointed at `/mcp-public` (#1178) - @guestccc — `/api` routes proxied in the Vite dev server (#1319) - @Jackzigen — mandate adjustments that enforce narrowing for non-numeric and list fields (#1285) - @JaxonHu1024 — Futu HKD valuations preserved in the portfolio (#1228) - @laiyierjiangsu — HK-prefixed symbols (`HK.06693` → `06693.HK`) locked in grounding (#1384) - @nandofmike — the Brazilian Portuguese (pt-BR) locale (#1327) - @P1Piyush — metals treated as metals in the forex backtest: pip size, lot size and spreads (#1226) - @sambazhu — per-market data-source priority in Settings and `MARKET_DATA_ORDER_*` (#1231) - @SiMinus — `vibe-trading swarm retry` with a resume option (#1194) - @sykuang — the IBKR public MCP OAuth flow (#1186) - @thisisjun786 — calendar-triggered partial rebalancing (#1277) - @wiliao — a run-stall watchdog, a bash tree-kill timeout and a compaction verification ledger (#1169) - @youngjincho02-arch — the historical VaR quantile formula fixed in the risk-analysis skill (#1189)

v0.1.14 cycle contributors

- @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.13 cycle contributors

- @santhreal — a 21-PR correctness sweep: trade-journal date and format parsing for Excel serials, UTF-16 BOM CSVs and BTCUSDT-style symbols (#778/#794/#811/#862/#868), loader interval mapping (#812/#838), skill frontmatter closed at EOF (#861), exact memory anchors and result bounds (#956/#957), negative-equity drawdown, insolvent empty cross accounts and `inf` from zero equity (#958/#959/#1041), NaN/inf in the grounding block (#1043), null and non-finite tool arguments (#911/#913), and resource-leak and robustness fixes in the rate limiter, HTTP throttle, event bus, store and Shoonya connector (#1039/#1047/#1046/#1045/#1038) - @Robin1987China — read-only `technical_indicators` and `sentiment` tools (#921/#939), the final report aggregator stage for `quant_strategy_desk` (#1048), annualisation entries for 15 more data sources (#891), `factor_analysis` realigned on MCP to the registered tool's contract (#715), blank symbol rows skipped in the Futu and generic journal parsers (#749), loader payloads handled without sampling indicator inputs (#1005), and a real account label in CLI balances (#843) - @he-yufeng — the options payoff and scenario explorer (#883, rebuilt by the maintainer as #946), the strict alpha bench gate via `alpha bench --strict` (#796), composable optimizer weight constraints (#818), rebalance notes and risk x-ray artifacts for portfolio runs (#795/#900), yfinance crypto routed to the crypto engine (#970), and memory entries written with their `.md` suffix (#984) - @shadowinlife — memory Phase 1 lifecycle management and Tier 2 structural organization (#733/#815), QVeris discovery/inspect/execute on the MCP surface (#976, landed as a port), JSON-string list/dict arguments accepted from MCP clients (#993), HK fallback routing repaired with a Tencent HK source (#1000), and MT5 `trading_history` numpy scalars made JSON-safe (#776) - @honginp — USD-M perpetual realism: margin state contracts, isolated and cross liquidation risk, the funding and liquidation lifecycle and persisted fidelity evidence (#798/#889/#903/#936), plus opt-in atomic rebalancing integrated with strict USD-M positions (#951/#1019) - @Shizoqua — swarm detection of `ok:false` / `success:false` tool failures (#1028), importance decay in FTS5 memory ranking (#1032), remote server identity in the MCP specs cache key (#1049), and lowercase `4h` requests resampled in the yfinance loader (#1013) - @tyj147454413-cmd — three fixes split from #543 that landed with their authorship: one run per session with honest terminal states (#676), redaction of free-text tool results (#675), and durable trace records and sidecars (#662) - @cgycorey — Alpha Zoo tools exposed on MCP with a bounded `alpha_bench` (#979), and mapping-shaped Responses stream events accepted (#1034) - @darkknight4563 — opt-in non-positive prices in the daily-bar validator (#816, closes #571), and `bar_returns` keeping the real move across a long trading halt (#895) - @MuggleJinx — sessions, runs and uploads stored under the user runtime root instead of the code tree (#925), and the `connector` CLI loading `~/.vibe-trading/.env` (#902) - @00EVA — a model dropdown that resizes so full provider/model slugs are readable (#1006) - @AmirF194 — universe metadata forwarded into the `alpha bench` JSON and HTML output (#841) - @CRui5in — Web UI LLM settings saved on Windows without an HTTP 500 (#561) - @ddy4633 — the correlation matrix no longer forward-filling missing closes (#873) - @Echoandelementwebsites — dataclass tool results serialized without a false circular-reference crash (#849) - @g0rdonL — historical USD-M funding consumed, with settlement jitter rounded (#819) - @JungHoonGhae — Korea equity (KRX: KOSPI/KOSDAQ) as a backtest engine (#693, landed as a port) - @klmtseng — restated PIT fundamentals deduplicated without regressing to an older fiscal period (#772) - @ngoanpv — timezone-aware local schedules for scheduled research (#954) - @QCYTSN — live model discovery and runtime identity in Settings (#924) - @sambazhu — `temperature=1` forced for the whole Kimi K-series (#701) - @shugaoye — the OpenBB Workspace bridge (#817, landed as a port) - @TSENGCHIENFENG — the read-only Taiwan stock snapshot tool (#848, landed as a port) - @wiliao — TSX/TSXV symbols end to end, with bash-written run-dir OHLC CSVs counted as observed evidence (#1037) - @x-lambda — a config option to disable the agent proxy (#995) - @xkam7ar — partial market-data results completed through the fallback chain instead of shrinking the universe (#689, landed as a port) - @y85998607 — the vn.py export skill updated for the vn.py 4.x layout (#869) - @yagnikpipaliya — the Anthropic adapter self-healing models that deprecate `temperature` (#890) - @yrk111222 — ModelScope as an OpenAI-compatible provider (#1011)

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 ✨

### Custom model endpoints Settings → Custom OpenAI-compatible providers tests a chat-completions endpoint, saves its API key in the OS credential vault (`pip install "vibe-trading-ai[keyring]"`), and activates it for new runs. Testing sends a short model request and may incur the provider's normal API charge. Active profiles are immutable; save a changed endpoint under a new ID and activate it after testing. Switch back through the normal model provider selector. Keys are never stored in the profile JSON. The same flow is available from `vibe-trading provider custom list`, `vibe-trading provider custom add --id example --label Example --base-url https://api.example.com/v1 --model example-model` (the key is prompted privately), and `vibe-trading provider custom activate example`. The configured provider is used by CLI, API, Web, and agent runs alike. RSSHub daily event enrichment uses calendar-date keys: timezone-aware `as_of` values and daily bar labels retain their displayed date, matching the provider’s knowable-date policy. This does not convert intraday publication instants between markets. RSSHub feed `code_style` transformations separate the final venue suffix from the ticker, preserving share-class dots: `BRK.B.US` becomes `BRK.B` for `bare` routes and `USBRK.B` for `exchange_prefix`; `raw` remains unchanged.