Risk Manager

Quantify and manage portfolio risk using historical volatility, drawdown analysis,

correlation metrics, position sizing frameworks, and macro risk factors sourced

from the Finskills API. Outputs a structured risk dashboard with actionable

hedging and position sizing recommendations.

Setup

API Key required — Register at https://finskills.net to get your free key.

Header: X-API-Key:

> Get your API key: Register at https://finskills.net — free tier available, Pro plan unlocks real-time quotes, history, and financials.

When to Activate This Skill

Activate when the user:

• Provides a portfolio and asks "how risky is this?"
• Wants to size a new position using Kelly Criterion or % risk rules
• Asks about maximum drawdown risk for their portfolio
• Wants Value at Risk (VaR) estimate
• Asks how to hedge a portfolio against a market downturn
• Looks for stop-loss levels or risk budgeting advice

Required Information

1. Portfolio holdings: ticker + shares (or weights) for risk assessment
2. New position sizing question: ticker, account size, max loss tolerance — for position sizing
3. Risk framework preference: Kelly / Fixed % / VaR-based (default: Fixed %)
4. Time horizon: Daily / Weekly / Monthly risk measurement

Data Retrieval — Finskills API Calls

1. Historical Daily Returns for Risk Calculation

For each portfolio holding:

GET https://finskills.net/v1/stocks/history/{SYMBOL}?period=1y&interval=1d

Extract: closing prices → compute daily log returns (ln(P_t/P_{t-1}))

2. Market Breadth (Systemic Risk Context)

GET https://finskills.net/v1/free/market/breadth

Extract: advance/decline ratio, % stocks above 200MA, new highs vs new lows → gauge market risk-on/off condition

3. Benchmark Performance

GET https://finskills.net/v1/stocks/history/SPY?period=1y&interval=1d

Extract: SPY daily returns for Beta and correlation calculation

4. US Treasury Risk-Free Rate

GET https://finskills.net/v1/free/macro/treasury-rates

Extract: 3-month and 10-year yield for risk-free rate in Sharpe Ratio calculation

5. Short Volume (Individual Stock Risk Signal)

For high-concentration positions:

GET https://finskills.net/v1/free/market/short-volume/{SYMBOL}

Extract: short volume ratio (short vol / total vol) — high short ratio = elevated downside risk

Analysis Workflow

Step 1 — Individual Position Risk Metrics

For each holding (using 252 trading days of daily returns):

Daily Volatility    = std(daily_returns)
Annual Volatility   = daily_vol × √252
Daily VaR (95%)     = -1.645 × daily_vol × position_value
Daily VaR (99%)     = -2.326 × daily_vol × position_value
Max Drawdown        = max(cummax(prices) - prices) / cummax(prices)
Sharpe Ratio        = (Ann.Return - risk_free_rate) / annual_vol

Step 2 — Portfolio-Level Risk Metrics

Portfolio Variance  = Σ_i Σ_j (w_i × w_j × cov(r_i, r_j))
Portfolio Volatility = √(Portfolio Variance) × √252
Portfolio VaR(95%)  = -1.645 × daily_portfolio_vol × total_portfolio_value
Portfolio Beta      = Σ_i (w_i × cov(r_i, r_SPY) / var(r_SPY))
Portfolio Sharpe    = (Portfolio Annual Return - rf) / Portfolio Annual Volatility

Correlation matrix (simplified for 4 or fewer positions):

• Show pairwise correlations between holdings
• Flag highly correlated pairs (r > 0.75): diversification benefit is reduced

Step 3 — Risk Classification

Assign each metric to a risk tier:

Step 4 — Position Sizing Recommendations

For a new trade, calculate using Fixed Fractional method (default):

Max Risk Per Trade:  user-specified % of account (common: 1–2%)
Stop Loss Distance:  entry_price - stop_price
Position Size:       (Account × Risk%) / Stop Loss Distance
Max Shares:          min(Position Size, account × 20%)  [never > 20% allocation]

Kelly Criterion (advanced, use when win_rate and win/loss ratio are known):

Kelly %  = win_rate - (1 - win_rate) / (avg_win / avg_loss)
F*       = Kelly % × 0.5  [half-Kelly for safety]
Position = F* × account_value / entry_price

Rule of thumb safety caps:

• Single stock: Max 20% of portfolio
• Single sector: Max 35% of portfolio
• High-beta stocks (β > 1.5): Reduce position by 20–30%

Step 5 — Hedging Strategies

Based on portfolio Beta and market risk context (market breadth data):

Common hedge instruments:

• SPY puts (broad market hedge)
• QQQ puts (tech-heavy portfolio hedge)
• VXX or UVXY (volatility spike hedge — only for short-term, decay is severe)
• TLT (flight-to-quality hedge in recession scenarios)
• GLD (inflation/tail risk hedge)

Output Format

╔══════════════════════════════════════════════════════╗
║      PORTFOLIO RISK DASHBOARD  —  {DATE}            ║
╚══════════════════════════════════════════════════════╝

📊 PORTFOLIO RISK SUMMARY
  Annual Volatility:  {%}    Risk Level: {Low/Medium/High}
  Portfolio Beta:     {x}    vs. S&P 500
  Sharpe Ratio:       {x}    ({Good/Adequate/Poor} risk-adjusted return)
  Max Drawdown (1Y):  -{%}
  VaR (95%, 1-Day):   -${amount} ({%} of portfolio)

📋 POSITION RISK BREAKDOWN
  Ticker  Weight  Ann.Vol  Beta  VaR(1D,95%)  MaxDD(1Y)
  AAPL    18.4%   22.1%    1.12  -$852        -28.3%
  MSFT    24.2%   19.8%    0.98  -$1,104      -24.1%
  ...

🔗 CORRELATION MATRIX
  [Pairwise correlations between holdings]
  High correlation pairs: {Ticker A & Ticker B: r={value}} ⚠️

⚠️ RISK FLAGS
  🚨 {Ticker} is {%} of portfolio — exceeds 20% concentration threshold
  ⚠️  {Sector} exposure at {%} — elevated sector risk
  ⚠️  Portfolio beta {x} — above 1.2 threshold in current market

📐 POSITION SIZING GUIDE (for new positions)
  Account Size:    ${value}
  Risk Per Trade:  {%} = ${dollar_amount}
  Example Entry:   {TICKER} at ${price}, Stop at ${stop}
  Suggested Size:  {shares} shares (${value} = {%} of account)

🛡️ HEDGING RECOMMENDATIONS
  Current Portfolio Beta: {x}
  Market Breadth Status:  {Risk-On / Neutral / Risk-Off}
  Recommendation:         {hedge action or "No hedge needed"}
  
  If hedging: {specific instrument, quantity, rationale}

📰 MARKET RISK CONTEXT
  Advance/Decline Ratio: {x}
  % Stocks > 200MA:      {%}
  Short Interest Signal:  {Low/Elevated for key positions}

Limitations

• Historical volatility and correlation are backward-looking; future risk may differ.
• VaR assumes normally distributed returns; tail events (crashes) are underestimated.
• Correlation estimates become less reliable with fewer than 60 data points.
• This skill does not account for leverage, margin calls, or options gamma risk.