{"uid":"cap_6o8F5lQ37fVGJiAdOWPan","slug":"portfolio-stats-value-at-risk-expected-shortfall-1c581c48","name":"Portfolio Stats – Value-at-Risk & Expected Shortfall","description":"ILLUSTRATIVE historical and parametric Value-at-Risk and expected shortfall from a return series you supply. Not advice.","url":"https://portfolio-stats.x402tookit.com/value-at-risk?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","required":[],"properties":{"unit":{"type":"string","description":"decimal (default, 0.01 = 1%) or percent (1 = 1%); applies to returns only"},"prices":{"type":"string","description":"Price series, oldest first, JSON like [100,101,99.5] or 100,101,99.5 (up to 1000). Give prices OR returns"},"returns":{"type":"string","description":"Period returns, oldest first, decimals by default (0.01 = 1%). Give returns OR prices"},"confidencePct":{"type":"number","description":"Confidence level in percent, 90 to 99.9 (default 95)"},"periodsPerYear":{"type":"integer","description":"Periods per year for annualising: 252 daily (default), 52 weekly, 12 monthly"},"portfolioValue":{"type":"number","description":"Optional amount to express the loss in money terms"}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","properties":{"asOf":{"type":["null","string"]},"source":{"type":["null","string"]},"zScore":{"type":["null","number"]},"horizon":{"type":["null","string"]},"reasons":{"type":["array","null"],"items":{"type":"string"}},"summary":{"type":["null","string"]},"verdict":{"type":["null","string"]},"degraded":{"type":["boolean","null"]},"disclaimer":{"type":["null","string"]},"meanReturn":{"type":["null","number"]},"notChecked":{"type":["array","null"],"items":{"type":"string"}},"observations":{"type":["null","number"]},"confidencePct":{"type":["null","number"]},"historicalVaR":{"type":["null","number"]},"parametricVaR":{"type":["null","number"]},"portfolioValue":{"type":["null","number"]},"educationalOnly":{"type":["null","string"]},"historicalVaRPct":{"type":["null","number"]},"illustrativeOnly":{"type":["boolean","null"]},"parametricVaRPct":{"type":["null","number"]},"periodVolatility":{"type":["null","number"]},"tailObservations":{"type":["null","number"]},"historicalVaRAmount":{"type":["null","number"]},"parametricVaRAmount":{"type":["null","number"]},"tooFewTailObservations":{"type":["boolean","null"]},"historicalExpectedShortfall":{"type":["null","number"]},"parametricExpectedShortfall":{"type":["null","number"]},"historicalExpectedShortfallPct":{"type":["null","number"]},"parametricExpectedShortfallPct":{"type":["null","number"]},"historicalExpectedShortfallAmount":{"type":["null","number"]},"parametricExpectedShortfallAmount":{"type":["null","number"]},"negativeVaRMeansTheThresholdWasAGain":{"type":["null","string"]}}}}}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.02","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.02/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.02","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.02","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_GXX6YacPRbwEbxz5v9XPK","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.02","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Computes illustrative historical and parametric Value-at-Risk (VaR) and Expected Shortfall (CVaR) from a user-supplied price or return series.","exampleAgentPrompt":"Calculate the historical and parametric VaR plus expected shortfall for this daily price series [100,101,99.5,102,98,97,103,105,104,99], at 99% confidence, assuming 252 trading days per year, and express the loss in dollar terms for a $50,000 portfolio.","exampleUseCases":[{"title":"Daily equity risk assessment","prompt":"I have these daily closing prices for a stock: [100,102,101,99,103,107,105,104,100,98,97,101]. Can you calculate the historical and parametric VaR at 95% confidence using 252 periods per year, and tell me the dollar loss estimate for a $100,000 position?"},{"title":"Weekly fund return tail-risk check","prompt":"Here are weekly returns for my fund in decimal form: [0.01,-0.02,0.015,-0.03,0.005,0.02,-0.01,0.008,-0.025,0.012]. Compute both VaR and expected shortfall at 99% confidence, assuming 52 weeks per year."},{"title":"Monthly return risk for client report","prompt":"I have monthly percentage returns — enter them as percent units: [1.2,-2.1,0.8,-1.5,2.3,-0.4,1.1,-3.0,0.6,1.8]. Calculate parametric and historical VaR at 95% confidence with 12 periods per year so I can include it in a client summary."}],"resultDescription":"Returns an object containing historical VaR and parametric VaR (both as fractions and percentages), expected shortfall, mean return, z-score, number of observations, horizon label, confidence level, optional dollar-denominated losses if portfolioValue was supplied, a plain-language summary, an educational disclaimer, and flags for any degraded or unchecked conditions.","failureModes":["Missing both prices and returns — endpoint requires one of the two","Fewer than ~20 data points may produce unreliable or degraded estimates flagged in the response","confidencePct outside 90–99.9 range rejected or clamped","Malformed JSON array in prices or returns parameter causes a parse error","Conflicting prices and returns supplied simultaneously"],"whenToPreferThis":"Choose this endpoint when you need a quick, illustrative VaR or Expected Shortfall figure from a raw price or return series you already have, without setting up a full risk analytics platform. It supports both historical simulation and parametric (Gaussian) methods in one call, optionally annualises results, and can express losses in monetary terms — making it ideal for lightweight portfolio risk checks, educational demonstrations, or automated report generation where regulatory-grade precision is not required.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-30T00:35:23.481Z","isFirstParty":false,"canonicalSlug":"portfolio-stats-value-at-risk-expected-shortfall-1c581c48"}