Portfolio Backtest (FinBridge DB)
backtest_portfolioBacktest a fixed-weight KR or US portfolio on daily data from the local finbridge.db (stocks are corporate-action adjusted; US stocks are total-return where SEC-reported dividends exist). ⚠ETFs are PRICE-RETURN ONLY in every market (no distributions), AND US ETF bars are NOT split-adjusted yet — a series with a split is refused, not mispriced. US history starts 2023-03-28, so earlier start dates are clipped. Pure historical simulation — no forecasts.
Args:
assets: 1-15 of {symbol, weight}. symbol = KR 6-digit code ('005930'), US ticker ('AAPL', 'SPY'), or a company/ETF name. Weights are normalized to sum 1.
from (required, YYYY-MM-DD), to (default: today). Start is clipped to the latest asset inception date (noted).
rebalance: 'none'|'monthly'|'quarterly'|'yearly' (default 'yearly') — rebalanced at the close of the first trading day of each new period.
currency: 'USD' (default) | 'KRW' — reporting currency; assets in the other currency are converted daily (USDKRW, FRED DEXKOUS).
initial: starting value in the report currency (default 10000).
Returns: {period, currency, rebalance, assets[](weight_pct, first_date, dividend_adjusted, converted), metrics{total_return_pct, cagr_pct, vol_annual_pct, sharpe, mdd_pct, mdd_peak_date, mdd_trough_date, best_year, worst_year}, annual_returns[], equity_curve[](sampled, JSON only), notes[]}.
Examples:
Samsung + KODEX 200 70/30: {assets:[{symbol:'005930',weight:0.7},{symbol:'069500',weight:0.3}], from:'2021-01-01', currency:'KRW'}
Use when: "what if I invested in X portfolio since YYYY" questions, comparing allocations, drawdown/volatility analysis. Don't use for: single-stock history (get_stock_prices), stock screening (screeners), strategy backtests with entry/exit rules (not yet available). Errors: unknown/ambiguous symbol -> candidates list; US asset -> not-supported error (licensing); KR data before 2020 -> source-limit hint; <60 overlapping trading days -> range too short. Notes: Simulation on historical data — not investment advice. Commission, one-way slippage and sell-side tax ARE deducted on the initial purchase and every rebalance (set costs=false for a gross view); dividends on KR stocks and all ETFs are not. KR stocks are price-return only (no distributions). US stocks are total-return where SEC-reported dividends exist (see dividend_adjusted per asset; ex-dates are approximated by fiscal-quarter end), otherwise price-return. ⚠ETFs are price-return only in every market right now — distributions are not in the data, so bond, REIT and high-dividend ETFs are understated. ⚠US ETF bars are also NOT split-adjusted — splits-us reads a SEC XBRL ratio that 1940-Act funds never file (2026-09-04 scan: 200 integer-ratio split events across 186 of 5,868 US ETFs, e.g. XLK/XLU 2:1 on 2025-12-05). This backtest refuses such a series rather than mispricing it, but tools that read the bars directly (get_stock_prices, get_technicals, screeners) still see the raw jump.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date YYYY-MM-DD (default: today) | |
| from | Yes | Start date YYYY-MM-DD | |
| costs | No | Deduct commission, slippage and sell-side tax on every rebalance (default true). Set false for a gross-return view. | |
| label | No | Name this run so you can find it again with get_backtest_runs (the run is saved either way). | |
| assets | Yes | Portfolio assets with weights | |
| initial | No | Starting value in the report currency (default 10000) | |
| currency | No | Reporting currency (default USD) | USD |
| benchmark | No | Benchmark symbol from the benchmarks table (KOSPI, KOSPI200, SPY, VTI, EW_KR, EW_US, EW_TW), 'auto' for the dominant market's default, or 'none'. | auto |
| rebalance | No | Rebalancing frequency (default yearly) | yearly |
| slippage_bps | No | One-way slippage in basis points (default 5). An assumption — we hold no quote data. | |
| response_format | No | 'markdown' for tables, 'json' for compact machine-readable output | markdown |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| assets | Yes | ||
| period | Yes | ||
| initial | No | ||
| metrics | Yes | ||
| currency | No | ||
| benchmark | No | ||
| rebalance | No | ||
| final_value | No | ||
| equity_curve | No | ||
| annual_returns | Yes |