[![finsight-mpp MCP server](https://glama.ai/mcp/servers/dun999/finsight-mpp/badges/score.svg)](https://glama.ai/mcp/servers/dun999/finsight-mpp)

# FinSight — Pay-per-use Portfolio Analytics API

## What Are We Building?

**FinSight** is a **pay-per-use** financial portfolio analytics API designed to be consumed autonomously by **AI agents** (Claude, Cursor, Cline, and others) — no registration, no API key per user, just a USDC balance.

It combines two core technologies:
- **MCP (Model Context Protocol)** — the standard for integrating AI agents with external tools and APIs
- **MPP (Machine Payment Protocol) + Tempo Blockchain** — infrastructure for automated machine-to-machine micropayments

The result: an AI agent can analyze investment portfolios in real-time, pay per request on its own, and return quantitative results to the user — all without human intervention.

**Live API:** `https://finsight-mpp.finsight-mpp.workers.dev`

---

## The Role of MPP + Tempo Blockchain

### MPP (Machine Payment Protocol)
MPP is an HTTP standard for automated micropayments between machines. It works like HTTP auth but for payment challenge-response:

1. Server returns **HTTP 402 Payment Required** with a payment challenge
2. Client (AI agent) reads the challenge, pays on-chain, and attaches the payment proof
3. Server verifies the proof and serves the request

MPP enables a **registrationless paid API** — anyone with a wallet and USDC can use it immediately.

### Tempo Blockchain
Tempo is an L2 blockchain (chainId: 4217) used as the USDC payment rails. Chosen for:
- **~500ms** transaction confirmation — fast enough for per-request payments
- **~$0.001** gas fee — cheap enough for micropayments
- Native **TIP-20 token** support (USDC) for stablecoin settlement

---

## Payment Flow

```
AI Agent / Client                  FinSight Worker                Tempo Blockchain
      │                                  │                               │
      ├─── POST /analyze/risk ──────────►│                               │
      │                                  │                               │
      │◄── HTTP 402 + challenge ─────────┤                               │
      │    (amount, recipient, chainId)  │                               │
      │                                  │                               │
      ├─── Send USDC ───────────────────────────────────────────────────►│
      │◄── TX Hash / Receipt ───────────────────────────────────────────┤
      │                                  │                               │
      ├─── POST /analyze/risk ──────────►│                               │
      │    Authorization: Bearer <hash>  ├─── Verify TX ────────────────►│
      │                                  │◄── Valid ─────────────────────┤
      │◄── HTTP 200 + Analysis Result ───┤                               │
```

### Key Components

| Component | Location | Purpose |
|-----------|----------|---------|
| `MPP_SECRET_KEY` | Server (Cloudflare Worker) | Validates payment tokens from clients |
| `MPPX_SECRET_KEY` | Client (MCP Server) | Signs and generates payment tokens |
| `RECIPIENT_ADDRESS` | Server | USDC recipient wallet address |

> `MPP_SECRET_KEY` (server) and `MPPX_SECRET_KEY` (client) must share the same value.

---

## Dry-Run Mode (Development)

Test without any on-chain transaction:

```bash
curl -X POST https://finsight-mpp.finsight-mpp.workers.dev/analyze/risk?dry_run=true \
  -H "Authorization: Bearer <DRY_RUN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"holdings":[{"asset":"BTC","ticker":"BTC","weight":0.6},{"asset":"ETH","ticker":"ETH","weight":0.4}]}'
```

---

Quantitative multi-asset portfolio analytics delivered as a Cloudflare Worker with micropayment gating via Tempo chain (USDC). Supports 70+ crypto tickers, 60+ US equity/ETF tickers, 30+ IDX Indonesia stocks, and macro indicators from FRED.

## Data Sources

| Source | Coverage | Cache TTL |
|--------|----------|-----------|
| **CoinGecko** | 70+ crypto tickers, 365-day daily history | 5 min |
| **Twelve Data** | 60+ US equity/ETF, 252-day daily history | 1 hr |
| **Yahoo Finance** | 30+ IDX Indonesia stocks (.JK suffix) | 1 hr |
| **FRED** | VIX, yield curve, CPI, GDP, unemployment, M2 | 1 hr |
| **Alternative.me** | Fear & Greed Index (0-100) | 1 hr |

## Analytics Methodology

### Correlation Matrix
Computes **real Pearson correlation** `rho(X,Y) = Cov(X,Y) / (sigma_X * sigma_Y)` from daily log returns when price history is available for both assets. Falls back to asset-class heuristic estimates when no price data exists.

### Portfolio Volatility
Uses the **full covariance matrix** formula `sigma_p = sqrt(w^T * Sigma * w)` where `Sigma_ij = rho_ij * sigma_i * sigma_j`. This correctly accounts for cross-asset correlations rather than assuming a single average correlation for all pairs.

### Beta (Market Sensitivity)
Computed via **OLS regression** against SPY benchmark: `beta = Cov(r_asset, r_SPY) / Var(r_SPY)` from aligned daily log returns. SPY is always fetched as benchmark even when not in the portfolio. Falls back to asset-class defaults when insufficient data.

### Stress Testing
10 scenario simulations with **beta-adjusted impacts**. Market-wide scenarios (crash, recovery, recession) scale each asset's impact by its effective beta rather than using hardcoded constants. Sector-specific adjustments apply where relevant.

### Executive Summary
Scores portfolios on a 0-100 scale across 4 components (Sharpe, diversification, drawdown, profile alignment). Produces **5+ items** per category (strengths, risks, recommendations) with quantitative backing — e.g., specific ratios, percentages, and thresholds.

### Additional Modules
- **VaR/CVaR** — Parametric Value-at-Risk at 95% and 99% confidence
- **Monte Carlo** — 10,000-path Geometric Brownian Motion simulation (Box-Muller RNG)
- **Diversification** — HHI, effective asset count, asset-class/region/sector breakdown
- **Factor Exposure** — Market beta, duration, dividend yield, currency exposure
- **Market Regime** — Detection from macro indicators (VIX, yield curve, credit spreads)
- **Rebalancing** — Risk parity, minimum variance, equal weight, profile-based
- **Portfolio Comparison** — Side-by-side delta across 9 metrics

## Endpoints

| Endpoint | Method | Price | Description |
|----------|--------|-------|-------------|
| `/` | GET | Free | API info and supported assets |
| `/demo` | GET | Free (2/day/IP) | Live demo with BTC+ETH+SPY+GLD |
| `/pricing` | GET | Free | Full pricing table |
| `/health` | GET | Free | Health check |
| `/llms.txt` | GET | Free | MCP integration docs |
| `/analyze/risk` | POST | $0.005 | Sharpe, Sortino, Calmar, beta, risk tier |
| `/analyze/rebalance` | POST | $0.01 | Target weights by method |
| `/analyze/diversification` | POST | $0.005 | HHI, breakdown, warnings |
| `/analyze/stress` | POST | $0.01 | 10 beta-adjusted scenarios |
| `/analyze/var` | POST | $0.01 | VaR/CVaR at 95% and 99% |
| `/analyze/factors` | POST | $0.01 | Factor exposure analysis |
| `/analyze/correlation` | POST | $0.01 | Pearson correlation matrix |
| `/analyze/regime` | POST | $0.01 | Market regime detection |
| `/analyze/montecarlo` | POST | $0.02 | 10,000-path Monte Carlo |
| `/analyze/report` | POST | $0.05 | Full report: all modules + executive summary |
| `/analyze/compare` | POST | $0.03 | Compare two portfolios |

## Payment

All paid endpoints require USDC payment on **Tempo chain** (chainId: 4217) via the Machine Payment Protocol (MPP). Settlement is ~500ms with ~$0.001 gas.

**Dry-run mode** is available for development only when `DRY_RUN_TOKEN` is configured as a Wrangler secret. Requires `Authorization: Bearer <token>` header. Not publicly accessible.

## Request Format

```json
{
  "holdings": [
    { "asset": "BTC", "weight": 0.4, "assetClass": "crypto" },
    { "asset": "ETH", "weight": 0.3, "assetClass": "crypto" },
    { "asset": "SPY", "weight": 0.2, "assetClass": "equity" },
    { "asset": "GLD", "weight": 0.1, "assetClass": "commodity" }
  ],
  "profile": "balanced",
  "benchmarkReturn": 0.08,
  "riskFreeRate": 0.05,
  "rebalanceMethod": "risk_parity"
}
```

Fields like `avgReturn`, `volatility`, and `maxDrawdown` are **auto-populated from live data** when the ticker is recognized. User-provided non-default values always take precedence.

## Supported Tickers

### Crypto (CoinGecko — 70+)
BTC, ETH, SOL, BNB, XRP, ADA, AVAX, DOGE, DOT, TRX, TON, HBAR, ALGO, FTM, ICP, VET, XMR, BCH, KAS, FIL, FLOW, STX, ROSE, MATIC/POL, ARB, OP, STRK, IMX, MANTA, LINK, UNI, AAVE, MKR, CRV, LDO, SNX, COMP, GMX, DYDX, 1INCH, CAKE, ATOM, NEAR, APT, SUI, SEI, TIA, LTC, ETC, XLM, INJ, JUP, PYTH, RNDR, GRT, OCEAN, ENS, WLD, HYPE, ZRO, LIT, EIGEN, VIRTUAL, PEPE, WIF, BONK, TRUMP, SHIB, FLOKI, POPCAT, USDC, USDT, DAI, FRAX, USDS

### US Equity/ETF (Twelve Data — 60+)
SPY, QQQ, IWM, DIA, VTI, VOO, VEA, VWO, ARKK, GLD, SLV, TLT, IEF, BND, AGG, HYG, XLK, XLF, XLE, XLV, SOXX, SMH, AAPL, MSFT, GOOGL, AMZN, NVDA, TSLA, META, AMD, CRM, PLTR, COIN, MSTR, JPM, BAC, GS, V, MA, XOM, CVX, JNJ, UNH, LLY, WMT, COST, VNQ, O, AMT, BIL, SGOV, and more

### IDX Indonesia (Yahoo Finance — 30+)
BBCA, BBRI, BMRI, BBNI, TLKM, ASII, ADRO, PTBA, ANTM, GOTO, BUKA, KLBF, SIDO, BSDE, SMGR, and more

## MCP Integration

FinSight works as an MCP (Model Context Protocol) server for AI agents like Claude, Cursor, and Cline. See `/llms.txt` for setup instructions.

## Development

```bash
# Install dependencies
npm install

# Local development
npx wrangler dev

# Set secrets
wrangler secret put MPP_SECRET_KEY
wrangler secret put COINGECKO_API_KEY
wrangler secret put TWELVE_DATA_API_KEY
wrangler secret put FRED_API_KEY
wrangler secret put DRY_RUN_TOKEN

# Deploy
npx wrangler deploy
```

### KV Namespaces
- `RATE_LIMITS` — IP-based rate limiting (60 req/min)
- `CACHE` — Report result cache (30s TTL)
- `MARKET_DATA` — Price data and macro indicator cache

## Architecture

- **Runtime**: Cloudflare Workers (edge deployment)
- **Framework**: Hono (TypeScript)
- **Payment**: MPP via Tempo chain (USDC)
- **Validation**: Zod schemas with weight-sum verification
- **Caching**: Cloudflare KV with versioned keys

## Version

v3.1.0 — Twelve Data equity provider, lower pricing, demo rate limiting (2/day/IP), real Pearson correlation, OLS beta, beta-adjusted stress tests.