Per-security signal
Before sizing a position, pull the provenance-aware composite signal for the ticker. Same request shape as this endpoint, so the integration is nearly free.
Portfolio risk analytics
Post holdings. Get risk numbers.
Building a portfolio risk view usually means wiring a price-history provider, writing a returns pipeline, and implementing VaR and drawdown yourself. /v1/risk collapses that into one request: send what the account holds, get computed metrics and any constraint breaches back.
- No return series to assemble
- Constraint breaches reported
- 100,000 free Quan 3.4 L tokens
portfolio-risk.sh
curl https://stockup.cc/v1/risk \
-H "x-api-key: $STOCKUP_API_KEY" \
-H "content-type: application/json" \
-d '{
"question": "Where is the concentration risk here?",
"horizon": "months",
"objective": "balanced",
"portfolio": {
"cash": 12000,
"holdings": [
{ "ticker": "NVDA", "shares": 120 },
{ "ticker": "MSFT", "shares": 40 },
{ "ticker": "KO", "shares": 200 }
]
},
"constraints": {
"maxPositionPct": 0.25,
"cashFloorPct": 0.05,
"maxVaRPct": 0.12
}
}'Returns computed risk plus a
decisionId you can retrieve later.9 metricsVaR, CVaR, Sharpe, Sortino, more
5 constraintsPosition, sector, cash, turnover, VaR
Verified contextPrices checked before computing
ReplayableImmutable decision record
What the risk engine computes
Standard analytics, computed rather than described.
| Metric | What you use it for |
|---|---|
| Volatility | Annualised dispersion of returns — the baseline everything else is scaled against. |
| Value at risk (VaR) | Loss threshold at a confidence level. Pair it with maxVaRPct to make it a hard constraint. |
| Conditional VaR (CVaR) | Average loss beyond the VaR threshold. This is the number that matters in the tail. |
| Sharpe ratio | Return per unit of total volatility. |
| Sortino ratio | Return per unit of downside volatility — usually the fairer read for a long-only book. |
| Maximum drawdown | Worst peak-to-trough decline. The metric users actually feel. |
| Beta | Sensitivity to a benchmark return series. |
| Log returns | The underlying series, so you can chart or re-aggregate it yourself. |
| RSI | Momentum context on individual positions. |
Constraints
Turn a policy document into a request field.
Most risk features fail not because the maths is wrong but because nobody encoded the rules. The constraints object takes five limits and evaluates them against the holdings you sent:
maxPositionPct— cap on any single positionmaxSectorPct— cap on aggregate sector exposurecashFloorPct— minimum cash that must remainmaxTurnoverPct— ceiling on how much the book may churnmaxVaRPct— ceiling on modelled value at risk
Set the ones you care about and omit the rest. Breaches come back identified, so your UI can flag a specific violated rule instead of showing a generic warning banner.
objective + horizon
// horizon shapes the lookback and the framing
"horizon": "days" | "weeks" | "months" | "years"
// objective shapes what counts as a problem
"objective": "capital_preservation"
| "balanced"
| "growth"A 30% single position is a breach under
capital_preservation long before it is one under growth.Related endpoints
Risk is one call in a chain.
Macro backdrop
The same 25% position means different things in Goldilocks and in Stagflation. Classify the regime, then read risk against it.
Full decision intelligence
When you want the reasoning layer rather than raw metrics, /v1/decision accepts the identical portfolio and constraints payload and returns a claim ledger with its evidence.
Audit trail
Every response is retrievable later.
Quantitative responses carry a decisionId, a releaseFingerprint identifying the engine build, a claimLedger of the assertions made, and a coverageBreakdown showing how much of the answer rested on verified data versus inference.
Pass that decisionId to /v1/audit and you get the owner-scoped immutable record back. If a user asks six months later why your product flagged their book as over-concentrated, you can answer precisely instead of re-running a since-updated model and hoping it agrees.
retrieve-audit.sh
curl https://stockup.cc/v1/audit \
-H "x-api-key: $STOCKUP_API_KEY" \
-H "content-type: application/json" \
-d '{ "decisionId": "dec_..." }'Owner-scoped: a key can only read records it created.
Risk FAQ
Before you integrate.
Do I have to send a full return series?
No. Send holdings and cash. Market context for supported securities is verified server-side before metrics are computed, which is the main reason this endpoint exists — assembling and cleaning a return series is most of the work in a risk feature.
What if a holding is not supported?
Coverage is reported rather than hidden. The response includes a coverage breakdown so you can see what the analysis actually rested on, instead of receiving a confident number computed from partial data.
Is this suitable for regulated reporting?
Treat it as research tooling. The metrics are standard and the runs are auditable, but it is not an exchange-licensed data feed and it is not a compliance product. Enterprise data-handling behaviour is established through Enterprise configuration and contract review.
How does this differ from asking a Quan model about risk?
/v1/risk computes. A model call explains. The figures here are produced by the risk engine, so a language model cannot round, drift, or invent them. Many products call both and render the numbers alongside the narrative.
Is any of this investment advice?
No. It is research and educational software, not personalized advice, and it knows nothing about your users' circumstances or tax position. See the risk disclaimer.
Skip the returns pipeline
Ship portfolio risk this week, not next quarter.
Start with 100,000 free Quan 3.4 L tokens and no card required.
Create a free API key →