Skip to main content
Glama

openInvest

A self-hosted investment decision engine built for modern AI agents. Multi-agent information isolation and cross-challenge protocol, providing an auditable decision trail (Audit Trail).

Python Agents License Stars Glama MCP server

๐Ÿ“š Full Architecture Wiki ยท ๐Ÿ‡จ๐Ÿ‡ณ ไธญๆ–‡็‰ˆ


What is OpenInvest?

OpenInvest is a self-hosted investment decision engine built for modern AI agents.

It provides a verifiable investment committee, evidence-based reasoning, long-horizon backtesting, and auditable decision records. Instead of replacing Claude Code, Codex, Hermes, or OpenClaw, OpenInvest is designed to power them.


Related MCP server: Decker

Account Performance & PnL

  • Benchmark Portfolio: The system introduces 8 standard control benchmarks across 4 quadrants (AI advisors / Mutual funds / Wealth management / Broad market index). For details on the comparison methodology and data cleaning logic, see docs/wiki/README.md.


Research & Falsification

System Self-Disclosure: This system is an auditing tool to eliminate human investment cognitive biases and enforce reasoning transparency, not a return-amplifying black box. Latest automated audit (docs/verdict_accuracy.md): Directional verdicts (excluding HOLD) have a true hit rate of 42.2% (n=56, below random); HOLD accounts for 56% of all decisions. The system's value lies in transparency and discipline (mostly staying inactive, low turnover), not directional prediction. Detailed log stream can be found in docs/verdict_accuracy.md.

This project systematically attempts to falsify its own edge and publishes negative results as-is. The deterministic features the committee reads, and the timing signals around them, were tested against pre-registered statistical gates โ€” none survived as tradable alpha.

Test

Result

Verdict

Q1 cross-sectional stock picking

6 features, mean-IC 0.025โ€“0.067, Holm-corrected p=0.397

No significant stock-picking signal

M1 multivariate GBM (out-of-sample)

mean OOS IC +0.003, p=0.925

Feature combination doesn't help either โ€” no signal

Q2 gold MA200 trend

p_holm=0.016, significant โ€” but trend_dca shows it is beta, not tradable alpha: timing terminal value 3.07 vs 15.10 buy-and-hold, Sharpe +0.36 vs +0.68, max drawdown deeper (โˆ’57% vs โˆ’44%)

Statistically significant, economically untradable

Per-asset multi-signal families

3 assets ร— 4 signal families ร— parameter grid = 24 variants per asset; after costs + DSR deflation, none passes DSR > 0.95

No tradable signal in any family

Positive control

A cheating perfect-foresight timing signal scores DSR = 1.00

The harness can detect a real signal

Methodology: Newey-West HAC t-statistics, Deflated Sharpe Ratio (Bailey & Lรณpez de Prado 2014, re-derived equation by equation), Holm correction, zero lookahead, and LLM training-cutoff probes.

Details: experiments/signal-eval/README.md ยท docs/verdict_accuracy.md ยท ADR-022 ยท ADR-023


Product Philosophy

Most AI investment assistants try to become better chatbots. OpenInvest instead builds a transparent, verifiable, and auditable decision engine that plugs into personal agents such as Claude Code, Codex, Hermes, and OpenClaw โ€” every improvement in those agents automatically makes OpenInvest more capable.

The division of labor is deliberate: your agent handles long-term memory, natural conversation, and user understanding; OpenInvest handles the verifiable investment committee, evidence-based reasoning, long-horizon backtesting, and auditable decision records.

                   User
                     โ”‚
         โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
         โ–ผ                       โ–ผ
    Your Agent             OpenInvest
(User Understanding)   (Market Understanding)
         โ”‚                       โ”‚
         โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                     โ–ผ
            Better Investment Decisions

Your agent knows you. OpenInvest knows investing.

Avoiding User Ownership

OpenInvest intentionally avoids "owning" the user. Most AI products try to own everythingโ€”memory, persona, chat history, and workspaces. OpenInvest takes a back seat. It exposes clean APIs, CLI commands, and agent skills (Claude Code / Codex / Hermes / OpenClaw), letting your primary agent manage the conversation and context while OpenInvest powers the underlying investment intelligence.


Features

  • Multi-Agent Investment Committee: Isolated analysis and round-rebuttal debate.

  • Coordinator-Worker Architecture: Prevents context contamination and role hallucination.

  • Information Isolation: Rigidly blocks quant and risk analysts from out-of-boundary contexts.

  • Auditable Decision Trail: Clean logs showing exactly "why" each decision was made.

  • Markdown-as-a-Database: Frontmatter (YAML) + Markdown (Body) as the single source of truth.

  • Long-Horizon Backtesting: Built-in test harness with lookahead bias protections.

  • Dreaming-Based Memory Consolidation: Nightly memory distillation to prevent context drift.

  • Self-Hosted / Zero-Cost: Powered directly by your local agent's reasoning resources.

  • Agent Skill: Lightweight plugin for Claude Code / Codex / Hermes / OpenClaw, with interactive bootstrap wizard.

  • Automated Deployment: GitHub Actions workflow to run the committee and email reports daily.


Quick Start

Add the lightweight skill from your agent's plugin registry. The host agent will automatically pull the core code and align dependencies on first run:

# Claude Code
/plugin marketplace add longsizhuo/openInvest
/plugin install invest@openinvest

# Codex
codex plugin marketplace add longsizhuo/openInvest
codex plugin add invest@openinvest

# Hermes Agent (official plugin catalog)
hermes plugins install openinvest --enable
# older Hermes without the catalog: hermes plugins install longsizhuo/openInvest/plugin --enable

# OpenClaw
openclaw plugins install clawhub:openinvest

Any other MCP client: register the MCP server from step 2 below (full walkthrough in the agent tutorial).

2. Standalone โ€” MCP server or CLI (no clone needed)

The backend ships on PyPI; ~/openInvest holds only your data:

# MCP (any MCP client; add --http for a remote streamable-HTTP server โ€” BETA)
claude mcp add openinvest -e INVEST_HOME=~/openInvest -- uvx openinvest-mcp

# or plain CLI
INVEST_HOME=~/openInvest uvx openinvest status

Send set up invest (or ๅธฎๆˆ‘ๅˆๅง‹ๅŒ– invest) to any skill-enabled AI terminal. The system will trigger an interactive bootstrap wizard to guide you through:

  1. Detecting the memory/ state storage path and .env configuration.

  2. 5-dimensional profiling (Legal name, Risk capacity, Debt structure, Initial holdings, and optional keys).

  3. Running static data migration to immediately generate your first asset exposure memo.

๐Ÿ’ก Zero-Cost Execution: In skill interactive mode, the committee's underlying reasoning relies entirely on the host agent's (e.g. Claude Code) reasoning pipeline. No third-party API Key is consumed. You only need to configure an API key when setting up automated crons or calling independent Web APIs.

For self-hosting details, see docs/QUICK_START.md. (The bundled Web GUI was retired on 2026-07-05 โ€” all capabilities are exposed via CLI/MCP; a standalone frontend may return later.)

3. Serverless Self-Hosting (GitHub Actions)

Run the committee automatically via GitHub Actions and receive daily digest emails.

โš ๏ธ Fork must be set to Private: State files (holdings, verdicts) will be committed back to your fork. Public forks will leak your private financial information.

  1. Fork this repository and change its visibility to Private (Settings -> Visibility).

  2. Run set up invest locally to generate the initial memory/ folder, then commit and push it to your private fork:

    git add -f memory/ && git commit -m "chore: init memory state" && git push
  3. In your fork's Settings -> Secrets and variables -> Actions, add the following Secrets:

    • LLM_API_KEY (or DEEPSEEK_API_KEY): API key to run the committee.

    • EMAIL_SENDER / EMAIL_PASSWORD: Gmail address + App Password.

    • DIGEST_EMAIL_TO: Recipient email address.

  4. Enable Workflows under the Actions tab. The workflow runs automatically at 10:00 AM (Beijing time) daily; you can also manually trigger daily-report via Run workflow.


Architecture & Multi-Agent Orchestration

openInvest does not run a mock debate in a single LLM session. The system enforces an Information Isolation Contract at the core/committee/ layer, orchestrating 4 independent LLM processes in a directed acyclic graph (DAG):

                [ Macro Data Injection ]
                           โ”‚
                 โ–ผ 1. Macro Alignment Context
             โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
             โ”‚    Macro Strategist      โ”‚ (VIX / Interest rate spread / Currency momentum)
             โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                           โ”‚
                 โ–ผ 2. Async Multi-Dimensional Scrutiny (Async DAG)
             โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
             โ–ผ                          โ–ผ
   โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”        โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
   โ”‚  Quant Analyst   โ”‚        โ”‚   Risk Officer   โ”‚
   โ”‚ (RSI / Momentum) โ”‚        โ”‚ (Concentration)  โ”‚
   โ”‚                  โ”‚        โ”‚                  โ”‚
   โ”‚ ๐Ÿ›‘ No Holdings   โ”‚        โ”‚ ๐Ÿ›‘ No Indicators โ”‚
   โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜        โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
             โ”‚                           โ”‚
             โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                           โ”‚
             โ–ผ 3. Round 2 Rebuttal & Cross-Challenge
             โ”‚ Mutual feedback loop for signal correction
             โ–ผ
   โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
   โ”‚         Chief Investment Officer (CIO)       โ”‚
   โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                           โ”‚
             โ–ผ 4. Deterministic State Persistence
          [ BUY / ACCUMULATE / HOLD / TRIM / SELL ]
  1. Macro Strategist: Assesses the global macro landscape (VIX, yield curve spread, core currency matrix) to establish the portfolio's risk threshold.

  2. Quant Analyst: A pure mathematical momentum and technical indicator filter. Strictly blocked from knowing portfolio holdings to eliminate human attachment and loss-aversion biases.

  3. Risk Officer: Focuses entirely on tail risks (drawdown buffers, concentration limits, solvency multipliers). Strictly blocked from technical indicators to make objective asset exposure rulings.

  4. Round 2 Rebuttal: Quant and Risk analysts are fed each other's Round 1 reports in Round 2, challenging boundaries until signals converge or safety valves trigger.

  5. CIO (Chief Investment Officer): Synthesizes the audited reports and outputs a structured Verdict (BUY / ACCUMULATE / HOLD / TRIM / SELL) with a confidence level. No auto-order execution occurs; final action remains strictly up to the human auditor.

Key trade-offs behind this design are recorded as ADRs in docs/wiki/adr/ (24 to date), including rulings that overturned our own earlier designs โ€” ADR-007 retired the few-shot CIO route, and ADR-009 rejected TA-style analyst agents after a pre-registered experiment.


Core Design

  • Coordinator-Worker Pattern: Workers operate in isolated namespaces. Boundary constraints are hardcoded at the framework layer in Python to prevent attention contamination in large multi-role prompts.

  • Markdown-as-a-Database: The system uses Frontmatter (YAML) + Markdown (Body) as the single source of truth. Leveraging fcntl.flock process file locks and temporary atomic file replacement, it provides a tamper-proof investment audit trail natively tracked by Git.

  • Three-Phase Dreaming Consolidation: Distills daily decisions against actual market outcomes nightly (Light Sleep $\rightarrow$ REM $\rightarrow$ Deep Sleep) to consolidate long-term insights, preventing Large Language Model (LLM) context drift over long execution spans.


Configuration

The system defaults to DeepSeek endpoints and supports any standard OpenAI-compatible API. LLM provider setup and all tunable runtime overrides (ADR-017) are documented in docs/wiki/22-configuration.md.


Disclaimers & Backtest Limitations

  1. No Financial Advice: This system is a decision-support tool powered by LLMs. Output memos represent simulated reasoning based on deterministic data and do not constitute asset allocation advice.

  2. Backtest Time-Lock & Lookahead Guard: The backtest engine (scripts/backtest_runner.py) has a hardcoded safety valve: it rejects backtests for decision_date > 2024-06-30 by default (override with --allow-lookahead). Since mainstream foundation models have training cutoff dates around mid-2024, backtesting on later intervals introduces severe Lookahead Bias (model pre-training leakage). Parameter tuning, Optuna sweeps, and prompt optimization must run strictly on historical windows prior to June 30, 2024.


Acknowledgments

  • Jawz: Thank you for supporting openInvest's continued development.

  • Tencent Cloud: Thank you for supporting openInvest's continued development.

  • Equibles โ€” Optional data provider for A-share and Hong Kong financial statements, and a daily-price fallback when Yahoo Finance is unreachable. Yahoo Finance stays the default; set your own free EQUIBLES_API_KEY to turn it on (setup).

  • Xiaomi MiMo โ€” Special thanks to MiMo Quantitative Lab for sponsoring production-grade high-performance LLM inference (powering mimo-v2.5-pro long-horizon sweeps).

  • OpenClaw Dreaming Guide โ€” Theoretical foundation for the three-phase sleep-cycle memory distillation framework.


License

This project is licensed under the MIT License - see the LICENSE file for details.

Available Tools

42 tools
add_news_sourceA
Idempotent

Add an RSS/Atom feed to the crawler's source list. The URL must be http(s) on a public host (fetched directly, not via HTTP(S)_PROXY), and is live-probed before saving โ€” a URL that doesn't parse as a feed is rejected. Idempotent: re-adding an existing URL returns the existing entry. Capped so the list can't grow unbounded.

Use when someone says "follow 's news" / "ๅŠ ไธชๆ–ฐ้—ปๆบ".

Inputs: url (required), name (required). Returns: result

buyA
Destructive

Record a buy in the local ledger: adds to an existing position with weighted-average cost, or opens a new position for an unseen symbol. This bookkeeps a trade the user already placed with their broker โ€” openInvest never places real orders.

Confirm symbol, units, and price with the user before calling; this moves ledger cash. A position the user already held before using openInvest is not a purchase: record it with record_existing_position. Off-exchange China mutual funds (FUND:<6 digits>) settle T+1 or later at the NAV of the pricing day: use place_fund_order + confirm_fund_order instead (buy books them as instantly filled and total assets dip by the amount until the real confirmation).

Args: symbol: yfinance ticker (e.g. "AAPL", "510300.SS"). Gold = "GC=F", booked in CNY per gram only (units = grams, currency "CNY", kind "metal", unit_label "ๅ…‹"). units: Quantity bought; must be > 0. price: Execution price per unit, in currency. currency: Currency of price; omitted = the existing position's currency (CNY if new). kind: Asset kind tag: "equity", "etf", "metal" (gold), "crypto", "bond", "fund", "other". unit_label: Human display label for units (default "่‚ก", i.e. shares). idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: Updated position summary, or {"status": "error", "error": ...}.

Inputs: price (required), units (required), symbol (required), kind, +4 more. Returns: result

cancel_fund_orderA
Destructive

Cancel an in-transit off-exchange fund order that was never executed (the user withdrew it on the fund platform): the amount returns to ledger cash. Only orders still in transit can be cancelled โ€” a confirmed order already holds shares (use sell to book a redemption).

Confirm with the user before calling; this moves ledger cash.

Args: order_id: The in-transit order to cancel.

Returns: Cash returned and new balance, or {"status": "error", "error": ...}.

Inputs: order_id (required). Returns: result

collect_newsB

Capture fixed news providers and durable per-source coverage, without a model call.

Capture is not proof of source truth or completed normalization. Incomplete windows remain pending; never infer a quiet market from this failure.

Inputs: since. Returns: result

committee_reviewA
Read-onlyIdempotent

Retrieve unchanged original transcript and issued verification packet; never completes work.

Inputs: context_id (required). Returns: result

confirm_fund_orderA
Destructive

Second leg of an off-exchange fund purchase: turn an in-transit order into shares at the pricing day's NAV (units = (amount - fee) / nav; average cost updates, cash unchanged). The fund_confirm job does this automatically every weekday evening, so call it manually only to supply a NAV / fee yourself or to confirm early.

Safe to call twice: an order that is already confirmed returns {"status": "already_confirmed"} (a cancelled one {"status": "cancelled"}) and nothing changes. If the pricing-day NAV is not published yet the result is {"status": "pending_nav"} and the order stays in transit.

Args: order_id: The order to confirm. nav: Unit NAV; omit to use the published NAV of the pricing day. fee: Subscription fee in CNY (default 0).

Returns: Units added, NAV used and new average cost, or {"status": "error", "error": ...}.

Inputs: order_id (required), fee, nav. Returns: result

daily_reportA

Assemble today's daily report (portfolio, verdicts, performance, holdings digest) and return it as full_report Markdown for you to deliver.

Agent mode (keyless backend): run prepare_committee โ†’ roles โ†’ submit_committee for every target asset FIRST; this tool then only reads today's submitted verdicts โ€” nothing is re-run by a backend model. Assets without a submitted verdict are listed in missing_verdicts: treat any entry there as a failure and report it. Backend mode: runs the backend committee itself (needs a backend LLM key, takes minutes).

Inputs: no named parameters. Returns: result

decisionsA
Read-only

Get the unified decision ledger: every committee verdict joined with rule interventions, the user's actual executions or refusals (with reasons), and post-hoc outcome data โ€” plus an adoption-rate summary.

Answers "how often did I follow the advice", "which recommendations did I skip", and "what did the safety rules rewrite". Read-only. Filter by symbol / verdict to answer questions about one asset or one kind of call; the list is capped at limit (newest first) so a year of history doesn't flood the context โ€” count and summary still cover every match.

Args: days: Look-back window in days (default 90). symbol: Only decisions on this ticker (case-insensitive). verdict: Only decisions with this verdict. limit: Max decisions listed (default 20; 0 = all).

Returns: Object with count (all matches), returned (listed), summary (adoption rate and aggregates over all matches), and decisions (newest first; each entry has decision_id, verdict, confidence, intervention, executed flag, matched trades, and outcome).

Inputs: days, limit, symbol, verdict. Returns: result

depositA
Destructive

Record a cash deposit into the ledger, in any currency. Bookkeeping only โ€” no real payment system is connected.

Args: currency: ISO-style currency code, e.g. "CNY", "USD", "AUD". amount: Amount to add; must be > 0. idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: Updated cash balances, or {"status": "error", "error": ...}.

Inputs: amount (required), currency (required), idempotency_key. Returns: result

disciplineA
Read-only

Get the committee's discipline ledger: how often it chose inaction (HOLD ratio), how many impulsive user trades its rules intercepted, and the counterfactual money saved/lost by those interventions (ADR-023: the system's proven value is discipline and transparency, not alpha).

Use when the user asks "what has the committee blocked" or "is this tool actually helping". Read-only.

Returns: Object with summary (structured stats) and markdown (the same ledger pre-rendered for direct display to the user).

Inputs: no named parameters. Returns: result

doctorA
Read-only

Health check, the first call of a session (same output as run.sh doctor, for agents without shell access): is onboarding done, and which optional pieces are missing.

status is "ready" when memory (user / strategy / portfolio) is initialized, or "needs_setup" when it is not (or portfolio.md is still the v1 format) โ€” only then hand over to the invest-setup skill. A missing LLM key or mail credentials never makes it "needs_setup": those checks entries are marked optional_for_coordinator / optional_for_email. The Coordinator path (prepare_committee + subagents) works without a key; only the Direct path (run_committee, cron) needs one, see direct_ready.

Read-only; makes one short HTTP probe to the configured LLM endpoint when a key is set.

Returns: Object with status, version, coordinator_ready, direct_ready, next_step, and checks (name / status / detail / hint per check).

Inputs: no named parameters. Returns: result

event_historyC
Read-only

Read qualified current events and source evidence. This is not a scan watermark or a duplicate veto.

Inputs: hours, limit. Returns: result

explain_decisionA
Read-only

Get the full reasoning behind one committee verdict: the complete 4-role debate transcript with the CIO memo, plus the path-probability snapshot the CIO saw at decision time.

Use when the user asks "why was today's verdict HOLD" or wants to audit a past decision. Read-only.

Args: decision_id: "/", e.g. "2026-07-03/GC=F" โ€” exactly as returned in the decisions tool output.

Returns: Object with verdict, confidence (the CIO's self-reported number, kept for the record), confidence_lookup (show this to the user instead: how similar verdicts (live + paper fleet) turned out 30 days later), alloc_cny, transcript_markdown (render this to the user), and path_snapshot (may be null).

Inputs: decision_id (required). Returns: result

historyA
Read-only

Get the most recent trade records and committee verdict history.

Use when the user asks "what did I buy recently" or "what did the committee decide lately". Read-only.

Args: n: Maximum number of recent trades to return (default 10).

Returns: Object with trades (each with symbol, direction, units, price, timestamp, status) and recent committee verdict records.

Inputs: n. Returns: result

ingest_eventA
Idempotent

Feed a finance news item you (the host agent) found into the event ledger, graded and mapped to affected symbols, stored for committee RAG recall.

Preferred: normalize it yourself โ€” pass one_line_claim, stance, severity (and ideally affected_symbols). The backend then only validates and stores it; no backend model is involved. Without those fields the backend model normalizes it, which fails when the backend runs keyless (agent mode) โ€” you get an error telling you which fields to add.

You have far better search reach than the self-hosted crawler (including Chinese-language sources) โ€” proactively feed news relevant to the user's holdings, especially A-share/regional coverage the crawler misses. Identical source snapshots are idempotent. Material corrections retain versions; a shared topic or URL never proves a correction is duplicate. Structured input needs no backend LLM key and grants no learning permission.

Args: title: Headline of the news item. url: Canonical source URL (also the dedup key). snippet: Short excerpt or summary of the article body. source: Publisher name (e.g. "Reuters") โ€” the news outlet. published_at: ISO 8601 publication time, if known. ingested_by: Your own agent identity (e.g. "hermes") for provenance; distinct in meaning from source.

Returns: Ingestion result with the normalized event id(s), dedup status, and committee_task_id โ€” set when a new holding-relevant event (severity โ‰ฅ mid, non-neutral) triggered a rate-limited committee re-run. In agent mode it is "queued:": the re-run waits for you in pending_committees. This tool is disabled in advisory mode.

Inputs: url (required), title (required), source, stance, +9 more. Returns: result

live_pricesA
Read-only

Fetch a one-shot market backdrop: spot gold (USD/oz and CNY/gram), USDCNY and AUDCNY FX rates, the NDQ.AX ETF price, the VIX volatility index, and the 10-year US Treasury yield (TNX). A fixed set of reference instruments, independent of what the user holds (use status for the user's own positions).

Use for quick market context before analysis or when the user asks "how is the market / what's the gold price". Read-only; single batch, no arguments.

Returns: Object keyed by instrument (GC_F_usd_per_oz, gold_cny_per_gram_spot, USDCNY, AUDCNY, NDQ_AX, VIX, TNX) plus as_of ISO timestamp. A field is null when its upstream quote is unavailable.

Inputs: no named parameters. Returns: result

news_sourcesA
Read-only

List the news feed sources the crawler pulls from: the built-in default feeds plus user-added extra feeds. Extra feeds can be added/removed with add_news_source / remove_news_source; defaults are fixed.

Use when someone asks "what news sources do you follow" or before adding/removing a source.

Inputs: no named parameters. Returns: result

pending_committeesA
Idempotent

Committee re-runs that events or price moves requested while reasoning is delegated to you (agent mode). For each item run prepare_committee, the roles, then submit_committee; an item is done once a newer verdict for that symbol is submitted. Requests expire after 24h.

Inputs: no named parameters. Returns: result

pending_newsA
Idempotent

News the backend fetched but did not normalize because reasoning is delegated to you (agent mode). For each relevant item call ingest_event with one_line_claim / stance / severity / affected_symbols; pass the irrelevant ones back here as dismiss_urls. Items leave the queue once ingested or dismissed, and expire after 48h.

Inputs: limit, dismiss_urls, include_expired, dismiss_source_ids. Returns: result

place_fund_orderA
Destructive

Record the first leg of an off-exchange fund purchase the user already placed with the fund platform: cash - amount, and the order is tracked as in transit (status.pending_fund_orders). Total assets do not change (the in-transit amount counts at face value), so there is no fake dip between order day and confirmation. Shares arrive when the pricing-day NAV is published: the fund_confirm job confirms automatically, or call confirm_fund_order. Bookkeeping only โ€” openInvest never places orders.

The expected confirm date uses a Monday-Friday calendar (no China holiday table) and a lag by fund type (QDII / FOF are slower, read from the fund's profile); the result says so (calendar, lag_source).

Confirm fund, amount, and order time with the user before calling; this moves ledger cash.

Args: symbol: FUND:<6 digits>. amount: Subscription amount in CNY; must be > 0. currency: Currency of the amount (CNY). order_ts: Order time, ISO 8601 Beijing time (default now). note: Free-text note. idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: order_id, pricing day (nav_date), expected confirm date, and new cash balance, or {"status": "error", "error": ...}.

Inputs: amount (required), symbol (required), note, currency, +2 more. Returns: result

prepare_committeeA

Step 1 of the agent-run committee (Coordinator path): get everything YOU need to play the 4 roles yourself โ€” no backend LLM key involved.

Returns the deterministic data blocks (regime, sentiment / defense flag, valuation, macro, events, portfolio, path reference) plus the 6 role prompts and instructions describing the 3 rounds. Run Macro / Quant / Risk (cheap subagents are fine), write the CIO memo yourself, then call submit_committee with the full transcript.

The backend keeps its own copy of the deterministic facts from this call and uses them when you submit (defense downgrade, regime, path snapshot), so a fact you forget to paste cannot silently switch a rule off. Submit within 6 hours of preparing.

Inputs: symbol (required), model, provider.

quality_statusA
Read-onlyIdempotent

Read independent decision-quality alerts and evidence/learning eligibility.

Check this before treating all-HOLD output as quiet success. Alerts are review requests, not permission to trade. Does not modify accounts or send messages.

Inputs: no named parameters. Returns: result

rebalance_planA
Read-only

Compute a rebalance list against the target allocation in strategy.md: what to BUY / SELL, how much, in whole lots, and why. Only produces the list, places no order โ€” the human executes. No LLM call.

Use when the user asks "do I need to rebalance", "how far am I from my target allocation" or "what should I buy/sell to get back on target". Per-asset targets come from target_assets[].target_pct in strategy.md; assets without one split target_allocation_stock equally (target_source: "equal_split"). Lot sizes: A-shares 100, convertible bonds 10, off-exchange funds by amount, HK/others 1 (HK lot size is unknown โ€” see lot_note).

Args: mode: "cash_only" | "sell_to_rebalance" | "hybrid" (default). band_pct: Drift band in percentage points, default 5.

Returns: rows (per target asset: current_pct / target_pct / drift_pct / action BUY|SELL|NONE / amount in base currency / units / reason), totals (cash_after, turnover, n_trades), unmanaged holdings, warnings; or {"status": "error", "error": ...}.

Inputs: mode, band_pct. Returns: result

record_balance_observationA
DestructiveIdempotent

Record independent value, native quantity or per-native-unit average cost observations.

No value-to-quantity conversion, cash movement, inferred fill or historical return approval. Historical/mismatched evidence stays audit-only. Invoke only for facts the client actually supplied, with its original as-of time.

Inputs: as_of (required), source_text (required), source_locator (required), idempotency_key (required), +8 more. Returns: result

record_dividendA
Destructive

Record a dividend (or interest) the user already received: credits ledger cash by amount - tax_withheld, positions unchanged. It counts as account return (inside NAV), not as a deposit. Bookkeeping only โ€” openInvest never moves money.

Confirm symbol, gross amount, withholding tax, and the date with the user before calling; this moves ledger cash. A symbol that is neither held nor in the ledger is rejected (typo guard).

Args: amount: Gross amount before withholding tax; must be > 0. currency: Currency of the cash credited. symbol: Ticker (required for dividends; optional for interest). kind: "dividend" (default) or "interest". tax_withheld: Tax withheld at source; credited cash = amount - tax_withheld. reinvest: DRIP โ€” buy more symbol with the net amount. reinvest_price: Price per unit for the reinvestment (default: stored raw close). trade_date: YYYY-MM-DD the cash arrived (default today). note: Free-text note. idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: Cash credited and new balance, or {"status": "error", "error": ...}.

Inputs: amount (required), currency (required), kind, note, +6 more. Returns: result

record_executionA
Idempotent

Record whether the user executed or declined a committee verdict, with their reason. Appends to the execution ledger; idempotent โ€” replaying the same record is a no-op, so retries are safe.

Call when the user says "I bought it / I didn't buy / I disagree". When they decline, ask one short question for the reason first โ€” this closes the adoption-rate loop that decisions reports on.

Args: decision_id: "/" from the decisions output. executed: True if the user acted on the verdict, False if declined. reason: The user's stated reason (especially when declined). trade_ids: Optional trade record IDs to link explicitly.

Returns: The stored execution record, or {"status": "error", "error": ...}.

Inputs: executed (required), decision_id (required), reason, trade_ids. Returns: result

record_existing_positionA
Destructive

Record a position the user already held before using openInvest (onboarding backfill) WITHOUT touching ledger cash. History is marked funding_source: external_funding, source: mcp:existing_position.

Only for positions that status does not list yet โ€” calling it for a symbol already there adds the units again (double count). A new purchase paid from ledger cash is buy. Does not add the symbol to the tracked list; use track_asset for committee coverage.

Args: symbol: yfinance ticker (e.g. "AAPL", "510300.SS"). Gold = "GC=F", booked in CNY per gram only (units = grams, currency "CNY", kind "metal", unit_label "ๅ…‹"). units: Quantity held; must be > 0. price: Average cost per unit, in currency. currency: Currency of price; omitted = the existing position's currency (CNY if new). kind: Asset kind tag: "equity", "etf", "metal" (gold), "crypto", "bond", "fund", "other". unit_label: Human display label for units (default "่‚ก", i.e. shares). idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: Updated position summary, or {"status": "error", "error": ...}.

Inputs: price (required), units (required), symbol (required), kind, +3 more. Returns: result

record_feeA
Destructive

Record a fee or a tax the user already paid: debits ledger cash, positions unchanged. It is an account cost (inside NAV), not a withdrawal. Trade commissions need no separate entry โ€” buy / sell already book the trade. Fails if the currency's cash balance is lower than the amount.

Confirm the amount and date with the user before calling; this moves ledger cash.

Args: amount: Amount paid; must be > 0. currency: Currency of the cash debited. kind: "fee" (default) or "tax". symbol: Related ticker (optional). trade_date: YYYY-MM-DD it was charged (default today). note: Free-text note. idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: Cash debited and new balance, or {"status": "error", "error": ...}.

Inputs: amount (required), currency (required), kind, note, +3 more. Returns: result

record_return_of_capitalA
Destructive

Record a return of capital (some ETF / REIT distributions): credits ledger cash, lowers the holding's average cost by amount / units (a cost reduction, not income), units unchanged. Cost floors at 0; any excess is reported as excess_over_cost (treat as a capital gain).

Confirm symbol, amount, and date with the user before calling; this moves ledger cash and changes average cost.

Args: symbol: Held ticker. amount: Cash received; must be > 0. currency: Currency of the cash (must match the holding's cost currency). trade_date: YYYY-MM-DD received (default today). note: Free-text note. idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: New average cost, or {"status": "error", "error": ...}.

Inputs: amount (required), symbol (required), currency (required), note, +2 more. Returns: result

record_splitA
Destructive

Record a stock split / reverse split: units x ratio, average cost / ratio, cash unchanged (market value is unchanged). Call it once per split โ€” a second call multiplies the position again; use an idempotency_key if unsure whether an earlier attempt landed. Rejected when the ledger already has trades / corrections for the symbol on or after trade_date (their units are already post-split, so multiplying the whole snapshot would invent shares) โ€” pass ledger_only=true if the snapshot is already correct.

Confirm symbol, ratio, and ex-date with the user before calling; this rewrites the position's units and average cost.

Args: symbol: Ticker that split. ratio: New / old shares (10-for-1 = 10; 1-for-10 reverse = 0.1). trade_date: Ex-date YYYY-MM-DD (default today). note: Free-text note. ledger_only: Write the ledger row only; do not change units / average cost. idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: New units / average cost (plus a follow_up hint), or {"status": "error", "error": ...}.

Inputs: ratio (required), symbol (required), note, trade_date, +2 more. Returns: result

remove_news_sourceA
Destructive

Remove a user-added news feed by name or URL. Built-in default feeds cannot be removed.

Inputs: key (required). Returns: result

run_committeeA
Idempotent

Run the 4-role LLM investment committee on a symbol (Direct path): Macro Strategist, Quant Analyst, and Risk Officer debate from isolated evidence, then a CIO synthesizes one calibrated BUY/HOLD/SELL-style verdict with a written memo.

Requires a backend LLM key (e.g. DEEPSEEK_API_KEY) and takes 30-90s on a cache miss. If the symbol was already analyzed today, the cached verdict is returned instantly unless force is set. Sends MCP progress notifications per debate phase when the client asks for them. Decision support only โ€” the human always executes.

Args: symbol: Symbol to analyze. Listed assets use yfinance tickers: US "AAPL", A-share "603083.SS" (Shanghai) / "000001.SZ" (Shenzhen), HK "0700.HK", exchange ETF "510300.SS", crypto "BTC-USD", futures "GC=F". China off-exchange (OTC) mutual funds use "FUND:<6-digit code>", e.g. "FUND:110011". A bare 6-digit code is rejected โ€” add the suffix or the FUND: prefix. force: Re-run even if a verdict already exists for today. max_rounds: Cross-challenge debate rounds (default 1).

Returns: Object with decision_id, cached flag, verdict and confidence_lookup (show this to the user instead of the self-reported confidence). The shape differs by path: - cached: false (fresh run): verdict is an object (verdict, confidence, suggested allocation, ...). - cached: true (today's transcript): verdict is the verdict string, with confidence, alloc_cny, alloc_currency alongside, plus the CIO memo as cio_memo and the deterministic input_health block (empty inputs, rewrite rules applied, forced HOLD) โ€” no need to call explain_decision just to read them.

Inputs: symbol (required), force, max_rounds. Returns: result

sellA
Destructive

Record a sell in the local ledger: reduces the position's units (average cost unchanged) and credits cash in the holding's cost currency. Bookkeeps a trade already executed at the user's broker โ€” openInvest never places real orders.

Confirm symbol, units, and price with the user before calling; this moves ledger cash.

Args: symbol: yfinance ticker of an existing holding. units: Quantity sold; must be > 0. price: Execution price per unit, in the holding's cost currency. idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: Updated position summary, or {"status": "error", "error": ...}.

Inputs: price (required), units (required), symbol (required), idempotency_key. Returns: result

set_allocationsA
Idempotent

Update the strategy's target allocation: the stock/cash ratio and/or the per-asset target weights that rebalance_plan reads, and/or the per-asset alert lines the price sentinel watches. The stock and cash values must sum to โ‰ˆ1.0, and the per-asset weights must sum to at most the stock target; schema validation rejects and rolls back any write that would corrupt the strategy file. Everything in one call is validated and written atomically โ€” to lower the stock target below the current sum of per-asset weights, pass the new weights in the same call.

Use when the user says e.g. "set my target to 70% stock / 30% cash" or "put 30% in 510300.SS and 20% in gold".

Args: target_allocation_stock: Stock weight in [0, 1], e.g. 0.7 (with cash). target_allocation_cash: Cash weight in [0, 1], e.g. 0.3 (with stock). target_pcts: {symbol: weight in [0, 1]} per tracked asset; null clears. alerts: {symbol: {rule: value}} alert lines per tracked asset; null clears a rule (or, for a whole symbol, all its rules).

Returns: The updated allocation and target assets, or {"status": "error", "error": ...}.

Inputs: alerts, target_pcts, target_allocation_cash, target_allocation_stock. Returns: result

source_snapshotA
Read-onlyIdempotent

Read the immutable original input and acquisition proof for one source version.

A backend_snapshot locator identifies a captured API item, not an upstream webpage. Source capture alone does not prove truth, independence or learning eligibility.

Inputs: snapshot_id (required). Returns: result

statusA
Read-only

Get a full snapshot of the user's portfolio: cash balances per currency, every holding with units / average cost / live price, and unrealized P&L per position and in total.

Use when the user asks "show my portfolio", "how is my P&L", or before proposing any trade. Read-only; fetches live quotes, so values change between calls.

Returns: Object with cash (currency โ†’ amount), all_holdings (every position, priced the same way whatever the symbol: units, avg_cost, live price, market value, pnl_pct; null price fields when a quote is unavailable; each carries alerts, the user's per-asset alert lines with the distance still to go, e.g. "่ท price_below ่ฟ˜ๆœ‰ 3.2%" โ€” a tracked asset with alert lines but no holding row appears as an is_tracking_only row), total_assets_cny, fx (rate to CNY per non-CNY currency in use), an optional gold summary when a gold-per-gram holding exists, and performance (real-account TWR 30d / YTD / since inception, XIRR, max drawdown with peak/trough dates, annualised volatility, return vs the configured benchmark, price_basis per symbol (raw | adjusted), and data_quality; or {"status": "insufficient_history"} until the ledger spans 2 trading days), income_30d (dividends / interest received in the last 30 days by currency; only present when there are any), and pending_fund_orders + pending_fund_orders_line (off-exchange fund orders placed but not yet confirmed โ€” cash already deducted, total_assets_cny counts them at face value; only present when there are any).

Inputs: no named parameters. Returns: result

strategyA
Read-only

Get the user's investment strategy: target stock/cash allocation, the list of tracked assets (per-asset investment cap, purchase channel, fee settings), and long-term insights distilled by the nightly Dreaming memory-consolidation job.

Use when deciding whether a proposed trade fits the user's plan, or when the user asks "what is my strategy / what am I tracking". Read-only.

Returns: Object with target_allocation (stock/cash ratios), target_assets (tracked symbols with constraints), and insights (distilled lessons from past decisions).

Inputs: no named parameters. Returns: result

submit_committeeA
Idempotent

Step 2 of the agent-run committee: hand in the transcript you produced from prepare_committee. The backend parses the CIO memo, applies the same deterministic rules as the backend-run committee (single-investment cap, defense downgrade, sanity checks), saves the decision and returns it.

If the CIO section has no parseable verdict, nothing is saved and this returns an error โ€” fix the CIO section and submit again.

Returns: decision_id, the post-rule verdict object, saved path and facts_source ("prepare" = rules used the facts saved at prepare time; "transcript" = no recent prepare found, facts were read from your text).

Inputs: symbol (required), transcript (required), model, provider, +2 more. Returns: result

track_assetA
Idempotent

Add a symbol to the tracked-asset list, or update an existing entry (idempotent upsert: only the fields you pass are changed). The tracked list decides which symbols the committee and DCA jobs cover. The alert_* parameters set per-asset alert lines the price sentinel checks every few minutes (price lines: 24h cooldown; day-move lines: once per trading day); each one you pass overwrites that line only. To clear a line use set_allocations with a null value. Delivery needs INVEST_EVENT_ALERT=1 on the server (default off โ€” without it a hit is only logged to the event store, nothing is sent).

Use when the user says "track AAPL", wants to change a tracked asset's cap/channel/fees/target weight, or says "alert me when X drops below N" / "tell me if it falls 3% in a day".

Args: symbol: yfinance ticker to track (e.g. "AAPL", "0700.HK", "BTC-USD"). max_single_invest_cny: Per-decision investment cap in CNY. On a new entry it defaults to the strategy-level max_single_invest_cny; optional on update. display_name: Human-friendly name shown in reports. channel: Where the user actually buys it (broker/app name). price_offset_pct: Systematic offset between the quote and the user's actual fill price, in percent (e.g. bank gold spread). sell_fee_pct: Sell-side fee in percent, used by fee-aware math. target_pct: Target weight as a fraction of total assets in [0, 1] (read by rebalance_plan); all tracked assets' weights must sum to <= target_allocation_stock or the write is rejected. alert_price_above / alert_price_below: price lines (status.current_price basis). alert_day_drop_pct / alert_day_rise_pct: the latest daily bar's move vs the previous close, percentage points. alert_drawdown_from_cost_pct: held position below average cost, percentage points.

Returns: The stored asset entry, or {"status": "error", "error": ...}.

Inputs: symbol (required), channel, target_pct, display_name, +8 more. Returns: result

untrack_assetA
DestructiveIdempotent

Remove a symbol from the tracked-asset list โ€” the committee and DCA jobs stop covering it. Holdings and trade history are untouched; schema validation guarantees at least one tracked asset remains.

Args: symbol: yfinance ticker currently in the tracked list.

Returns: The updated tracked list, or {"status": "error", "error": ...}.

Inputs: symbol (required). Returns: result

what_ifA
Read-only

Simulate portfolio P&L for a hypothetical price move: "what happens to my portfolio if moves ยฑpct% / reaches ". Pure arithmetic over current holdings โ€” no LLM call, instant, free.

Use when the user asks scenario questions like "if the Nasdaq drops 10%, how much do I lose". Provide exactly one of pct or price.

Args: symbol: yfinance ticker held or tracked by the user (e.g. "NDQ.AX", "GC=F", "510300.SS"). pct: Hypothetical percent change, e.g. -10 for a 10% drop. price: Hypothetical absolute target price (alternative to pct).

Returns: Object with the position's simulated value change and the resulting portfolio-level P&L delta.

Inputs: symbol (required), pct, price. Returns: result

withdrawA
Destructive

Record a cash withdrawal from the ledger, in any currency. Fails if the balance is insufficient. Bookkeeping only โ€” no real payment system is connected.

Args: currency: ISO-style currency code, e.g. "CNY", "USD", "AUD". amount: Amount to remove; must be > 0. idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: Updated cash balances, or {"status": "error", "error": ...}.

Inputs: amount (required), currency (required), idempotency_key. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    B3.4/5.0

    Scored across 42 tools

    Disambiguation2/5

    Several clusters have genuinely unclear boundaries: record_existing_position vs record_balance_observation (whose description is opaque jargon), track_asset vs set_allocations (both write target weights and alert lines), and explain_decision vs committee_review vs source_snapshot vs event_history (all return fragments of decision/evidence transcripts). The decision-read cluster (decisions / history / discipline / quality_status) also requires careful reading to pick correctly. Descriptions do cross-reference each other, but that is a patch on real overlap rather than a clean split.

    Naming Consistency4/5

    Names are uniformly lower_snake_case, and most are verb_noun (record_dividend, place_fund_order, add_news_source, untrack_asset). Deviations are limited to bare-noun readers (status, strategy, history, decisions, live_prices, news_sources), which is a readable and conventional split. No camelCase or mixed-convention chaos.

    Tool Count2/5

    42 tools is well past the 25-tool threshold for a heavy surface, spanning ledger, funds, allocation, committee, news pipeline, reports and setup. The scope is genuinely broad, but the count forces agents to navigate many rarely used interactions (source_snapshot, committee_review, record_balance_observation) that could be consolidated into fewer parameterized tools.

    Completeness4/5

    Lifecycle coverage is strong: buy/sell/deposit/withdraw, fees, dividends, splits, return of capital, fund order place/confirm/cancel, tracked-asset management, and full committee prepare/submit/run plus decision audit. Minor gaps: no way to query an arbitrary symbol's quote (live_prices is a fixed instrument set) and no correction/void tool for erroneous ledger entries, though splits explicitly reference existing corrections.

    Maintenance

    ActivityActive
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Personal investment management advisor that exposes tools for accounts, portfolios, trades, market data, strategies, risk control, and advice, enabling AI agents to analyze and provide structured investment recommendations.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Deterministic market-state engine for trading agents โ€” zero LLM in the signal path. 8 tools: structural market state & phase, action gate (GO/WATCH/HOLD), entry/target/invalidation coordinates, bar-by-bar state timeline, composed view cards, and pre-trade intent validation. Every output traces to a bar-stamped ledger with a public daily self-scoring track record.
      3
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Portfolio & trading-strategy stress diagnostics for AI agents: multi-asset stress with hedge-break detection, a daily preregistered regime outlook and deflated-Sharpe backtest-integrity checks. Remote streamable-HTTP endpoint with a free tier (no key); this repo is the public server card.
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Provides multi-agent equity research for US markets with provenance-backed financial data from SEC EDGAR, technicals, macro, and Alpaca paper trading, enforcing risk limits and journaling theses.
      27
      -