> ## Documentation Index
> Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Portfolio Analytics

> Factor-aware portfolio analysis, optimization, and stress testing

SEC API provides portfolio research analytics: factor exposure analysis, attribution, hedge candidate construction, bounded optimizer scenario generation, stress testing, and model factor analysis.

## Endpoints

### Portfolio Analysis

Analyze factor exposures, attribution, and hedge candidates for a portfolio:

```bash theme={null}
curl -X POST "https://api.secapi.ai/v1/portfolio/analyze" \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "holdings": [
      {"symbol": "AAPL", "weight": 0.25},
      {"symbol": "MSFT", "weight": 0.25},
      {"symbol": "GOOGL", "weight": 0.20},
      {"symbol": "AMZN", "weight": 0.15},
      {"symbol": "NVDA", "weight": 0.15}
    ],
    "benchmarkLabel": "Equal-weight comparison",
    "benchmarkHoldings": [
      {"symbol": "AAPL", "weight": 0.20},
      {"symbol": "MSFT", "weight": 0.20},
      {"symbol": "GOOGL", "weight": 0.20},
      {"symbol": "AMZN", "weight": 0.20},
      {"symbol": "NVDA", "weight": 0.20}
    ],
    "whatIfLabel": "Reduce NVDA concentration",
    "whatIfHoldings": [
      {"symbol": "AAPL", "weight": 0.30},
      {"symbol": "MSFT", "weight": 0.30},
      {"symbol": "GOOGL", "weight": 0.20},
      {"symbol": "AMZN", "weight": 0.15},
      {"symbol": "NVDA", "weight": 0.05}
    ],
    "category": "style"
  }'
```

Returns: factor exposures, attribution breakdown, factor-model fit, idiosyncratic risk proxy, benchmark active tilts, what-if exposure deltas, concentration risks, and hedge candidates.

### Portfolio Attribution

Explain portfolio return through factor contributions:

```bash theme={null}
curl -X POST "https://api.secapi.ai/v1/portfolio/attribution?response_mode=compact" \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "holdings": [
      {"symbol": "AAPL", "weight": 0.30},
      {"symbol": "MSFT", "weight": 0.25},
      {"symbol": "NVDA", "weight": 0.20},
      {"symbol": "JPM", "weight": 0.15},
      {"symbol": "XOM", "weight": 0.10}
    ],
    "lookback": "6m",
    "category": "style"
  }'
```

### Portfolio Hedge

Generate bounded benchmark-instrument hedge candidates for unwanted factor exposures. The response is an analytical proxy overlay with residual exposures and constraint diagnostics, not a trade instruction or full cross-exposure optimizer:

```bash theme={null}
curl -X POST "https://api.secapi.ai/v1/portfolio/hedge?response_mode=compact" \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "holdings": [
      {"symbol": "AAPL", "weight": 0.35},
      {"symbol": "MSFT", "weight": 0.30},
      {"symbol": "NVDA", "weight": 0.20},
      {"symbol": "JPM", "weight": 0.15}
    ],
    "objective": "factor_neutral",
    "constraints": {
      "maxHedges": 3,
      "maxPositionWeight": 0.10,
      "maxTotalHedgeWeight": 0.25,
      "minLiquidityUsd": 50000000,
      "excludedSectors": ["SECTOR_ENERGY"]
    }
  }'
```

### Portfolio Optimization

Generate bounded factor-aware optimizer scenarios for factor neutrality, minimum-drawdown, or regime-aware research workflows:

```bash theme={null}
curl -X POST "https://api.secapi.ai/v1/portfolio/optimize" \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "holdings": [{"symbol": "AAPL", "weight": 0.5}, {"symbol": "MSFT", "weight": 0.5}],
    "objective": "factor_neutral",
    "maxHedges": 3,
    "constraints": {"maxCandidates": 3, "turnoverLimit": 0.2, "maxRuntimeMs": 750}
  }'
```

Optimizer outputs are analytical model scenarios for research and developer workflows, not personalized investment advice or a recommendation to trade. Use `include=optimizer_candidates` when you need the full candidate weights.

### Stress Testing

Run stress scenarios against factor and macro shocks:

```bash theme={null}
curl -X POST "https://api.secapi.ai/v1/portfolio/stress-test" \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "holdings": [{"symbol": "AAPL", "weight": 0.5}, {"symbol": "MSFT", "weight": 0.5}],
    "scenarioKey": "us_recession"
  }'
```

### Model Portfolio Factor View

Drill into a model portfolio's factor profile:

```bash theme={null}
curl "https://api.secapi.ai/v1/model-portfolios/{id}/factor-view" \
  -H "x-api-key: $SECAPI_API_KEY"
```

### Model Factor Analysis

Analyze Model Builder or ad hoc model holdings without first persisting a model portfolio:

```bash theme={null}
curl -X POST "https://api.secapi.ai/v1/models/factor-analysis?response_mode=compact" \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": {"id": "growth-quality-core", "label": "Growth Quality Core", "source": "model_builder"},
    "holdings": [
      {"symbol": "AAPL", "weight": 0.30},
      {"symbol": "MSFT", "weight": 0.25},
      {"symbol": "NVDA", "weight": 0.20},
      {"symbol": "GOOGL", "weight": 0.15},
      {"symbol": "AMZN", "weight": 0.10}
    ],
    "include": {"attribution": true, "hedge": true, "optimizer": true, "positionViews": true},
    "optimizer": {"objective": "min_drawdown", "constraints": {"maxCandidates": 3, "turnoverLimit": 0.25}}
  }'
```

## Use Cases

<CardGroup cols={2}>
  <Card title="Factor Neutralization" icon="scale">
    Identify unwanted factor exposures and inspect bounded neutralization candidates.
  </Card>

  <Card title="Regime-Aware Rebalancing" icon="chart-line">
    Adjust portfolio weights based on the current macro regime.
  </Card>

  <Card title="Risk Budgeting" icon="shield-check">
    Allocate risk across factors and set concentration limits.
  </Card>

  <Card title="Hedge Construction" icon="umbrella">
    Generate benchmark-instrument hedge candidates with residual exposure, liquidity, and cost proxies.
  </Card>
</CardGroup>

## Related Skills

* [Make Portfolio Factor Neutral](/api-reference/portfolio/post-v1-portfolio-optimize) — Interactive workflow for portfolio neutralization
* [Decompose Return and Hedge](/api-reference/portfolio/post-v1-portfolio-analyze) — Attribution and hedge ideas for individual positions
* [Attribute Portfolio Return](/api-reference/portfolio/post-v1-portfolio-attribution) — Dedicated explained-return and factor-contribution workflow
* [Construct Factor Hedge](/api-reference/portfolio/post-v1-portfolio-hedge) — Bounded benchmark-instrument hedge candidate workflow