Portfolio Health Guide

The Portfolio Health API provides a comprehensive score for any investment portfolio, along with actionable recommendations for improvement.

How Scoring Works

The total score ranges from 0 to 1000, broken into four components (250 points each):

Component	Weight	What It Measures
Diversification	250	Asset class variety, geographic spread
Cost Efficiency	250	Expense ratios, trading costs
Risk Alignment	250	Age-appropriate asset allocation
Rebalancing	250	Deviation from target allocation

Basic Usage

curl -X POST https://indepai.app/api/v1/portfolio-health \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      { "type": "etf", "value": 80000, "expenseRatio": 0.07 },
      { "type": "stock", "value": 15000 },
      { "type": "cash", "value": 5000 }
    ],
    "userAge": 32
  }'

Asset Schema

Each asset in the array can have these fields:

Field	Type	Required	Description
type	string	Yes	Asset type (see below)
value	number	Yes	Current value
symbol	string	No	Ticker symbol
name	string	No	Asset name
quantity	number	No	Number of units
purchasePrice	number	No	Purchase price per unit
currency	string	No	Currency code (default: EUR)
expenseRatio	number	No	Annual expense ratio (%)
region	string	No	Geographic region

Asset Types

• stock - Individual stocks
• etf - Exchange-traded funds
• crypto - Cryptocurrency
• real_estate - Real estate investments
• cash - Cash and equivalents
• bond - Bonds and fixed income
• other - Other assets

Score Levels

Score	Level	Description
0-199	Beginner	Significant room for improvement
200-399	Apprentice	Basic portfolio structure
400-599	Competent	Good foundation, some gaps
600-799	Proficient	Well-structured portfolio
800-899	Expert	Excellent portfolio management
900-1000	Master	Near-optimal portfolio

Understanding Each Component

Diversification (0-250)

Measures how well your assets are spread across:

• Asset classes - Stocks, bonds, real estate, etc.
• Geographic regions - US, Europe, Asia, Emerging Markets
• Sectors - Technology, Healthcare, Finance, etc.
• Individual holdings - Number of positions

Example of good diversification:

{
  "assets": [
    { "type": "etf", "value": 60000, "region": "Global" },
    { "type": "etf", "value": 20000, "region": "Emerging Markets" },
    { "type": "bond", "value": 15000, "region": "Europe" },
    { "type": "real_estate", "value": 10000 },
    { "type": "cash", "value": 5000 }
  ]
}

Cost Efficiency (0-250)

Analyzes your investment costs:

• Expense ratios - Lower is better (target < 0.2%)
• ETF vs mutual funds - ETFs typically have lower costs
• Passive vs active - Index funds outperform most active funds

High score example (low-cost index funds):

{
  "assets": [
    { "type": "etf", "value": 100000, "expenseRatio": 0.07 },
    { "type": "etf", "value": 50000, "expenseRatio": 0.12 }
  ]
}

Low score example (high-cost funds):

{
  "assets": [
    { "type": "etf", "value": 100000, "expenseRatio": 1.5 },
    { "type": "stock", "value": 50000 }
  ]
}

Risk Alignment (0-250)

Compares your allocation to age-appropriate targets:

Common Rule: “120 minus age” in stocks

Age	Target Stocks	Target Bonds
25	95%	5%
35	85%	15%
45	75%	25%
55	65%	35%
65	55%	45%

Include your age for accurate scoring:

{
  "assets": [...],
  "userAge": 35
}

Rebalancing (0-250)

Measures how much your portfolio has drifted from optimal:

• Target deviation - How far from ideal allocation
• Cash drag - Excess cash sitting uninvested
• Concentration risk - Any position > 25% of portfolio

Complete Example

curl -X POST https://indepai.app/api/v1/portfolio-health \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      {
        "type": "etf",
        "value": 120000,
        "symbol": "VWCE.DE",
        "name": "Vanguard FTSE All-World",
        "expenseRatio": 0.22,
        "region": "Global"
      },
      {
        "type": "etf",
        "value": 30000,
        "symbol": "EIMI.L",
        "name": "iShares EM IMI",
        "expenseRatio": 0.18,
        "region": "Emerging Markets"
      },
      {
        "type": "bond",
        "value": 25000,
        "symbol": "AGGH.L",
        "name": "iShares Global Agg Bond",
        "expenseRatio": 0.10,
        "region": "Global"
      },
      {
        "type": "cash",
        "value": 15000,
        "currency": "EUR"
      }
    ],
    "userAge": 35,
    "targetAllocation": {
      "stocks": 60,
      "bonds": 25,
      "cash": 5,
      "other": 10
    }
  }'

Response:

{
  "success": true,
  "data": {
    "totalScore": 785,
    "level": "Proficient",
    "components": {
      "diversification": 195,
      "costEfficiency": 235,
      "riskAlignment": 180,
      "rebalancing": 175
    },
    "recommendations": [
      "Excellent expense ratios - your costs are well below average",
      "Consider reducing cash allocation from 7.9% to target 5%",
      "Your emerging markets exposure (15.8%) is above typical 10% allocation",
      "Portfolio is slightly overweight equities for your age"
    ],
    "assetBreakdown": {
      "etf": 78.9,
      "bond": 13.2,
      "cash": 7.9
    },
    "totalValue": 190000
  }
}

Using with Authenticated Users

For authenticated users, the API can pull their actual portfolio:

curl https://indepai.app/api/v1/assets?summary=true \
  -H "Authorization: Bearer YOUR_TOKEN"

Then pass to portfolio health:

// Fetch user's assets
const assetsResponse = await fetch("/api/v1/assets", {
  headers: { Authorization: `Bearer ${token}` },
});
const { data: assets } = await assetsResponse.json();

// Transform to portfolio health format
const portfolioAssets = assets.map((asset) => ({
  type: asset.assetType,
  value: asset.currentValue || asset.quantity * asset.purchasePrice,
  symbol: asset.tickerSymbol,
  name: asset.name,
  expenseRatio: asset.expenseRatio,
  region: asset.geographicRegion,
}));

// Get health score
const healthResponse = await fetch("/api/v1/portfolio-health", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    assets: portfolioAssets,
    userAge: user.age,
  }),
});

Improving Your Score

Based on recommendations, here’s how to improve each component:

Improve Diversification

1. Add asset classes you’re missing
2. Include international investments
3. Add some alternatives (REITs, commodities)
4. Avoid over-concentration in single stocks

Improve Cost Efficiency

1. Switch to low-cost index ETFs
2. Target expense ratios < 0.2%
3. Avoid actively managed funds
4. Use commission-free brokers

Improve Risk Alignment

1. Adjust stock/bond ratio for your age
2. Reduce volatility as you approach FI
3. Consider your risk tolerance
4. Maintain emergency fund outside investments

Improve Rebalancing

1. Set target allocations
2. Rebalance annually or when >5% drift
3. Keep cash to 3-6 months expenses
4. Avoid position concentration

Rate Limits

Tier	Requests/Day
Starter	1,000
Pro	10,000

Related Endpoints

• List Assets - Manage your portfolio
• FI Calculator - Calculate your timeline
• Tax Calculator - Understand tax impact