What If Rebalance API
The What If Rebalance API allows you to preview and analyze portfolio rebalancing scenarios before actually executing them. Get comprehensive risk metrics, expected returns, volatility analysis, and correlation data for proposed allocations.
Endpoint
POST /user/portfolios/{portfolioId}/rebalance/whatIfAuthentication
All requests require the IdToken obtained from the authentication flow:
Authorization: Bearer <ID_TOKEN>
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| portfolioId | string | Yes | Portfolio identifier |
Request Format
| Field | Type | Required | Description |
|---|---|---|---|
| allocations | object | Yes | Object with ticker symbols as keys and allocation percentages as values |
Allocation Details:
- Key: Ticker symbol (e.g., "AAPL", "MSFT")
- Value: Target allocation percentage (0-100)
- Total: Must be ≤ 100 (cash fills remaining)
- Support: Only supports fractionable tickers
Response Format
| Field | Type | Description |
|---|---|---|
| message | string | Confirmation message |
| summary | object | Portfolio-level risk metrics and performance summary |
| tickers | array | Per-ticker analysis with individual metrics |
| correlation | object | Pairwise correlation matrix between all holdings |
Summary Metrics:
- expectedAnnualReturn - Expected annual return in percentage
- annualVolatility - Standard deviation of returns in percentage
- sharpeRatio - Risk-adjusted return ratio (higher is better)
- sortinoRatio - Downside risk-adjusted return (only penalizes negative volatility)
- maxDrawdown - Maximum peak-to-trough decline in percentage
- beta - Market correlation relative to SPY benchmark
- treynorRatio - Return per unit of systematic risk
- var95Daily - Value at Risk at 95% confidence
- cvar95Daily - Expected loss if it exceeds VaR threshold
- tailRatio - Ratio of upside to downside volatility
- diversificationRatio - Diversification benefit measure
- effectiveHoldings - Effective number of independent holdings
- hhi - Herfindahl-Hirschman Index (concentration measure)
- cashAllocation - Percentage of portfolio in cash
- dataPoints - Number of trading days used in analysis
- riskC - Risk score on 0-10 scale