Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/georgejohnsonoff-business/spendwiselygeorge/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Portfolio API provides real-time valuation of your mutual fund holdings by fetching current NAV (Net Asset Value) data from MFApi and calculating total portfolio value.

​
Get Portfolio

​
/api/portfolio
GET
Calculates current portfolio value based on stored holdings and live NAV data

​
How It Works

1

Load Holdings

Reads mutual fund holdings from holdings.json
2

Fetch NAV Data

For each holding, fetches latest NAV from MFApi using scheme code
3

Calculate Values

Multiplies units by NAV to get current value for each fund
4

Aggregate Total

Sums all fund values to get total portfolio value

​
Example Request

curl http://localhost:8000/api/portfolio

​
Response

​
portfolio
array
Array of holdings with current valuations
​
total_value
number
Total portfolio value across all holdings (rounded to 2 decimal places)

​
Portfolio Item Fields

​
scheme_code
string
AMFI scheme code for the mutual fund
​
scheme_name
string
Full name of the mutual fund scheme
​
units
number
Number of units held
​
nav
number
Current Net Asset Value per unit
​
current_value
number
Total value of this holding (units × NAV, rounded to 2 decimals)

​
Example Response

{
  "portfolio": [
    {
      "scheme_code": "120503",
      "scheme_name": "Axis Bluechip Fund - Direct Plan - Growth",
      "units": 150.5,
      "nav": 48.23,
      "current_value": 7258.62
    },
    {
      "scheme_code": "119551",
      "scheme_name": "SBI Small Cap Fund - Direct Plan - Growth",
      "units": 75.25,
      "nav": 125.67,
      "current_value": 9456.67
    },
    {
      "scheme_code": "118989",
      "scheme_name": "HDFC Mid-Cap Opportunities Fund - Direct Plan - Growth",
      "units": 200.0,
      "nav": 156.89,
      "current_value": 31378.00
    }
  ],
  "total_value": 48093.29
}

​
Empty Portfolio

When no holdings are configured: 
{
  "portfolio": [],
  "total_value": 0
}
The API fetches NAV data from MFApi, a public API for Indian mutual funds:

​
Endpoint Format

https://api.mfapi.in/mf/{scheme_code}

​
Example MFApi Response

{
  "meta": {
    "scheme_code": "120503",
    "scheme_name": "Axis Bluechip Fund - Direct Plan - Growth"
  },
  "data": [
    {
      "date": "05-03-2026",
      "nav": "48.23"
    },
    {
      "date": "04-03-2026",
      "nav": "48.15"
    }
  ]
}
The API always uses the most recent NAV (first item in the data array).

​
Calculation Logic

For each holding: 
value = units * nav
current_value = round(value, 2)
Total portfolio value: 
total_value = sum(all_current_values)
total_value = round(total_value, 2)

​
Example Calculation

Holding 1: 150.5 units × ₹48.23/unit = ₹7,258.615 → ₹7,258.62
Holding 2: 75.25 units × ₹125.67/unit = ₹9,456.6675 → ₹9,456.67
Holding 3: 200.0 units × ₹156.89/unit = ₹31,378.00 → ₹31,378.00

Total = ₹7,258.62 + ₹9,456.67 + ₹31,378.00 = ₹48,093.29

​
Error Handling

​
Failed NAV Fetch

If NAV data cannot be fetched for a fund:
  • Error is logged to console: "Error fetching {code}: {error}"
  • Fund is excluded from portfolio response
  • Total value calculation continues with remaining funds

​
Common Failure Scenarios

ScenarioBehavior
Invalid scheme codeFund skipped, error logged
MFApi network errorFund skipped, error logged
MFApi returns empty dataFund skipped, error logged
Missing scheme_nameFund skipped, error logged
Funds with fetch errors are silently excluded. Check server logs for details.

​
Example with Partial Failure

If holdings.json contains: 
[
  {"scheme_code": "120503", "units": 150.5},
  {"scheme_code": "INVALID", "units": 100.0},
  {"scheme_code": "119551", "units": 75.25}
]
Response will only include valid funds: 
{
  "portfolio": [
    {"scheme_code": "120503", ...},
    {"scheme_code": "119551", ...}
  ],
  "total_value": 16715.29
}

​
Data Dependencies

​
Holdings File

Portfolio calculation requires holdings in ./holdings.json: 
[
  {
    "scheme_code": "120503",
    "units": 150.5
  },
  {
    "scheme_code": "119551",
    "units": 75.25
  }
]
Create holdings using the POST /api/holdings endpoint.

​
Network Requirements

  • Internet connection required to fetch NAV data
  • Access to api.mfapi.in must be allowed
  • No authentication required for MFApi

​
Performance Considerations

​
API Calls

The endpoint makes one MFApi request per holding:
  • 5 holdings = 5 API calls
  • 10 holdings = 10 API calls
Large portfolios (50+ funds) may experience slower response times due to sequential API calls.

​
Caching Recommendations

For production deployments, consider:
  • Caching NAV data for 15-30 minutes
  • Implementing batch NAV fetching
  • Pre-calculating portfolio values

​
Use Cases

​
Dashboard Display

const portfolioData = await fetch('http://localhost:8000/api/portfolio')
  .then(r => r.json());

console.log(`Total Portfolio Value: ₹${portfolioData.total_value}`);
portfolioData.portfolio.forEach(fund => {
  console.log(`${fund.scheme_name}: ₹${fund.current_value}`);
});

​
Performance Tracking

Compare current value against purchase value to calculate returns: 
const currentValue = portfolioData.total_value;
const invested = calculateTotalInvested(); // Your logic
const returns = currentValue - invested;
const returnPercent = ((returns / invested) * 100).toFixed(2);

console.log(`Returns: ₹${returns} (${returnPercent}%)`);

​
Finding Scheme Codes

Use MFApi to search for scheme codes: 
# Search by fund name
curl https://api.mfapi.in/mf/search?q=axis%20bluechip

# Get all schemes
curl https://api.mfapi.in/mf
Refer to MFApi documentation for complete scheme listings.

​
Next Steps

Manage Holdings

Add or update your mutual fund holdings

View Transactions

Track your transaction history

Build docs developers (and LLMs) love

Get started for freeTalk to us