# FinSight — Pay-per-use Crypto Portfolio Analyzer on Tempo Chain > Analyze your crypto portfolio with live CoinGecko market data. Pay $0.005–$0.05 USDC on Tempo chain per call. > Works natively with Claude, Cursor, and any MCP-compatible AI agent. > Version: 3.1.0 | Real data: CoinGecko (70+ crypto) + Twelve Data (60+ equity) + Yahoo Finance (30+ IDX) + FRED (macro indicators) ## What Makes This Useful **You only need to provide tickers and weights.** For known crypto assets (BTC, ETH, SOL, AVAX, ARB, etc.), the server auto-fetches 365 days of real price history from CoinGecko and computes: - avgReturn (1-year annualized return) - volatility (30-day realized, annualized) - maxDrawdown (1-year peak-to-trough) This means instead of guessing "BTC volatility is probably 80%", you get the actual figure from market data. **Minimal request — real results:** ```json { "holdings": [ { "asset": "BTC", "weight": 0.6 }, { "asset": "ETH", "weight": 0.3 }, { "asset": "USDC", "weight": 0.1 } ] } ``` The server auto-populates all metrics, detects USDC as a stablecoin, and runs the full analysis. ## Base URL https://finsight-mpp.finsight-mpp.workers.dev ## Free Endpoints (no payment needed) GET / Service overview: network, data sources, supported assets, quick start. GET /demo Live showcase: free risk + diversification analysis of a sample BTC/ETH/SPY/GLD portfolio using real CoinGecko + Twelve Data data. Rate limited to 2 requests per IP per day. GET /health Uptime check. Returns { status: "ok", version: "3.1.0" }. GET /pricing Full pricing for all endpoints with Tempo chain payment details. GET /llms.txt This file. ## Paid Endpoints (USDC on Tempo chain, ~500ms settlement) All paid endpoints: - Auto-enrich holdings via CoinGecko (crypto), Twelve Data (equity/ETF), Yahoo Finance (IDX Indonesia) - Support ?dry_run=true for development (requires Authorization: Bearer ) - Return warnings[] (non-blocking data quality hints) and request_id in every response - Response header X-Data-Sources shows which assets were enriched and from which source POST /analyze/risk — $0.005 Risk profiling using real volatility data from CoinGecko. Returns: portfolioRisk (0-100), portfolioVolatility, portfolioSharpe, portfolioSortino, portfolioCalmar, portfolioBeta, expectedReturn, riskTier (low/moderate/high/very_high), assets[] with per-asset risk scores. POST /analyze/rebalance — $0.01 Rebalancing recommendations using real vol-weighted methods. Methods: profile (conservative/balanced/aggressive), risk_parity (inverse-vol), min_variance (inverse-variance), equal_weight (1/N). Returns: method, profile, suggestions[] with currentWeight, targetWeight, action, delta. targetWeightsSum always = 1.0. POST /analyze/diversification — $0.005 Diversification scoring using Herfindahl-Hirschman Index (HHI). Returns: hhi (0-10000), effectiveAssets, grade (excellent/good/moderate/poor/critical), stableRatio, topHolding, assetClassBreakdown[], regionBreakdown[], sectorBreakdown[]. POST /analyze/stress — $0.01 Stress test across 10 macro scenarios, shocks applied to real drawdown/volatility data. Scenarios: market_crash, crypto_winter, stablecoin_depeg, high_volatility, recovery_bull, rate_hike_shock, recession, stagflation, geopolitical_shock, dollar_rally. Returns: baseValue (10000), scenarios[] with portfolioValue, change, worstAsset, bestAsset. POST /analyze/var — $0.01 VaR and CVaR (Expected Shortfall) computed from real portfolio volatility. Returns: confidence95 { dailyVaR, annualVaR, dailyCVaR, annualCVaR }, confidence99 { ... }, worstCaseDollarLoss1M, interpretation. POST /analyze/factors — $0.01 Factor exposure: market beta, asset-class contributions, region/sector breakdown, portfolio duration, weighted dividend yield, currency exposure, interest-rate sensitivity. Returns: marketBeta, betaInterpretation, assetClassContributions[], regionBreakdown[], sectorBreakdown[], portfolioDuration, weightedDividendYield, currencyExposure[]. POST /analyze/correlation — $0.01 Cross-asset correlation matrix and diversification ratio. Returns: matrix[] (full N×N), avgPairwiseCorrelation, diversificationRatio, assetClassCorrelations[], interpretation. POST /analyze/regime — $0.01 Market regime detection from macro indicators + portfolio signals. Regimes: risk_on | stable_growth | recovery | high_volatility | risk_off | crisis. Returns: regime, confidence (low/medium/high), signals[], portfolioFitScore (0-100), recommendation, suggestedAdjustments[]. Note: if FRED_API_KEY is configured on the server, macro indicators (VIX, yield curve, CPI, GDP) are auto-fetched. Provide marketIndicators manually for confidence=HIGH. POST /analyze/montecarlo — $0.02 Monte Carlo simulation: 10,000-path Geometric Brownian Motion over 1–30 years. Query params: ?years=5&simulations=10000 (both optional, defaults shown). Returns: percentile outcomes (p5, p25, p50, p75, p95), expected value, loss probability, annualised return distribution. POST /analyze/report — $0.05 Full analysis — all 9 modules in one call + ExecutiveSummary. Cached 30s for identical inputs (X-Cache: HIT/MISS header). Returns: risk, rebalance, diversification, stressTest, varCvar, factorExposure, correlation, marketRegime, executiveSummary { overallScore (0-100), grade (A-F), keyStrengths[], keyRisks[], topRecommendations[] }, generatedAt, version. POST /analyze/compare — $0.03 Compare two portfolios side-by-side. Both legs auto-enriched with live market data. Input: { "portfolio_a": {...Portfolio...}, "portfolio_b": {...Portfolio...} } Returns: metrics[] with metric, portfolio_a, portfolio_b, winner (a/b/tie), delta, description; overall_winner, a_advantages[], b_advantages[], recommendation. Metrics: Sharpe, Sortino, Calmar, Volatility, Beta, VaR 95%, CVaR 99%, HHI, Effective Assets. ## Supported Tickers for Auto-Enrichment ### Crypto (CoinGecko, 365-day history, 5-min KV cache, 70+ tickers) 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 ### Equity / ETF (Twelve Data, 252-day history, 1-hour KV cache, 60+ tickers) SPY, QQQ, IWM, DIA, VTI, VOO, VEA, VWO, ARKK, GLD, SLV, GDX, USO, TLT, IEF, SHY, BND, AGG, HYG, LQD, EMB, TIPS, XLK, XLF, XLE, XLV, SOXX, SMH, AAPL, MSFT, GOOGL, AMZN, NVDA, TSLA, META, AMD, CRM, PLTR, COIN, JPM, BAC, GS, V, MA, XOM, CVX, JNJ, UNH, LLY, WMT, COST, VNQ, O, AMT, BIL, SGOV ### IDX Indonesia (Yahoo Finance, 1-year history, 1-hour KV cache, 30+ tickers) BBCA, BBRI, BMRI, BBNI, BNGA, BJTM, TLKM, EXCL, ISAT, ASII, AUTO, INDF, UNVR, ADRO, PTBA, ANTM, INCO, HRUM, BYAN, ITMG, KLBF, SIDO, MIKA, ICBP, BSDE, SMRA, CTRA, GOTO, BUKA, EMTK, SMGR, INTP Note: For unknown tickers, provide avgReturn/volatility/maxDrawdown manually. ## Minimal Input — Real Data Example The simplest crypto portfolio request: ```json { "holdings": [ { "asset": "BTC", "weight": 0.5 }, { "asset": "ETH", "weight": 0.3 }, { "asset": "SOL", "weight": 0.2 } ] } ``` Response includes X-Data-Sources: BTC:coingecko@2025-03-24, ETH:coingecko@2025-03-24, SOL:coingecko@2025-03-24 ## Full Input Format (all fields) All POST endpoints (except /analyze/compare) accept: ```json { "holdings": [ { "asset": "ETH", "weight": 0.40, "avgReturn": 0.45, "volatility": 0.72, "maxDrawdown": 0.78, "assetClass": "crypto", "region": "global", "beta": 1.6, "currency": "USD", "isStable": false, "dividendYield": 0, "duration": 0, "sector": "layer1" }, { "asset": "TLT", "weight": 0.20, "avgReturn": 0.04, "volatility": 0.14, "maxDrawdown": 0.25, "assetClass": "bond", "region": "US", "beta": -0.2, "currency": "USD", "dividendYield": 0.038, "duration": 18 }, { "asset": "USDC", "weight": 0.40, "isStable": true, "assetClass": "cash", "beta": 0 } ], "profile": "balanced", "benchmarkReturn": 0.08, "riskFreeRate": 0.05, "rebalanceMethod": "risk_parity", "marketIndicators": { "vix": 22, "yieldCurve": 0.3, "creditSpread": 1.5, "inflationRate": 3.2, "gdpGrowth": 2.1 } } ``` ## Holding Field Reference | Field | Type | Required | Default | Auto-filled? | Description | |---------------|---------|----------|---------|----------------------|----------------------------------------------------------| | asset | string | yes | — | — | Ticker or name (max 20 chars) | | weight | number | yes | — | — | Portfolio weight 0-1. All weights must sum to 0.98-1.02. | | avgReturn | number | no | 0 | Yes, known tickers | Annual return as decimal (0.12 = 12%) | | volatility | number | no | 0.3 | Yes, known tickers | Annual volatility as decimal (0.20 = 20%) | | maxDrawdown | number | no | 0.3 | Yes, known tickers | Max peak-to-trough decline as decimal | | isStable | boolean | no | false | Yes, USDC/USDT/DAI | True for stablecoins / cash-equivalent assets | | assetClass | enum | no | crypto | No | crypto / equity / commodity / bond / real_estate / cash | | sector | string | no | — | No | e.g. "technology", "energy", "layer1", "defi" | | region | enum | no | global | No | US / EU / UK / APAC / EM / global / other | | beta | number | no | 1 | No | Market beta (class defaults: crypto=1.5, equity=1.0) | | currency | string | no | USD | No | ISO 4217 code (3 chars) | | dividendYield | number | no | 0 | No | Annual yield as decimal (0.03 = 3%) | | duration | number | no | 0 | No | Modified duration in years (bonds only) | ## Advisory Warnings All responses include warnings[] — non-blocking data quality hints: - Bond with duration=0 → set modified duration (e.g. 5 for IEF, 18 for TLT) - isStable=true but volatility > 5% → contradiction - Cash asset with beta != 0 → cash beta should be 0 - avgReturn > 500% → likely decimal/percent confusion (use 0.55 not 55) - Crypto with dividendYield > 5% → most crypto does not pay dividends - Non-bond with duration > 2 → duration is a bond concept ## Error Reference 400 — Validation failed. details field contains per-field errors. 402 — Payment required. MPP challenge. mppx SDK handles this automatically. 401 — Unauthorized. dry_run requires valid Bearer token. 403 — dry_run disabled. DRY_RUN_TOKEN not configured on server. 429 — Rate limit. 60 req/min per IP. Retry-After: 60. 503 — MPP_SECRET_KEY not configured. 500 — Internal error. Include request_id in support requests. ## Response Headers X-Request-ID — UUID per request. Include in bug reports. X-Data-Sources — Which tickers were enriched, e.g. "BTC:coingecko@2025-03-24" X-Dry-Run: true — Confirms ?dry_run=true and no payment was charged. X-Cache: HIT|MISS — On /analyze/report only (30s KV cache). Retry-After: 60 — On 429 responses. ## Payment Flow 1. POST request → Worker returns 402 with MPP payment challenge 2. mppx SDK auto-pays USDC on Tempo chain (chainId: 4217, ~500ms finality) 3. Request retried with payment proof → Worker validates and returns result No subscriptions. No API keys. No credit cards. Pure USDC micropayments. ## Quick Start — Minimal Crypto Portfolio ```bash # Install mppx CLI npm install -g mppx # Analyze BTC+ETH+SOL — server auto-fetches real price data from CoinGecko mppx post https://finsight-mpp.finsight-mpp.workers.dev/analyze/risk \ '{"holdings":[{"asset":"BTC","weight":0.5},{"asset":"ETH","weight":0.3},{"asset":"SOL","weight":0.2}]}' ``` ## Quick Start — Free Demo (no payment) ```bash # See live analysis of a sample portfolio with real CoinGecko data curl https://finsight-mpp.finsight-mpp.workers.dev/demo ``` ## Quick Start — dry_run (development) ```bash # Validate + compute without spending USDC (requires DRY_RUN_TOKEN from server operator) curl -X POST "https://finsight-mpp.finsight-mpp.workers.dev/analyze/report?dry_run=true" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{"holdings":[{"asset":"BTC","weight":0.6},{"asset":"ETH","weight":0.3},{"asset":"USDC","weight":0.1}]}' ``` ## Tempo Chain Integration FinSight is a flagship application on Tempo chain — demonstrating real-world utility of blockchain-based micropayments for AI-agent services. - Network: Tempo (EVM-compatible rollup) - Chain ID: 4217 - Payment token: USDC (0x20C000000000000000000000b9537d11c60E8b50) - Settlement: ~500ms, gas ~$0.001 per transaction - No wallet setup needed for end users — mppx SDK handles everything ## Source GitHub: https://github.com/dun999/finsight-mpp Demo: GET https://finsight-mpp.finsight-mpp.workers.dev/demo