FAQ - Vibe-Trading

Vibe-Trading is an open-source research workspace for turning finance questions into runnable analysis. It connects natural-language prompts to market-data loaders, strategy generation, backtest engines, reports, exports, and persistent research memory.

It's designed for research, simulation, and backtesting - and when you choose, autonomous trading through a broker you authorize yourself (e.g. Robinhood Agentic Trading). It holds no funds and never trades outside the limits you set, and you can halt it instantly.

Vibe-Trading supports multiple platforms:

• Desktop: Native Python CLI with rich terminal interface
• Web UI: Browser-based interface for research and backtesting
• Docker: Containerized deployment for consistent environments
• MCP Plugin: Integration with Claude Desktop, OpenClaw, Cursor, etc.
• IM Channels: Integration with 16 messaging platforms

Yes, Vibe-Trading is open-source and free to use. However, some features may require:

• API keys for certain data providers (like Tushare, Finnhub, Alpha Vantage)
• Broker accounts for live trading features
• Premium data through QVeris (optional)

The core functionality works with free data sources like yfinance, AKShare, OKX, and mootdx.

Software Requirements:

• Python 3.11+ (for local installation)
• Docker (for containerized deployment)
• Node.js (for Web UI development)

Hardware Requirements:

• Minimum: 4GB RAM, 2 CPU cores
• Recommended: 8GB+ RAM, 4+ CPU cores
• For large backtests: 16GB+ RAM, 8+ CPU cores

Network Requirements:

• Stable internet connection for data fetching
• Access to broker APIs for live trading

Backend (Python):

• Python 3.11+
• FastAPI for API server
• LangChain and LangGraph for agent framework
• pandas, numpy for data manipulation
• Pydantic for data validation
• Rich for CLI interface

Frontend (JavaScript/TypeScript):

• React 19
• Vite for build tooling
• TypeScript
• Zustand for state management
• ECharts for data visualization

There are several ways to install Vibe-Trading:

• PyPI (Recommended):

  pip install vibe-trading-ai

• Docker:

  git clone https://github.com/HKUDS/Vibe-Trading.git
  cd Vibe-Trading
  cp agent/.env.example agent/.env
  # Edit agent/.env with your settings
  docker compose up --build

• ClawHub (One Command):

  npx clawhub@latest install vibe-trading --force

• From Source:

  git clone https://github.com/HKUDS/Vibe-Trading.git
  cd Vibe-Trading
  python -m venv .venv
  source .venv/bin/activate  # Linux/macOS
  .venv\Scripts\Activate.ps1  # Windows
  pip install -e .
  cp agent/.env.example agent/.env

You need to set these environment variables in your `agent/.env` file:

• LLM Provider Setup:

  LANGCHAIN_PROVIDER=openrouter
  OPENROUTER_API_KEY=your_api_key
  LANGCHAIN_MODEL_NAME=openai/gpt-4-turbo
  LANGCHAIN_BASE_URL=https://openrouter.ai/api/v1

• Optional Data Sources:

  TUSHARE_TOKEN=your_tushare_token
  FMP_API_KEY=your_fmp_key
  FRED_API_KEY=your_fred_key

• Security (for remote access):

  API_AUTH_KEY=your_secure_key

See the full list of supported providers in the documentation.

Vibe-Trading has an automatic fallback system for data sources. You can configure them in several ways:

• Web UI Settings: Access through the UI to configure LLM providers and data sources
• CLI: Use `vibe-trading settings` command
• Environment Variables: Set in `agent/.env` file

The system automatically selects the best available source based on IP-ban risk. Free sources are tried first, then premium sources when available.

Broker connectors are configured using the CLI:

vibe-trading connector list
vibe-trading connector use <connector-name>
vibe-trading connector configure <connector-name>

Supported brokers include:

• Interactive Brokers (IBKR)
• Robinhood
• Alpaca
• OKX
• Binance
• Futu
• Longbridge
• Dhan (India)
• Shoonya (India)

Note: Most brokers require paper trading accounts for strategy testing.

You can run backtests using the CLI or Web UI:

CLI:

vibe-trading run -p "Backtest a 20/50 moving average crossover on AAPL for 2024"

Web UI:

1. Open the Web UI
2. Enter your strategy prompt in the chat
3. Click "Run" to start the backtest
4. View results and metrics

The system will automatically generate strategy code, run the backtest, and provide metrics like Sharpe ratio, max drawdown, and returns.

Vibe-Trading supports multiple markets:

• Equities:
  • A-shares (China)
  • Hong Kong stocks
  • US stocks (NYSE, NASDAQ)
  • Indian stocks (NSE, BSE)
• Crypto:
  • Perpetual futures
  • Spot trading
  • 100+ exchange pairs
• Forex: Major currency pairs
• Futures: Commodity and financial futures
• Options: Basic options strategies

The Alpha Zoo contains 461 pre-built quantitative factors across 5 families:

• Qlib 158 (Microsoft Qlib factors)
• Alpha 101 (Kakushadze formulaic alphas)
• GTJA 191 (Guotai Junan short-horizon factors)
• Academic (Fama-French, Carhart, etc.)
• Fundamental (PIT-safe SEC company facts)

You can:

• Browse factors: `vibe-trading alpha list --zoo gtja191`
• View details: `vibe-trading alpha show gtja191_171`
• Benchmark factors: `vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025`
• Compare factors: `vibe-trading alpha compare gtja191_171 gtja191_163`

Shadow Account analyzes your trading history and creates a rule-based strategy:

1. Upload your trading journal: CSV export from your broker
2. Analyze behavior: Win rate, holding period, biases
3. Extract rules: Convert patterns into explicit strategy
4. Backtest the shadow: Compare actual vs. rule-based trades
5. Generate report: HTML/PDF with insights

Use this command to start: `vibe-trading --upload trades.csv && vibe-trading run -p "Analyze my trading behavior"`

Multi-agent swarms allow you to run specialized trading teams:

• Investment Committee: Bull/bear debate with risk review
• Quant Strategy Desk: Screening to backtest pipeline
• Crypto Trading Desk: Funding/basis/liquidation analysis
• Risk Committee: Drawdown and tail risk review

Run a swarm with: `vibe-trading --swarm-run investment_committee '{"topic":"TSLA outlook"}'`

Each agent has specialized tools and the swarm results are consolidated into a single report.

Vibe-Trading maintains persistent research memory across sessions:

• Save preferences: `vibe-trading run -p "Remember I prefer momentum strategies with max 15% drawdown"`
• Recall in future sessions: Preferences are automatically loaded
• Memory management: Search, update, and delete memories
• File-based storage: Memories stored in `~/.vibe-trading/memory/`

Use CLI commands: `vibe-trading memory list`, `show`, `search`, `forget`

Vibe-Trading has 19+ data sources with automatic fallback:

• A-shares: Tencent, mootdx (TCP), Eastmoney, Baostock, AKShare, Tushare
• US/HK: Yahoo, Sina, Stooq, Eastmoney, yfinance
• Premium providers: Finnhub, Alpha Vantage, Tiingo, FMP
• Crypto: OKX, CCXT (100+ exchanges)
• India: Yahoo, yfinance, Shoonya/Dhan (broker)
• Local files: CSV, Parquet, DuckDB

The system automatically selects the best source based on IP-ban risk, with free sources tried first.

The system has a fallback chain for each market:

• A-share chain: Tencent → mootdx → Eastmoney → Baostock → AKShare → Tushare → local
• US chain: Yahoo → Stooq → Sina → Eastmoney → yfinance → Tiingo → FMP → Finnhub → AKShare → local
• HK chain: Eastmoney → Yahoo → Futu → yfinance → AKShare → local
• India chain: Yahoo → yfinance → india_broker → local

If a source fails or is rate-limited, the system automatically tries the next in the chain. You can set `source="auto"` to use this system.

QVeris is an optional premium data marketplace that adds 63+ providers to Vibe-Trading:

• Options Greeks and implied volatility
• Premium fundamental data
• Enhanced China/HK/global data
• Macroeconomic indicators
• Crypto on-chain data
• News and sentiment analysis

To enable QVeris:

1. Sign up at https://qveris.ai/ (use referral link for +1000 bonus credits)
2. Get your API key
3. Enable in Settings → QVeris or set `VIBE_TRADING_DATA_MODE=paid`

When enabled, failed premium calls are not charged.

Yes! You can add custom historical OHLCV loaders:

1. Create `agent/backtest/loaders/yourname_loader.py`
2. Implement the DataLoaderProtocol interface
3. Add to `_loader_modules` in `registry.py`
4. Add to `_VALID_SOURCES` in `runner.py`
5. Optionally add to market fallback chains

Example loader structure:

@register
class DataLoader:
    name = "yoursource"
    markets = {"us_equity"}
    requires_auth = False
    
    def is_available(self):
        return True
    
    def fetch(self, codes, start_date, end_date, interval="1D"):
        # Return {symbol: DataFrame}
        ...

Vibe-Trading supports several brokers for live trading:

• Robinhood: Agentic Trading with mandate-based controls
• Alpaca: US equities with paper/live separation
• Interactive Brokers: Global markets (read-only via MCP)
• OKX: Crypto trading with mandate controls
• Binance: Crypto trading

Important: Most brokers require paper trading accounts for strategy testing. Live trading is experimental and should be used with caution.

The mandate system provides safety controls for live trading:

• Symbol universe: Limit which assets can be traded
• Order size: Cap maximum position size
• Exposure limits: Total portfolio exposure caps
• Leverage limits: Maximum leverage allowed
• Daily trade cap: Maximum trades per day
• Kill switch: Filesystem-based emergency stop

When you enable a broker connector, you set these limits in a mandate file. The system will refuse any trades that violate the mandate.

All supported brokers offer paper trading accounts:

• Robinhood: Paper trading account
• Alpaca: Paper trading environment
• Interactive Brokers: Paper trading account
• OKX: Demo trading account
• Binance: Testnet for crypto
• Dhan/Shoonya: Paper trading for Indian markets

Paper trading allows you to test strategies with virtual money without risking real capital. Performance in paper trading may not reflect actual trading results.

To set up paper trading:

1. Open a paper trading account with your broker
2. Configure the broker connector in Vibe-Trading:

   vibe-trading connector use <broker-name>-paper
   vibe-trading connector configure <broker-name>-paper

3. Test the connection:

   vibe-trading connector account
   vibe-trading connector positions

4. Run strategies with the paper trading profile

Make sure to use the paper trading profile for all strategy testing.

Vibe-Trading implements several security measures:

• Local storage: All trading data and session information is stored locally on your machine
• Encryption: API keys and sensitive data are encrypted at rest
• Network security: All API communications use HTTPS
• Authentication: Optional API authentication key for remote access
• File permissions: Strict file access controls for generated code

Your trading data never leaves your system unless you explicitly upload it to a broker or external service.

Security features for live trading include:

• Mandate system: Predefined trading limits that cannot be overridden
• Kill switch: Filesystem-based emergency stop that immediately halts trading
• Audit trail: Complete logging of all trading decisions
• Pre-trade advisory: Optional human approval for trades
• Rate limiting: Protection against rapid-fire trading
• Broker integration: Direct broker API with no custody of funds

Remember: Vibe-Trading never holds your funds - it only sends instructions to your broker.

To secure the API server:

1. Set API auth key: Add `API_AUTH_KEY=your_secure_key` to `agent/.env`
2. Use HTTPS: Configure reverse proxy with SSL/TLS
3. Network restrictions: Bind to specific IP addresses
4. Rate limiting: Implement rate limiting at the proxy level
5. Authentication: Require authentication for sensitive endpoints

When `API_AUTH_KEY` is set, all sensitive endpoints require the key in the Authorization header.

Vibe-Trading has undergone multiple security reviews:

• External audit (July 2026): Comprehensive security audit covering all aspects of the system
• Internal reviews: Regular security reviews by the development team
• Community feedback: Security feedback from the community

All findings from the July 2026 external audit have been addressed, including:

• Docker multi-stage builds with digest-pinned images
• AST-hardened backtest sandbox
• Short-lived SSE auth tickets
• Hardened Docker Compose configuration
• Rate limiting and security headers

Research Autopilot automates the research workflow:

1. Hypothesis creation: Define research questions and criteria
2. Signal generation: Automatically create strategy engines
3. Backtesting: Run comprehensive backtests with validation
4. Analysis: Generate detailed reports with attribution
5. Iteration: Use results to refine hypotheses

Run with: `vibe-trading run -p "Run research autopilot for momentum strategies"`

This creates a complete research loop from hypothesis to validated strategy.

The Strategy Development Manager (SDM) is a tool for turning research into strategies:

• Paper analysis: Import academic papers and extract strategies
• Broker research: Convert broker research reports into strategies
• Artifact storage: Persistent storage of strategies and results
• Performance monitoring: Track IC and Sharpe decay over time
• Strategy lifecycle: Active → monitoring → decayed → disabled

Use CLI commands: `sdm_register`, `sdm_status`, `sdm_decay_scan`

You can integrate external MCP servers by adding them to `~/.vibe-trading/agent.json`:

{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-mcp-server"],
      "enabledTools": ["search", "fetch"]
    }
  }
}

Then restart Vibe-Trading. The tools from the external server will be available to the agent.

For swarm workers, you can configure external tools in swarm presets using the `mcp_internal_` prefix.

Yes! You can create custom skills:

1. Create skills in `agent/src/skills/` directory
2. Follow the existing skill structure with SKILL.md metadata
3. Implement the skill logic in Python
4. Register the skill in the skill registry
5. Use the skill in your research sessions

Skills can access all Vibe-Trading tools and data sources. They're stored in `~/.vibe-trading/skills/`.

Example skill structure:

# my_skill/SKILL.md
name: My Custom Skill
description: Does something custom
category: Analysis
version: 1.0.0

# my_skill/__init__.py
from .skill_impl import MySkill

def register():
    return MySkill

There are many ways to contribute:

• Code contributions: Fix bugs, implement features, improve documentation
• Issue reporting: Report bugs or request features
• Documentation: Improve documentation, write tutorials
• Community support: Help other users on forums and Discord
• Testing: Test new features and provide feedback

Start by checking the Contributing Guide for detailed instructions.

Look for issues tagged with "good first issue" in the GitHub repository. These are typically:

• Documentation improvements
• Small bug fixes
• Adding new data sources
• Improving error messages
• Adding tests for existing features

Check the GitHub issues for current opportunities.

There are several channels for support:

• Discord: Official Discord server for real-time discussion
• GitHub Issues: GitHub Issues for bug reports and feature requests
• Documentation: Official documentation
• WeChat/Feishu Groups: For Chinese-speaking users
• Email: For private support inquiries

Before asking for help, please check the documentation and existing issues to see if your question has already been answered.

Stay updated through these channels:

• GitHub Releases: Release notes for new versions
• News Section: Project news on the website
• Discord Announcements: Important updates in the Discord server
• Twitter/X: Official account for quick updates
• GitHub Discussions: Community discussions

The project follows a regular release schedule with major updates approximately every 2-3 weeks.