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.

🌎 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

Research: You ask your agent, "Find a good entry for AAPL." The agent calls fetch_ohlcv and get_sentiment.
Proposal: The agent concludes, "AAPL is oversold; I want to buy $1000 worth of shares." It calls place_market_order.
Governance: The MCP server checks its rules. Is $1000 within your MAX_TRADE_AMOUNT? If yes, it creates a Pending Execution.
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:

Navigate to the directory: cd frontend
Install dependencies: npm install
Run the development server: npm run dev
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.

ReadyTrader-Stocks demo flow

🛠️ 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).

🛡️ Live Trading Safety & Approval

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.

🔑 Exchange & Signing Credentials

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.

📈 Market Data & CCXT Tuning

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.

🛠️ Ops, Observability & Limits

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.

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:

Go to Settings -> MCP Servers.
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:

Agent calls fetch_ohlcv("AAPL") to see data structure.
Agent writes code for on_candle(close, rsi, state).
Agent calls run_backtest_simulation(code, "AAPL").
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

ReadyTrader-Stocks

Important Disclaimer (Read Before Use)

🌎 The Big Picture

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

🛡️ 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

Research: You ask your agent, "Find a good entry for AAPL." The agent calls fetch_ohlcv and get_sentiment.
Proposal: The agent concludes, "AAPL is oversold; I want to buy $1000 worth of shares." It calls place_market_order.
Governance: The MCP server checks its rules. Is $1000 within your MAX_TRADE_AMOUNT? If yes, it creates a Pending Execution.
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:

Navigate to the directory: cd frontend
Install dependencies: npm install
Run the development server: npm run dev
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.

ReadyTrader-Stocks demo flow

🛠️ 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).

🛡️ Live Trading Safety & Approval

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.

🔑 Exchange & Signing Credentials

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.

📈 Market Data & CCXT Tuning

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.

🛠️ Ops, Observability & Limits

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.

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:

Go to Settings -> MCP Servers.
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:

Agent calls fetch_ohlcv("AAPL") to see data structure.
Agent writes code for on_candle(close, rsi, state).
Agent calls run_backtest_simulation(code, "AAPL").
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

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

ReadyTrader-Stocks

ReadyTrader-Stocks

Important Disclaimer (Read Before Use)

🌎 The Big Picture

🛡️ The Trust Model: Intelligence vs. Execution

💰 Funding Model (Non-Custodial)

🔄 A Day in the Life of a Trade

🖥️ Premium Next.js Dashboard

🚀 Key Features

⚡ 10-minute evaluation

🛠️ Installation & Setup

Prerequisites

1. Build & Run (Standalone)

Local development (no Docker)

2. Configuration (.env)

Brokerage credentials

🔌 Integration Guide

Option A: Agent Zero (Recommended)

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

📚 Feature Guide

2. Paper Trading Laboratory (Zero-Key Flow)

3. Market Regime & Risk

🧰 Tool Reference

🧪 Synthetic Stress Testing

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

📌 Project docs

ReadyTrader-Stocks

Important Disclaimer (Read Before Use)

🌎 The Big Picture

🛡️ The Trust Model: Intelligence vs. Execution

💰 Funding Model (Non-Custodial)

🔄 A Day in the Life of a Trade

🖥️ Premium Next.js Dashboard

🚀 Key Features

⚡ 10-minute evaluation

🛠️ Installation & Setup

Prerequisites

1. Build & Run (Standalone)

Local development (no Docker)

2. Configuration (.env)

Brokerage credentials

🔌 Integration Guide

Option A: Agent Zero (Recommended)

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

📚 Feature Guide

2. Paper Trading Laboratory (Zero-Key Flow)

3. Market Regime & Risk

🧰 Tool Reference

🧪 Synthetic Stress Testing

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

📌 Project docs

2. Configuration (`.env`)

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

2. Configuration (`.env`)

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