📈 Risk-Aware Trading Agents

AI trading agents for US stocks that check the macro calendar, the fear index and verified news before they buy

Buy when others are afraid · keep 30% in cash · never panic-sell

Market regimes from FOMC · CPI · jobs reports · VIX · dip buying at EMA 50 / 100 / 200 · earnings-checked dips · Finviz + RSS + SEC news, cross-verified · daily paper-trading agents · an MCP server for Claude · 16 strategies including options · a frozen 2026 market for research · backtest your own · paper and live trading on 10 brokers · English and 中文

📊 2026 backtest with news: +15.9% vs SPY +12.1% · max drawdown -5.3% vs -8.9% · Sharpe 1.70 vs 0.77 · details

🔬 News backtesting without look-ahead bias: a point-in-time 2026 dataset (prices, VIX, 16,945 headlines and SEC filings) ships with the package, every run gets a look-ahead check, and LLM trading agents can be tested step by step over MCP · research kit

中文说明 → README_zh.md · Website · What's new · Screenshots · Quick start · Paper agents · MCP · Strategy lab · Strategy library · Brokers · Changelog

Contents

• 🆕 What's new · 📸 Screenshots · 💡 The idea · ✨ Highlights · 🚀 Quick start
• 🤖 Paper-trading agents · 🔗 MCP server · 🧪 Strategy lab · 🔬 Research kit
• 🧠 How it works: Market regimes · Risk profiles
• 📊 Backtest: News in backtests · 📚 Strategy library: Options · 🧩 Write your own strategy
• 🔌 Brokers · 🔒 Safety · 🔧 Configuration · 💻 CLI · 📁 Project layout
• ❓ FAQ · 🧭 Roadmap · 🤝 Contributing · ❗ Disclaimer · 📜 License

🆕 What's new

_{Latest release 0.7.0 (2026-11-12). The full history is in the changelog.}

	New in 0.7, 0.6 and 0.5
	🔬 A frozen 2026 market for research: everything the agents saw in 2026 ships with the package, point in time: daily prices since 2024, the VIX term structure, 16,945 headlines and SEC filings, every indicator and regime reading. Ask what was known at any close, have Claude turn a strategy you describe into code and test it, or let an LLM trade the year step by step, blind if you like. Every run gets a look-ahead check and a record with data hashes, ready for a paper. Five common swing strategies tested with and without news: trend following made +21.1% against SPY's +12.1%. How →
	⏳ Long runs keep going in the background: start a scan, a backtest, an agents run or a news fetch on the dashboard, then open another page or reload: it keeps running, a bar at the top of every page shows how far it is, and one click takes you back to the result. A long backtest can be stopped halfway.
	❓ Every number explains itself: click the ? next to any card, column or field on the dashboard and a popup says what it is, how it is calculated (straight from the code: the regime rules, the six parts of the risk score, the technical (TA) score, conviction, the news score, Sharpe and the rest) and how to use it, in English and 中文. The Signals page now also shows conviction's four parts: technical (TA), earnings, news and macro. See it →
	🔎 The news behind every backtest trade: the dashboard's Backtest page now has a News the backtest saw panel. Pick a trade and it shows the headlines the backtest had seen at that close, which of them were confirmed, the news score, and the order the strategy placed the next day. How →
	🗞️ 2026 news in the box: 16,945 news items for the 64 stocks of the built-in lists ship with the package (Benzinga headlines, titles only, and SEC 8-K filings, January to November 2026), so riskaware backtest --news, or the new Replay news switch on the dashboard's Backtest page, works with nothing to download. In 2026 so far the built-in agent with news returned +15.9% against SPY's +12.1%, with a max drawdown of -5.3% against -8.9%. Results →
	🧪 Describe a strategy, the AI writes and tests it: over MCP, Claude, Codex or Gemini read strategy_guide, write the strategy as code and run it with backtest_code. The code is checked for look-ahead and side effects and runs in a separate process; the good ones are saved for the dashboard and the paper agents. riskaware lab FILE does the same for code from anywhere. How →
	🔭 No peeking at the future: each backtest day sees only news published before its close (13:00 on early-close days), a timestamp that could be read two ways is read the later way, and a strategy can no longer reach later prices through the price data it is given. Details →
	🔑 No API key needed: an agent's review can run on your Claude, ChatGPT or Gemini plan through the tool you are already logged in to: --llm claude-cli, --llm codex-cli or --llm gemini-cli (Gemini CLI or Antigravity). How →
	🔌 MCP in one command: riskaware mcp-setup claude-desktop (or claude-code, codex, gemini, antigravity) connects the agents to that app, so you can ask it about the market and run agents in plain words. Set it up →
	🗄️ Your own news archive: for other years, riskaware news-history keeps a point-in-time archive on your own machine (SEC 8-K filings for free, your Benzinga key, or any CSV) that backtests replay the same way. How →

_{0.4.0 gave each agent its own LLM review (GPT, Claude or a free local model) with every decision on record, and made the news harder to fake; 0.3.0 added daily paper-trading agents, the MCP server and the new dashboard; 0.2.0 added options to the backtester and four stock strategies. See the changelog.}

📸 Screenshots

Every page of the dashboard (riskaware dashboard), in English and 中文. Click a picture to open it full size.

Market — the regime, fear and greed, VIX, breadth and the macro calendar	Agents — paper-trading agents ranked against SPY
How it decided — the setups, the risk check, and the LLM's bull case, bear case and verdict	Agent details — positions, orders and the reason behind every decision
Signals — what a strategy would buy or sell today: conviction and its technical (TA), earnings, news and macro parts, each with a ? that explains it	Backtest — any strategy against SPY, with drawdowns and every trade
Cross-verified news — a story counts when two outlets, the company's own release or its SEC filing carry it	News the backtest saw — pick any trade and see the headlines the backtest had at that close, their verdict and the order it placed

💡 The idea

Most trading bots either chase every signal or need a quant team to configure. This one follows a simple, explainable discipline that long-term investors already use: buy quality stocks when they pull back to their moving averages, add when fear is high and the earnings still hold up, trim when prices run too far, never panic-sell into uncertainty, and always keep a cash reserve. Four agents check the market, the calendar, the company and the news; a deterministic risk manager has the final word on every order.

Not financial advice. It starts in paper mode, and live trading needs three explicit switches.

✨ Highlights

• Macro-aware market regimes. VIX and its term structure (VIX/VIX3M), sector breadth, credit appetite (HYG vs IEF), safe-haven demand, a fear-and-greed gauge computed from free data (and CNN's Fear & Greed for reference), and the FOMC, CPI, jobs report, PPI, GDP and PCE calendar put the market in one of four regimes: risk-on, neutral, uncertain, risk-off.
• Buy low, sell high. Pullbacks to EMA 50 / 100 / 200, RSI(2) and z-score mean reversion, quality dips that must pass an earnings check (revenue growth, margins, free cash flow, leverage, EPS beats), breakouts and trend continuation in strong markets. Take-profit trims when a stock runs far above EMA50; trend exits after a break of a falling EMA50.
• No panic selling. When the regime is uncertain or risk-off the agent holds, does not sell, and only buys at strong support. Only a disaster the company itself confirms (bankruptcy, delisting, restatement in its own 8-K or press release) or an optional hard stop can force an exit.
• Risk first. A 30% cash + T-bill floor, position, sector and speculative ("lottery ticket") caps, volatility-scaled sizes, buying in tranches, a Treasury sleeve for conservative profiles, idle cash parked in a T-bill ETF, a drawdown pause, a kill switch.
• Cross-verified news. Finviz (free), Google News, Nasdaq, Seeking Alpha and Yahoo RSS plus the company's own SEC 8-K filings. A story only counts toward the company it names, and it is confirmed when two independent outlets, the company's own press release or its SEC filing carry it; a red flag on a confirmed story blocks new buys. Only the company's 8-K, or its own release confirming what independent outlets reported first, can force a sale, so a fake headline, a fake press release and the outlets that repeat it, or another company's bad news cannot. A denial clears the story it refutes instead of confirming it.
• 10 brokers, one interface. Built-in paper account, Alpaca, Interactive Brokers, Public.com, Charles Schwab, tastytrade, Tradier, Futu/moomoo, Tiger Brokers, Longbridge.
• Options strategies (backtest). An aggressive call-buying strategy and the wheel (cash-secured puts and covered calls), with premium caps, put collateral outside the cash floor, assignment and expiry.
• Backtest anything, including your own strategy. Write one Python method; the same strategy object runs in backtests, paper and live trading with the same risk engine. Compare strategies side by side with an HTML report, and replay point-in-time news: 2026 headlines and SEC filings ship with the package, and other years come from a local archive (SEC 8-K filings, your own Benzinga key or a CSV).
• Daily paper-trading agents. Run several strategies side by side, each on its own paper account with free prices. A background job trades them every trading day, and a leaderboard compares them with SPY.
• Works with Claude (MCP). riskaware mcp gives Claude, Cursor or any MCP client the regime, signals, news, backtests and the paper agents. Describe a strategy in words and the AI writes it as code and backtests it, checked for look-ahead.
• A frozen 2026 market for research. Point-in-time prices, VIX, news and indicators ship with the package. Every experiment is checked for look-ahead and saved with its data hashes, and LLMs can run experiments or trade the year over MCP.
• Optional LLM review, per agent. A bull analyst, a bear analyst and a risk judge (GPT, Claude, any OpenAI-compatible model such as DeepSeek or Qwen, or a free local model through Ollama) can nudge conviction by at most ±0.15 or veto a buy. They can never create a trade or change a limit. News reaches them only as quoted, untrusted text, and every prompt and reply is kept in the local journal so you can see how each decision was made.
• Bilingual. CLI, dashboard, reports and docs in English and 中文.

🚀 Quick start

git clone https://github.com/jackson-cmd/risk-aware-trading-agents
cd risk-aware-trading-agents
pip install -e ".[dashboard,mcp]"    # Python 3.10+

riskaware init                        # 2-minute wizard: language, risk profile, broker, watchlist
riskaware regime                      # market regime, VIX, fear & greed, next FOMC / CPI / jobs report
riskaware scan                        # today's signals, each with its reasons
riskaware analyze NVDA                # what every agent thinks about one stock
riskaware news AAPL                   # cross-verified headlines
riskaware backtest --compare buy_and_hold,ema_bounce
riskaware run                         # one paper-trading cycle (built-in paper account)
riskaware agents init                 # four starter paper-trading agents
riskaware agents run                  # let them trade once now
riskaware agents schedule --install   # ...and every trading day from now on
riskaware dashboard                   # web UI (English / 中文)

No account or API key is needed for any of the commands above. Add --lang zh to any command for Chinese output.

🤖 Paper-trading agents

An agent is a strategy with its own paper account. Pick a strategy (built-in or your own file), a risk profile, a stock list and the starting cash, and the agent trades that account once every trading day on free Yahoo Finance prices. Run several side by side and see which one beats SPY. Agents only ever use the built-in paper account, never a broker.

riskaware agents init                                    # steady, momentum, breakout, fear-buyer
riskaware agents add dips --strategy rsi2 --universe tech --cash 25000
riskaware agents add mine --strategy my_dip.py:MyDip --profile aggressive
riskaware agents add luna --strategy risk_aware --llm openai:gpt-5.6-luna   # with an LLM review board
riskaware agents add local --strategy risk_aware --llm ollama:qwen2.5:3b    # a free local model
riskaware agents run                                     # trade every active agent now
riskaware agents why luna                                # how it decided: setups, risk check, bull / bear / judge
riskaware agents                                         # the leaderboard
riskaware agents schedule --install                      # every trading day, by itself

The daily job (a LaunchAgent on macOS, a crontab line on Linux, a scheduled task on Windows) wakes every 15 minutes on weekdays and trades each agent once per trading day after 15:40 New York time, before the close. It skips holidays, catches up after the laptop sleeps, and keeps going when one agent fails. Each agent keeps its account, journal and daily equity in ~/.riskaware/arena/NAME/. The Agents page of the dashboard shows the leaderboard and lets you create, run, pause, reset and delete agents; its Decisions tab shows how each decision was made, including the LLM's bull case, bear case and verdict and the exact prompt it was sent. GPT needs OPENAI_API_KEY in your .env; a local model needs Ollama (ollama pull qwen2.5:3b); and --llm claude-cli, codex-cli or gemini-cli uses your Claude, ChatGPT or Gemini plan through its command-line tool, with no API key. More in docs/agents.md.

🔗 MCP server

riskaware mcp serves the agents over the Model Context Protocol, so Claude, Codex, Gemini, Cursor or any MCP client can use them, on your plan and without an API key. riskaware mcp-setup prints (or, with --apply, runs) the one step that connects it:

pip install -e ".[mcp]"
riskaware mcp-setup claude-desktop --apply   # or: claude-code, codex (your ChatGPT login), gemini, antigravity

Twenty-one tools: market_regime, scan, analyze_stock, stock_news, list_strategies, backtest, strategy_guide, backtest_code, agents_leaderboard, agent_detail, agent_decisions, agents_create and agents_run, and for research research_guide, market_day, run_experiment, list_experiments, experiment_report, trading_session_start, trading_session_step and trading_session_status. They are read-only or act on local paper accounts; no tool can send an order to a broker. Then just ask, for example "What regime is the market in, and what is coming up this week?" or "Backtest the wheel on megacap with $1M since 2018." ChatGPT itself only connects to remote servers, so on the OpenAI side use Codex, which runs on your ChatGPT login. More in docs/agents.md.

🧪 Strategy lab

Describe a strategy in plain words and let the AI build it. Over MCP, Claude, Codex or Gemini read strategy_guide, write the strategy as a Python class and run it with backtest_code. Before the code runs, the lab refuses dates and stock tickers written into it (both let a backtest know the future), files, network and private attributes. Then it backtests the code in a separate process with no API keys and a time limit, and returns the metrics next to SPY and buy-and-hold, or the lines to fix.

Write a strategy that buys two-day pullbacks in uptrends when the recent news is positive, and sells after 10 days or at +8%. Backtest it on the tech list for 2026 with news.

save_as keeps a strategy that works: it then shows up on the dashboard and can run as a paper agent. For code from anywhere else, riskaware lab my_strategy.py --preset tech does the same checks and backtest. More in docs/strategy-lab.md.

🔬 Research kit

The whole of 2026 ships with the package, frozen, for experiments that anyone can repeat: daily prices since 2024 for the 64 stocks and 25 ETFs, the VIX term structure, 16,945 headlines and SEC filings, and every indicator and regime reading the agents use, each as it was known at that day's close.

riskaware research day 2026-04-08 --symbols NVDA,TSLA           # everything known at that close
riskaware research run --strategy swing_trend --split 2026-07-01
riskaware research trade --llm ollama:qwen2.5:3b --universe core --blind

• Point in time. Signals at the close, orders at the next open: swing trading on daily bars. A headline counts only after it was published, and indicators only look back.
• A look-ahead check on every run. The run is repeated with every price and headline after three cut days replaced by random ones, and the decisions before each cut must not change.
• A record for papers. Each run saves its data hashes, code, settings, metrics, bootstrap intervals, trades and every decision.
• Made for LLMs. Over MCP, describe a strategy and Claude writes and tests it (run_experiment), looks at any day (market_day), or trades the year step by step (trading_session_start), blind if you like: no tickers, company names or dates.

Five common swing strategies, 2026-01-02 to 2026-11-11 on the 56 megacaps, at most 10 equal positions:

Sharpe and drawdown are without news. Trend following beat SPY with half its drawdown. The news filter made every strategy slightly worse, and buying on positive headlines did worse than buying the same price move without them. Every interval overlaps, and every run passed the look-ahead check. Definitions, the full table with 95% intervals, and advice for papers in docs/research.md.

🧠 How it works

flowchart TB
  D["Prices · VIX · sectors · FOMC / CPI / NFP calendar · earnings · Finviz + RSS + SEC"]
  M["Macro agent<br/>regime + fear/greed"]
  E["Event agent<br/>FOMC, CPI, jobs"]
  T["Technical agent<br/>EMA 50/100/200,<br/>mean reversion, trend"]
  F["Fundamental agent<br/>earnings quality"]
  N["News agent<br/>cross-verified"]
  S["Strategy: built-in or yours"]
  L["Optional LLM<br/>bull / bear / judge"]
  R["Risk manager: cash floor · caps · tranches · regime rules"]
  D --> M & E & T & F & N
  M & E & T & F & N --> S
  L -.->|"±0.15 at most"| S
  S --> R
  R --> G["Safety guards"] --> B["Paper or live broker"]
  R --> X["Backtester"]

What the agent does in each regime

Emergency exits (a severe red flag the company itself confirms in its 8-K or its own press release, or the profile's hard stop) work in every regime.

Risk profiles

Every limit can be overridden in riskaware.yaml. Positions are built in tranches (50% / 25% / 25% of the target); a later tranche needs a deeper support touch or a winning position, and trimmed positions can be rebuilt on the next pullback.

📊 Backtest

Built-in strategy, balanced profile, the 55-stock megacap list, $100k, signals at the close and fills the next day, 5 bps slippage, January 2018 to November 2026:

Read it honestly: in a long bull market the agent earns less than the index because it keeps at least 30% in cash, and it loses roughly half as much when markets fall. The list is today's large caps, so it carries survivorship bias; these numbers use neither news nor fundamentals (2026 with news is below), and past results do not predict future ones. Reproduce it with riskaware backtest --compare buy_and_hold.

riskaware backtest --strategy risk_aware --compare buy_and_hold,ema_bounce,rsi2 --start 2018-01-01 --open
riskaware backtest --preset etf --profile conservative
riskaware backtest --symbols AAPL,MSFT,NVDA,COST --cash 25000
riskaware backtest --synthetic                     # offline demo, no download

Every run writes a self-contained HTML report (metrics, equity and drawdown charts with regime shading, monthly returns, every trade with its reason) plus CSV files.

2026 so far, with news

The same agent and settings on 2026, from January 2 to November 11, now reading the news that ships with the package: 15,542 Benzinga headlines and 605 SEC filings for these 56 stocks, each day only what was out before its close.

The agent beat SPY by 3.8 points while holding stocks with 60% of its money on average, and its worst drop was 60% of SPY's: in the March sell-off it fell 5.3% while SPY fell 8.9%. News added half a point of return this year. Ten months is a short test, so the 2018–2026 table above is still the better guide. Reproduce it with riskaware backtest --preset megacap --start 2026-01-02 --end 2026-11-11 --news.

News in backtests

A backtest may only use news it would have seen on that day, so it needs each item's publication time. News for 2026 ships with the package: 16,945 items for the 64 stocks of the built-in lists (Benzinga headlines, titles only, and SEC 8-K filings, January 1 to November 11, 2026). For other years, riskaware news-history keeps an archive on your own machine (~/.riskaware/news, never in the repository). --news replays both through the same clustering and two-source check used in live trading. Each day sees only items published before its close (16:00 New York, 13:00 on early-close days), and orders fill the next day.

riskaware backtest --strategy examples/strategies/news_earnings_drift.py --preset megacap --start 2026-01-02 --news   # 2026: nothing to download
riskaware news-history build --preset core --contact-email [email protected]   # SEC 8-K filings since 2018
riskaware news-history build --symbols AAPL,NVDA --source benzinga             # with your own BENZINGA_API_KEY
riskaware news-history import my_news.csv --tz America/New_York               # timestamp, symbol, headline[, source, url, sentiment]
riskaware news-history status
riskaware news-history show NVDA --date 2024-05-22                             # what the backtest saw at that close
riskaware backtest --strategy examples/strategies/news_earnings_drift.py --preset core --news --compare buy_and_hold

The core preset is SPY, QQQ, AAPL, MSFT, NVDA, AMZN, GOOGL, META and TSLA. SPY and QQQ are funds, not companies, so the SEC archive has little or nothing for them; the FOMC, CPI and jobs calendar already drives the regime in every backtest. Benzinga counts as one publisher, so a Benzinga-only story stays single-source until an SEC filing or a second publisher backs it. What you download or import stays on your machine. Details: docs/news-history.md.

More history. We keep a much larger archive, about 3.2 million Benzinga headlines from 2011 to 2026. It is far too big to ship in the package, so the package carries 2026 for the built-in lists. If you need more years or more stocks, open an issue and we will look at how to provide them, for example as a separate download.

📚 Strategy library

Every built-in strategy runs through the same risk manager, so all of them keep the cash floor. Backtest any of them with riskaware backtest --strategy NAME; compare several with --compare a,b,c.

Backtests from January 2018 to November 2026 on the megacap list:

Options (backtest only)

Option strategies open long calls or puts, cash-secured puts and covered calls. The risk manager caps the premium in long options (options_sleeve: 0% conservative, 3% balanced, 12% aggressive; options_per_trade: 0 / 1% / 3%), keeps put collateral out of the 30% cash floor and inside the single-stock cap, and never lets shares that back a written call be sold. Expiring options settle at intrinsic value; written puts are assigned into shares, covered calls are called away.

There is no free archive of historical option quotes, so the backtester prices options with Black-Scholes on a modelled implied volatility (VIX for index ETFs; realized volatility, a 10% volatility premium and a VIX scaling for stocks) and pays half of a 4% bid-ask spread plus $0.65 per contract. The results move with these assumptions: without the 10% volatility premium the wheel drops to a 0.81 Sharpe and aggressive_calls ranges from 3% to 15% a year depending on spread and volatility, always with a drawdown near -40%. Treat option backtests as the shape of a strategy, not a forecast. riskaware run skips option orders in this version.

Written puts need cash for 100 shares per contract inside the single-stock cap, so the wheel only trades names whose strike × 100 fits (about $10k per name on a $100k aggressive account); test it with --cash 1000000 or a list of lower-priced names.

🧩 Write your own strategy

riskaware new-strategy my_dip          # creates my_dip.py from a template
riskaware backtest --strategy my_dip.py --compare risk_aware,buy_and_hold
riskaware run --strategy my_dip.py     # paper trade it

from riskaware.strategy import Action, Signal, Strategy

class MyDip(Strategy):
    name = "my_dip"
    default_params = {"rsi_entry": 30, "take_profit": 0.20}

    def on_bar(self, ctx):
        signals = []
        for sym in ctx.universe:
            row = ctx.row(sym)                 # indicators at today's close
            if row is None:
                continue
            pos = ctx.position(sym)
            if pos is None and row["close"] > row["ema200"] and row["rsi14"] < self.params["rsi_entry"]:
                signals.append(Signal(sym, Action.BUY, strength=0.7, reason="oversold in an uptrend"))
            elif pos and pos.gain >= self.params["take_profit"]:
                signals.append(Signal(sym, Action.SELL, strength=0.8, fraction=0.5, reason="take profit"))
        return signals

A strategy only says what it wants and how sure it is; the risk manager decides the size and enforces the cash floor, caps and regime rules, so your strategy inherits the same protection. ctx.market has the regime, VIX and upcoming events; ctx.quality(sym) and ctx.news(sym) give the earnings verdict and the verified news in live runs; ctx.news also works in backtests run with --news. See docs/custom-strategies.md. Or describe the strategy and let an AI write it in the strategy lab.

🔌 Brokers

Setup for each broker (keys, gateways, paper accounts) is in docs/brokers.md. Reports from live use of the SDK-based adapters are very welcome.

🔒 Safety

• riskaware run uses the paper account unless you change the broker; --dry-run previews without sending anything.
• A live order needs execution.mode: live in the config and --live on the command line and a typed confirmation (or --yes).
• Guards: limit price within a band of the quote, a per-order value cap, a maximum number of orders per run, no trading on market holidays, and deterministic client order ids so a rerun on the same day cannot duplicate an order.
• riskaware halt blocks all order submission until riskaware resume.
• Every run, decision and order is written to a local SQLite journal (~/.riskaware/journal.db), visible in the dashboard.
• API keys stay in .env (see .env.example); they are never written to the config or the journal.

🔧 Configuration

riskaware init writes a commented riskaware.yaml; every key is optional.

language: en                 # en | zh
profile: balanced            # conservative | balanced | aggressive
profile_overrides:
  cash_floor: 0.30           # cash + T-bill ETF never below 30%
  hard_stop: 0.30            # emergency exit after a 30% loss (null = never)
broker:
  name: alpaca
  options: {paper: true}
universe:
  preset: megacap            # megacap | tech | defensive | etf | sectors (combine with +)
  symbols: [PLTR, SHOP]
  cash_vehicle: SGOV         # idle cash goes into T-bills
news:
  min_independent_sources: 2
llm:
  enabled: false
  provider: anthropic        # or openai (any OpenAI-compatible endpoint)

riskaware config prints the resolved configuration; riskaware doctor checks data sources and the broker connection.

💻 CLI

📁 Project layout

src/riskaware/
  agents/      macro regime, technical setups, earnings quality, news
  data/        prices (Yahoo, CSV, synthetic), FOMC/BLS/BEA calendar, fundamentals, CNN Fear & Greed
  news/        Finviz + RSS + SEC sources, clustering and cross-source verification
  strategy/    Strategy interface, the risk-aware strategy, examples, swing baselines, loader
  risk.py      the risk manager (cash floor, caps, tranches, regime rules)
  brokers/     paper + 9 broker adapters
  engine.py    paper / live cycle, guards, journal, state
  backtest/    backtester, metrics, HTML report
  research/    the frozen 2026 market, point-in-time days, experiments, look-ahead check, LLM trading sessions
  llm/         optional bull / bear / judge review
  dashboard/   Streamlit app (pages, theme, charts)
  arena.py     paper-trading agents: accounts, daily runs, leaderboard
  scheduler.py the daily background job (launchd, cron, Task Scheduler)
  mcp_server.py  tools for Claude and other MCP clients
site/          bilingual project website (GitHub Pages)
docs/          design notes and guides (English and Chinese)

❓ FAQ

Longer answers on the website: backtesting with news without look-ahead bias · point-in-time market data for 2026 · testing LLM trading agents.

How do I backtest a trading strategy with news, without look-ahead bias?

Run riskaware backtest --news, or riskaware research run for a record you can cite. News is replayed point in time: each day the strategy sees only the headlines and SEC filings published before that day's 16:00 New York close, and its orders fill at the next open. Every research experiment is also run again with a random future after three cut days, and the decisions before each cut must not change. See news in backtests and the research kit.

Where can I get historical news data for backtesting?

2026 ships with the package: 16,945 news items for 64 large-cap US stocks, Benzinga headlines (titles only) and SEC 8-K filings, each with its publication time. For other years, riskaware news-history build downloads SEC 8-K filings for free, and Benzinga headlines with your own API key; a CSV with a time, a ticker and a headline works too. See docs/news-history.md.

Is there a free point-in-time dataset of US stock prices, VIX and news?

Yes. The research kit's frozen market holds daily bars from January 2024 to November 2026 for 64 stocks and 25 ETFs, the VIX term structure (VIX9D, VIX, VIX3M, VVIX) and the 2026 news, with SHA-256 hashes so that a paper can cite the exact data. riskaware research day 2026-04-08 shows everything that was known at that close. See what ships.

How do I evaluate an LLM trading agent fairly?

Let it trade the frozen 2026 market one decision at a time with riskaware research trade --llm ..., or with trading_session_start over MCP. Each observation holds only what was known at that close, orders fill at the next open, and the run is saved with every order and its metrics against SPY. Blind mode replaces tickers, company names and dates, so the model cannot recall how a stock did. See LLM agents.

Can Claude, ChatGPT (Codex) or Gemini backtest my strategy?

Yes, over MCP. Run riskaware mcp-setup claude-desktop --apply (or claude-code, codex, gemini), then describe the strategy in words. The assistant writes it as code; the code is checked for dates, tickers and side effects, runs in a separate process, and comes back with metrics, confidence intervals and a look-ahead verdict. See the MCP server and the strategy lab.

Does news sentiment improve swing trading strategies?

Not in our 2026 test with headline sentiment from one feed. A news filter made each of five common swing strategies (trend following, RSI(2) mean reversion, breakouts, pullbacks, post-news drift) slightly worse, and buying on positive headlines did worse than buying the same price move without them. Trend following made +21.1% against SPY's +12.1%. See the results.

How do I paper trade before risking real money?

Paper trading is the default. riskaware run trades the built-in paper account, riskaware agents runs several strategies on simulated money every trading day, and broker paper accounts such as Alpaca's work too. Live trading needs three explicit switches. See safety.

Which brokers are supported?

A built-in paper account, Alpaca, Interactive Brokers, Public.com, Charles Schwab, tastytrade, Tradier, Futu/moomoo, Tiger Brokers and Longbridge. See brokers.

🧭 Roadmap

• Point-in-time fundamentals from SEC XBRL for backtests
• Live option orders (option chains from each broker), protective puts and collars
• More brokers (Webull, E*TRADE) and crypto / HK / A-share markets
• Walk-forward parameter studies

🤝 Contributing

Issues and pull requests are welcome: new brokers, data sources, strategies, translations. Run pip install -e ".[dev]" && pytest before you open a PR. See CONTRIBUTING.md.

❗ Disclaimer

This software is for research and education. It is not investment advice, and nothing in it is a recommendation to buy or sell any security. Trading involves risk of loss. You are responsible for every order your account sends; test with paper trading first.

📜 License

MIT