ReadyTrader-Stocks

Important Disclaimer (Read Before Use)

ReadyTrader-Stocks is provided for informational and educational purposes only and does not constitute financial, investment, legal, or tax advice. Trading stocks and equities involves substantial risk and may result in partial or total loss of funds. Past performance is not indicative of future results. You are solely responsible for any decisions, trades, configurations, supervision, and the security of your credentials/API keys. ReadyTrader-Stocks is provided “AS IS”, without warranties of any kind, and we make no guarantees regarding profitability, performance, availability, or outcomes. By using ReadyTrader-Stocks, you acknowledge and accept these risks.

See also: DISCLAIMER.md.

---

---

🌎 The Big Picture

ReadyTrader-Stocks is a specialized bridge that turns your AI Agent (like Gemini or Claude) into a professional stock trading operator.

Think of it this way: Your AI agent provides the Intelligence (analyzing charts, earnings reports, and news sentiment), while ReadyTrader-Stocks provides the Hands (connecting to brokerages and data providers) and the Safety Brakes (enforcing your risk rules). It allows you to delegate complex trading tasks to an AI without giving it unchecked access to your capital.

🛡️ The Trust Model: Intelligence vs. Execution

The core philosophy of this project is a strict separation of powers:

• The AI Agent (The Brain): Decides what and when to trade. It can research historical data, scan social media, and simulate strategies, but it has no direct power to move money.
• The MCP Server (The Guardrail): Owns the API keys and enforces your safety policies. It filters every AI request through a "Risk Guardian" that rejects any trade that is too large, too risky, or violates your personal limits.

💰 Funding Model (Non-Custodial)

ReadyTrader-Stocks operates on a User-Custodied basis. This means:

• You keep your funds: Your capital remains in your own brokerage account (e.g., Alpaca, Tradier, request Interactive Brokers).
• You control the keys: You provide API keys that allow the agent to trade but (recommended) not withdraw.
• Agent as Operator: The agent acts as a remote operator. It sends order instructions to your broker using your keys, and the broker handles actual execution and settlement.

Note: In Paper Mode (default), we simulate a virtual wallet with fake funds so you can practice without linking a real brokerage.

🔄 A Day in the Life of a Trade

1. Research: You ask your agent, "Find a good entry for AAPL." The agent calls fetch_ohlcv and get_sentiment.
2. Proposal: The agent concludes, "AAPL is oversold; I want to buy $1000 worth of shares." It calls place_market_order.
3. Governance: The MCP server checks its rules. Is $1000 within your MAX_TRADE_AMOUNT? If yes, it creates a Pending Execution.
4. Consent: If you've enabled "Human-in-the-loop," the agent notifies you. You click Confirm in the Web UI, and only then does the trade hit the market.

---

🖥️ Premium Next.js Dashboard

ReadyTrader-Stocks includes a professional Next.js dashboard for real-time monitoring, multi-agent coordination, and trade approvals.

How to Enable:

1. Navigate to the directory: cd frontend
2. Install dependencies: npm install
3. Run the development server: npm run dev
4. Access it at http://localhost:3000.

Features:

• Real-time Tickers: Low-latency price streaming via WebSockets.
• Multi-Agent Insights: Shared "Market Insights" for collaborative research.
• Mobile Guard: Push notifications for trades requiring manual approval.
• Glassmorphic UI: High-performance charting and portfolio visualization.

---

🚀 Key Features

• 📉 Paper Trading Simulator: Zero-risk practice environment with persistent balances and realistic order handling.
• 🧠 Strategy Factory: Built-in Backtesting Engine with a Strategy Marketplace for saving and sharing agent configurations.
• 📰 Advanced Intelligence: Real-time sentiment feeds from Reddit and News APIs with local NLP fallbacks.

---

⚡ 10-minute evaluation

Run both demos locally (no exchange keys, no RPC needed):

python examples/paper_quick_demo.py
python examples/stress_test_demo.py

You’ll get exportable artifacts under artifacts/demo_stress/ (gitignored).

Prompt pack (copy/paste): prompts/READYTRADER_PROMPT_PACK.md.

🛠️ Installation & Setup

Prerequisites

• Docker (Docker Compose optional)

1. Build & Run (Standalone)

Run the server in a container. It exposes stdio for MCP clients.

cd ReadyTrader-Stocks
docker build -t readytrader-stocks .
# Run interactively (to test)
docker run --rm -i readytrader-stocks

Local development (no Docker)

If you want to run or test ReadyTrader-Stocks locally:

pip install -r requirements-dev.txt
python app/main.py

2. Configuration (.env)

Create a .env file or pass environment variables. Start from env.example (copy to .env).

<details> <summary><b>🛡️ Live Trading Safety & Approval</b></summary>

Variable	Default	Description
PAPER_MODE	true	Set to false for live trading.
LIVE_TRADING_ENABLED	false	Must be true for any live execution.
TRADING_HALTED	false	Global kill switch to halt all live actions.
EXECUTION_APPROVAL_MODE	auto	auto executes immediately; approve_each requires manual confirmation.
API_PORT	8000	Port for the FastAPI/WebSocket server (api_server.py).
DISCORD_WEBHOOK_URL	""	Optional webhook for trade approval notifications.
</details>

<details> <summary><b>🔑 Exchange & Signing Credentials</b></summary>

Variable	Description
ALPACA_API_KEY	API Key for Alpaca brokerage.
ALPACA_API_SECRET	API Secret for Alpaca brokerage.
TRADIER_ACCESS_TOKEN	Access Token for Tradier.
</details>

<details> <summary><b>📈 Market Data & CCXT Tuning</b></summary>

Variable	Default	Description
MARKETDATA_EXCHANGES	alpaca	Comma-separated list of brokerages to use for data.
TICKER_CACHE_TTL_SEC	5	How long to cache price data.
ALLOW_TICKERS	*	Comma-separated allowlist of tradeable tickers.
</details>

<details> <summary><b>🛠️ Ops, Observability & Limits</b></summary>

Variable	Default	Description
RATE_LIMIT_DEFAULT_PER_MIN	120	Default API rate limit.
RISK_PROFILE	conservative	Presets for sizing and safety limits.
ALLOW_CHAINS	ethereum...	Allowlists for EVM networks.
</details>

---

Brokerage credentials

To place live orders or fetch balances, configure brokerage credentials via env.

• ALPACA_API_KEY=...
• ALPACA_API_SECRET=...
• TRADIER_ACCESS_TOKEN=...

Tools:

• place_stock_order(symbol, side, amount, order_type='market', price=0.0, exchange='alpaca', rationale='')
• get_portfolio_balance()
• reset_paper_wallet() - New: Reset all simulated data
• deposit_paper_funds(asset, amount) - New: Add virtual cash

Market-data introspection:

• get_marketdata_capabilities(exchange_id='')

Market-data introspection:

• get_marketdata_capabilities(exchange_id='')

---

🔌 Integration Guide

Option A: Agent Zero (Recommended)

To give Agent Zero these powers, add the following to your Agent Zero Settings (or agent.yaml). The MCP server key/name is arbitrary; we use readytrader_stocks in examples.

Quick copy/paste file: configs/agent_zero.mcp.yaml.

Via User Interface:

1. Go to Settings -> MCP Servers.
2. Add a new server:
   • Name: readytrader_stocks
   • Type: stdio
   • Command: docker
   • Args: run, -i, --rm, -e, PAPER_MODE=true, readytrader-stocks

Via agent.yaml:

mcp_servers:
  readytrader_stocks:
    command: "docker"
    args: 
      - "run"
      - "-i" 
      - "--rm"
      - "-e"
      - "PAPER_MODE=true"
      - "readytrader-stocks"

Prebuilt config: configs/agent_zero.mcp.yaml. Restart Agent Zero after saving.

Option B: Generic MCP Client (Claude Desktop, etc.)

Add this to your mcp-server-config.json:

Quick copy/paste file: configs/claude_desktop.mcp-server-config.json.

{
  "mcpServers": {
    "readytrader_stocks": {
      "command": "docker",
      "args": [
        "run", 
        "-i", 
        "--rm", 
        "-e", "PAPER_MODE=true", 
        "readytrader-stocks"
      ]
    }
  }
}

Prebuilt config: configs/claude_desktop.mcp-server-config.json.

---

📚 Feature Guide

Example Prompt:

"Create a mean-reversion strategy for AAPL. Write a Python function on_candle that uses RSI. Run a backtest simulation on the last 500 hours and tell me the Win Rate and PnL."

What happens:

1. Agent calls fetch_ohlcv("AAPL") to see data structure.
2. Agent writes code for on_candle(close, rsi, state).
3. Agent calls run_backtest_simulation(code, "AAPL").
4. Server runs the code in a sandbox and returns { "pnl": 15.5%, "win_rate": 60% }.

2. Paper Trading Laboratory (Zero-Key Flow)

Perfect for "interning" your agent without any paid API keys.

• Fund your account: deposit_paper_funds("USD", 100000)
• Researching Stocks: Use fetch_ohlcv and get_stock_price (powered by public yfinance data).
• Analyze Sentiment: fetch_rss_news (MarketWatch/Yahoo Finance) provides real-time "Free" signals.
• Place Orders: place_market_order("AAPL", "buy", 10)
• Reset Everything: reset_paper_wallet()

3. Market Regime & Risk

The agent can query the "weather" before flying.

• Tool: get_market_regime("AAPL")
• Output: {"regime": "TRENDING", "direction": "UP", "adx": 45.2}
• Agent Logic: "The market is Trending Up (ADX > 25). I will switch to my Trend-Following Strategy and disable Mean-Reversion."

The Guardian (Passive Safety): You don't need to do anything. If the agent tries to bet 50% of the portfolio on a whim, validate_trade_risk will BLOCK the trade automatically.

---

🧰 Tool Reference

For the complete (generated) tool catalog with signatures and docstrings, see: docs/TOOLS.md.

Category	Tool	Description
Market Data	get_stock_price	Live price from brokerage/data provider.
	fetch_ohlcv	Historical candles for research.
	get_market_regime	Trend/Chop Detection.
Intelligence	get_sentiment	Fear & Greed Index (Market).
	get_social_sentiment	X/Reddit Analysis (Financial focus).
	get_financial_news	Bloomberg/Reuters (Simulated/Real).
Trading	place_market_order	Execute market order.
	place_limit_order	Limit Order (Paper Mode).
	check_orders	Update Order Book (Paper Mode).
Account	get_portfolio_balance	Check Account Balance.
	deposit_paper_funds	Get fake money (Paper Mode).
Research	run_backtest_simulation	Run Strategy Backtest.
Research	run_synthetic_stress_test	Run synthetic black-swan stress test with deterministic replay + recommendations.

---

Built for the Agentic Future.

🧪 Synthetic Stress Testing

This MCP includes a 100% randomized (but deterministic-by-seed) synthetic market simulator. It can generate trending, ranging, and volatile regimes and inject black swan crashes and parabolic blow-off tops.

Tool: run_synthetic_stress_test(strategy_code, config_json='{}')

Returns JSON containing:

• metrics summary across scenarios
• replay seeds (master + per-scenario)
• artifacts: CSV scenario metrics, plus worst-case equity curve CSV + trades JSON
• recommendations: suggested parameter changes (and applies to PARAMS keys if present)

Example config_json:

{
  "master_seed": 123,
  "scenarios": 200,
  "length": 500,
  "timeframe": "1h",
  "initial_capital": 10000,
  "start_price": 100,
  "base_vol": 0.01,
  "black_swan_prob": 0.02,
  "parabolic_prob": 0.02
}

---

📌 Project docs

• README.md: Project overview and configuration
• docs/TOOLS.md: complete tool catalog (generated from app/tools)
• docs/ERRORS.md: common error codes and operator troubleshooting
• docs/EXCHANGES.md: exchange capability matrix (Supported vs Experimental)
• docs/MARKETDATA.md: market data routing, freshness scoring, plugins, and guardrails
• docs/THREAT_MODEL.md: operator-focused threat model (live trading)
• docs/CUSTODY.md: key custody + rotation guidance
• docs/POSITIONING.md: credibility-safe marketing + messaging
• RELEASE_READINESS_CHECKLIST.md: what must be green before distribution
• CHANGELOG.md: version-to-version change summary