Nexus Core

Open source regime-adaptive financial analysis engine with MCP tool orchestration.

Live: nexusmcp.site | Source: GitHub | Patent: USPTO #64/034,229

Status

This is a reference framework and a starting point, not a production-ready product. It is a work in progress under active, iterative development.

Adopters are responsible for adding their own PII controls, access control, input validation, authentication, and data-handling boundaries appropriate to their own regulatory and security context before any real or sensitive data touches it. Adopters are also responsible for their own AI-provider data-handling posture; the framework makes no data-retention guarantees.

Provided as-is under Apache-2.0. Educational use only — nothing here is investment advice.

The code supports a public demo MCP profile and service-key-gated REST/JSON calculation endpoints. The deployed configuration is documented in DEPLOY.md; verify the live endpoints before relying on their current access posture. Browser apps should call their own BFF/API layer so Nexus service keys remain server-side.

The onchain-accounting substrate is exposed through GET /api/accounting/tools and POST /api/accounting/tools/{tool_id} with accounting contract 0.2.0, with account-scoped FIFO, explicit transfer/fee/event treatment, bounded replay, calendar holding periods, exact total-basis conservation, method-pinned opening snapshots, replay-safe lineage, and structured completeness; see the accounting contract guide. The same handler registry and configured price historian register price_history, decode_onchain_events, compute_cost_basis, and onchain_pnl_report in the native MCP full profile. The hosted demo profile excludes accounting tools. This is calculation substrate, not an end-to-end client statement or tax-return system. Authenticated linkage, exact-artifact review, delivery, and retention remain private consumer responsibilities. Release and methodology decisions are recorded in CHANGELOG.md and the accounting guide.

The current options substrate includes the MBOUM equity option expiration/chain provider, batch collar screens, and a collar-book realistic-fill layer. The engine plus REST/MCP parsers can accept midpoint net_credit and either explicit executable_net_credit or executable leg prices (call_bid / put_ask), then report stock price, shares, fill haircut, executable income, and executable annualized yield. This remains an advisor research worksheet, not an order surface or advice engine.

What This Is

Nexus Core is the open source foundation of the Protocol Wealth research engine — a regime-aware financial-analysis and DeFi/market-data engine that exposes its capabilities as a read-only REST API and as MCP (Model Context Protocol) tools. Any MCP-compatible AI client (Claude, GPT, Gemini) can access the public demo tool surface without implementing financial domain logic. Production consumers should use the REST/JSON endpoints through an authenticated service boundary. It is built on FastAPI + FastMCP (Python 3.12, sync httpx, asyncpg), runs mypy --strict + ruff, and is deployed on Google Cloud Run behind Cloudflare at nexusmcp.site.

Built and tested in production by an SEC-registered RIA (Protocol Wealth LLC, CRD #335298).

Public API

The deployed surface is read-only and carries no client data. The native /mcp transport can run as a public open-source demo endpoint; in production, NEXUS_PUBLIC_MCP_PROFILE=demo keeps that surface limited to closed-world calculation/demo tools. The REST/JSON calculation surfaces (/api/* and the planning JSON gateway) can be gated with NEXUS_ACCESS_MODE=restricted and NEXUS_API_KEYS, with pw-api sending a service bearer key. Remote MCP clients may complete a transparent OAuth handshake with no login. Every external integration degrades gracefully — to None, an empty result, or 503 — when its provider key is absent.

For the PW Cash Flow OS + PW Planning Lab + PW Retirement Income Lab direction, Nexus Core is the public-safe calculation plane. It can accept de-identified planning inputs, optional taxable / traditional / Roth planning buckets, derived monthly-close numbers, pre-screened stock symbols, caller-supplied option-chain facts, and de-identified public-chain movements under opaque account and transaction references. It must not ingest Monarch CSV exports, Seeking Alpha workbooks, Schwab order/status files, client-linked custodian rows, wallet-to-client mappings, merchant/payee strings, account nicknames, household records, advisor/client notes, approval state, release state, or books-and-records audit trails. Those production workflows belong in private PWOS / pw-api / PWPortal; Nexus should receive only de-identified calculation inputs after private ingestion.

Meta

Regime & Scoring

Market & Economic Data

Options (educational)

On-Chain & DeFi

LP Analytics (Uniswap V3 + Aerodrome Slipstream)

Supported chains (Uniswap V3): ethereum, base, optimism, polygon. (Arbitrum's published subgraph uses an incompatible schema and is not supported.) Aerodrome Slipstream — a Uniswap-V3 CLMM sibling — is read directly on-chain on Base, so the same pure engine drives it with no subgraph dependency.

Benchmarks

Architecture

MCP Client (Claude, GPT, Gemini)  /  REST clients
    │ JSON-RPC over HTTP          │ HTTP
    ▼                             ▼
Nexus Core (FastAPI + FastMCP)
├── Regime Engine (engine/regime)
│   ├── Core signals: Gold/SPX vs 200WMA, real rates, DXY, VIX, credit spreads (BBB OAS)
│   ├── Supplementary: yield curve (2s10s), precious metals
│   └── 5 regime states (Growth, Transition, Hard Asset, Deflation, Repression)
├── EMF Scoring (engine/scoring/emf)
│   └── 8-check durability scoring + confidence tiers (SEC EDGAR fundamentals)
├── Options Pricing (engine/pricing)
│   └── Black-Scholes price + Greeks, covered-call/CSP/collar overlays,
│       collar-book sizing + executable-fill haircut worksheet
├── LP Analytics (engine/lp/uniswap_v3.py)
│   └── Pure CLMM math: tick math, get_amounts_for_liquidity, exact IL, fee APR
│       (protocol-agnostic — reused across ethereum/base/optimism/polygon)
├── Benchmarks (engine/benchmarks.py)
│   └── Base-100 buy-and-hold compositions
├── Planning (engine/planning)
│   └── PII-free planning math: Monte Carlo, goals, cash flow, healthcare/LTC stress, taxable-first waterfall, inherited IRA, Roth/IRMAA, versioned tax-table provider with source/last-verified assumption metadata
├── Data Clients (data/)
│   ├── market/   yfinance, MBOUM, MarketStack, CoinGecko + cache + composite
│   ├── macro/    FRED, EIA, BEA, Treasury
│   ├── edgar/    SEC fundamentals (XBRL)
│   ├── derivatives/  Deribit
│   └── onchain/  DeBank, Tatum, The Graph, Merkl, vaults.fyi, DefiLlama, Jupiter
├── Persistence (data/db.py, data/snapshots.py)
│   └── asyncpg → private Cloud SQL (daily benchmark snapshots)
├── Jobs (jobs/daily_snapshot.py)
└── MCP Tool Registry (mcp/server)
    ├── @mcp.tool() decorator pattern
    └── Pluggable ResponseFilter hooks (adopter-supplied auth / PII / audit)

See docs/ARCHITECTURE.md for the signal ensemble, regime-state table, 8-check definitions, and the ResponseFilter tiering hook.

Key Innovations

Regime Detection — Signal ensemble maps macroeconomic conditions to regime states, informing asset-specific analysis.

EMF Scoring — Multi-dimensional 8-check durability assessment combining fundamentals, technicals, momentum, and regime alignment.

Exact LP Analytics — Pure constant-liquidity-market-maker math computes exact impermanent-loss-vs-HODL, fee APR, and total APR (including Merkl rewards) for Uniswap V3 positions.

MCP Orchestration — Tools auto-adjust analysis based on detected regime. Any LLM accesses regime-aware insights without domain logic.

Built on the Shoulders of Giants

Nexus Core stands on a foundation of exceptional open-source projects. We bundle or extend these libraries with full attribution — see NOTICE and THIRD_PARTY_LICENSES.md for complete legal notices.

Portfolio Optimization & Risk Analytics

• PyPortfolioOpt (MIT) — Mean-variance, Black-Litterman, HRP
• Riskfolio-Lib (BSD-3) — 24 convex risk measures, factor models
• empyrical-reloaded (Apache 2.0) — Performance metrics (Sharpe, Sortino, VaR)
• pyfolio-reloaded (Apache 2.0) — Professional tear sheets
• skfolio (BSD-3) — scikit-learn portfolio optimization
• ffn (MIT) — Pandas financial functions

Derivatives Pricing & Fixed Income

• QuantLib (Modified BSD) — Derivative pricing, yield curves
• FinancePy (MIT) — Numba JIT pricing for bonds/swaps/options

SEC EDGAR & Financial Data

• edgartools (MIT) — SEC filings as Python objects + built-in MCP server
• Arelle (Apache 2.0) — SEC-certified XBRL validation
• sec-parser (MIT) — Semantic parsing for LLM pipelines
• sec-edgar-downloader (MIT) — Bulk filing downloads
• yfinance (Apache 2.0) — Market data

Backtesting & Factor Analysis

• zipline-reloaded (Apache 2.0) — Event-driven backtesting
• alphalens-reloaded (Apache 2.0) — Factor performance analysis

AI & ML for Finance

• FinRL (MIT) — Reinforcement learning for portfolios
• FinBERT (Apache 2.0) — Financial sentiment classification (via Transformers)

Huge thanks to every maintainer and contributor of these projects. Financial software has historically been locked behind proprietary walls — Nexus Core would not exist without the open-source financial ecosystem.

What's Open vs Private

Open (Apache 2.0): Framework architecture, scoring structure, layer model, tool pattern, public-safe REST/MCP surfaces, caching patterns, and the de-identified onchain price/decoder/FIFO/PnL calculation substrate — and Protocol Wealth's calibrated regime thresholds + scoring values, which PW publishes openly as part of the EMF framework (protocolwealthllc.com/framework). All third-party integrations listed above.

Private: API keys, client data, Monarch imports, Schwab/custodian files, Seeking Alpha CSV/XLSX imports, wallet-to-client linkage, client-linked raw transaction ingestion, household records, advisor/client planning workflows, suitability logic, statement/report production, approvals, release workflow, books-and-records audit trail, the narrative and research-ingestion pipeline, and any client-specific implementation. (Calibrations are not private — EMF is a published framework. Adopters with different signal sources should still re-fit.)

Installation

Package name: the official PyPI distribution is pw-nexus-core. The bare nexus-core name on PyPI is an unrelated project and is not maintained by Protocol Wealth. Tagged releases are also installable directly from GitHub.

Full install (all capabilities)

pip install "pw-nexus-core[all]==1.0.3"

Modular installs (reduce dep footprint)

Swap [all] for any single extra: serve (the public HTTP API + MCP server, nexusmcp.site) · mcp (local stdio MCP server) · optimization (PyPortfolioOpt, Riskfolio, skfolio) · risk (empyrical, pyfolio, ffn) · pricing (QuantLib, FinancePy) · edgar (edgartools, Arelle, sec-parser) · market (yfinance) · ai (FinRL, Transformers, torch — heavy) · backtest (zipline-reloaded, alphalens). Omit the bracket entirely for core only (regime + scoring).

pip install "pw-nexus-core[serve]==1.0.3"

From source

Install the same reviewed tag directly from GitHub:

pip install "pw-nexus-core[all] @ git+https://github.com/Protocol-Wealth/nexus-core.git@v1.0.3"

Quick Start

Hosted — no install. The server is live at nexusmcp.site. Public liveness and docs routes are anonymous; production /api/* examples require a service API key when the hosted deployment is in restricted mode:

curl https://nexusmcp.site/health
curl -H "Authorization: Bearer $NEXUS_SERVICE_API_KEY" \
  https://nexusmcp.site/api/regime              # current macro regime
curl -H "Authorization: Bearer $NEXUS_SERVICE_API_KEY" \
  https://nexusmcp.site/api/planning/tools      # planning contract + tool ids

# a planning tool (educational, PII-free — send age, never date of birth)
curl -X POST https://nexusmcp.site/api/planning/tools/glide_path \
  -H "Authorization: Bearer $NEXUS_SERVICE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"currentAge": 40, "retirementAge": 65, "horizonAge": 95,
       "startEquityWeight": 0.8, "endEquityWeight": 0.4, "shape": "linear"}'

In Python — the regime engine is built over data providers:

from nexus_core.app.main import build_market_provider
from nexus_core.data.macro import FredMacroData
from nexus_core.engine.regime import RegimeEngine

engine = RegimeEngine(market_data=build_market_provider(), macro_data=FredMacroData())
result = engine.classify()
print(result.to_dict())   # regime code, confidence, per-signal breakdown, rationale

See examples/ for more runnable snippets.

Run the public API + MCP server

pip install -e ".[serve]"
nexus-core serve     # HTTP API + MCP-over-HTTP — http://127.0.0.1:8080
nexus-core mcp       # MCP server over stdio (for Claude Desktop)
nexus-core snapshot  # Write a daily benchmark snapshot to the database

nexus-core serve hosts the surface deployed at nexusmcp.site: the read-only REST API described above, interactive docs at /docs, and an MCP endpoint at /mcp. In hosted production, /mcp may remain a public OAuth-compatible demo surface while REST/JSON calculation paths are service-key gated. See DEPLOY.md for the Cloud Run + Cloud SQL + Cloud Scheduler deployment.

Using with any MCP client

The hosted MCP endpoint is public and read-only, so any MCP-compatible AI client (Claude, GPT, Gemini), or an agent platform such as SmythOS, can register https://nexusmcp.site/mcp as a read-only demo MCP server. Some remote clients complete transparent OAuth automatically; there is no user login. Production integrations should call the REST/JSON API through pw-api with a service API key. For example, in a .mcp.json (or any client config that follows the same shape):

{
  "mcpServers": {
    "nexus-core": {
      "type": "http",
      "url": "https://nexusmcp.site/mcp"
    }
  }
}

See the MCP setup guide for per-client steps (Claude.ai, Claude Code, Claude Desktop, and other clients) and tools/list output.

Configuration

All configuration is environment-driven. Every variable is optional; the app runs without any of them, with reduced data coverage.

Tech Stack

Python 3.12 · FastAPI · FastMCP · httpx · asyncpg · PostgreSQL (Cloud SQL) · pandas · numpy · scipy · mypy --strict · ruff · CI-gated test + lint suite

Documentation

• Live and planned work — current surface status and forward lanes; open work is in GitHub Issues, which is authoritative
• Validation — latest local gates and live smoke evidence
• Changelog
• Architecture
• Deployment — running the public API + Cloud Run / Cloud SQL deploy
• Public-surface audit — what the deployment exposes (and excludes)
• Attribution — detailed provenance per capability
• Contributing
• Code of Conduct
• Security

Patent & IP

Patent Pending — USPTO Application #64/034,229 "Compliance-First Quantitative Research Engine with Multi-Signal Regime Detection, Systematic Asset Scoring, and AI Tool Orchestration via Model Context Protocol for SEC/FINRA-Regulated Financial Advisory Services"

• Patent disclosure · USPTO Patent Center · Figure 1 — system drawing (PDF)
• Applicant: Protocol Wealth, LLC
• Inventor: Nicholas Rygiel
• Filed: April 9, 2026
• Status: Patent Pending

This patent was filed defensively under Apache 2.0. The intent is to establish formal prior art and prevent third parties from patenting these concepts and restricting their use by independent financial advisors. Under Apache 2.0, you receive an automatic, perpetual, royalty-free patent grant. If you sue Protocol Wealth for patent infringement related to this software, your license terminates automatically.

Open Invention Network (OIN) Member — Protocol Wealth LLC is a member of the Open Invention Network (OIN), the world's largest patent non-aggression network with 4,100+ members including Google, IBM, Toyota, Meta, Microsoft, and Amazon. Learn more

See PATENTS for full non-assertion pledge.

License

Apache License 2.0 — see LICENSE.

Apache 2.0 includes an explicit patent retaliation clause that MIT lacks. If someone sues you for patent infringement related to Nexus, their right to use the software terminates automatically.

Third-party components retain their original licenses. See NOTICE and THIRD_PARTY_LICENSES.md.

Contributing

We welcome contributions. All commits must include a Signed-off-by: line certifying agreement with the Developer Certificate of Origin:

git commit -s -m "feat: your change"

See CONTRIBUTING.md for full guidelines.

Related

• PWOS Core — Compliance-first AI operating system (pwos.app)

Links

• Live App: nexusmcp.site
• MCP setup guide · REST docs · llms.txt
• USPTO Patent Center #64/034,229
• Protocol Wealth

Built by Protocol Wealth LLC — SEC-Registered Investment Adviser (CRD #335298)