Portfolio API

Base path: /api/v1/portfolio

All four resources require a valid OpenAlgo API key. Portfolio analysis is read-only and never places orders.

Endpoints

Method	Path	Authentication	Success response
GET	/benchmarks?apikey=...	Valid API key	JSON benchmark inventory
POST	/backtest	apikey in JSON	Full JSON analysis
POST	/tearsheet	apikey in JSON	Downloadable HTML
POST	/holdings	apikey in JSON plus active broker session	Current-holdings summary and analysis

The heavier JSON endpoints use PORTFOLIO_API_RATE_LIMIT, which defaults to 10 per minute. Tearsheet rendering uses PORTFOLIO_TEARSHEET_RATE_LIMIT, which defaults to 5 per minute. /benchmarks uses the shared API limit.

GET /benchmarks

Reads available index symbols from the downloaded instrument master. The list therefore varies by broker and master-contract coverage.

{
  "status": "success",
  "data": [
    {"symbol": "NIFTY", "exchange": "NSE_INDEX", "name": "Nifty 50"}
  ]
}

POST /backtest

{
  "apikey": "YOUR_OPENALGO_API_KEY",
  "holdings": [
    {"symbol": "INFY", "exchange": "NSE", "weight": 40},
    {"symbol": "HDFCBANK", "exchange": "NSE", "weight": 60}
  ],
  "start_date": "2021-01-01",
  "end_date": "2026-01-01",
  "benchmark": "NIFTY",
  "benchmark_exchange": "NSE_INDEX",
  "rebalance": "quarterly",
  "drift_band": 0.05,
  "cost_model": "indian_equity",
  "cost_exchange": "NSE",
  "slippage": 0.0005,
  "initial_capital": 100000,
  "risk_free_rate": 0.06,
  "source": "db"
}

Request fields

Field	Required	Contract
apikey	Yes	Valid OpenAlgo API key
holdings	Yes	1-50 unique holdings
holdings[].symbol	Yes	1-64 characters, normalized uppercase
holdings[].exchange	No	NSE or BSE; default NSE
holdings[].weight	Yes	Non-negative number; weights are normalized by ratio
start_date, end_date	Yes	Date strings accepted by the history layer
benchmark	No	Index symbol or null
benchmark_exchange	No	NSE_INDEX, BSE_INDEX, or GLOBAL_INDEX
rebalance	No	never, monthly, quarterly, or yearly
drift_band	No	Fraction from 0 through 0.99
cost_model	No	indian_equity or flat_bps
cost_exchange	No	NSE or BSE
cost_bps	No	Flat cost from 0 through 1000 basis points
slippage	No	Fraction from 0 through 0.1
initial_capital	No	Positive number; default 100000
risk_free_rate	No	Fraction from 0 through 0.5
source	No	db or api; default db

source=db reads local Historify data and still requires a valid OpenAlgo API key. source=api also requires an active broker session and calls broker history sequentially.

The success response contains the complete simulation generation, including equity, benchmark, metrics, holding contributions, correlations, diversification, allocation, costs, rebalancing, walk-forward, Monte Carlo, crisis, health, and insight sections.

POST /tearsheet

Accepts the same request shape as /backtest. Success returns a self-contained HTML attachment:

Content-Type: text/html; charset=utf-8
Content-Disposition: attachment; filename="portfolio-tearsheet.html"

POST /holdings

{
  "apikey": "YOUR_OPENALGO_API_KEY",
  "lookback_days": 365,
  "benchmark": "NIFTY",
  "benchmark_exchange": "NSE_INDEX",
  "risk_free_rate": 0.06,
  "source": "db"
}

lookback_days must be between 60 and 3650. This endpoint always needs an active broker session to read current holdings. Historical prices then come from the selected db or api source.

The result is a historical scenario for today's market-value allocation, not the account's actual performance. The holdings response does not contain purchase dates or cash flows, so the service cannot reconstruct realized returns.

Errors

Status	Meaning
400	Invalid schema, duplicate symbols, weights, dates, or cost policy
403	Invalid API key or required broker session absent
422	Missing/incompatible history or no usable current holdings
429	Configured rate limit exceeded
500	Unexpected internal failure

A missing benchmark can leave benchmark-relative sections empty without invalidating an otherwise usable portfolio simulation.