backtest / wire operation
Run a portfolio backtest
totalfinance.backtest.portfolio_run
Backtest a multi-asset portfolio through the ledger: instruments with built-in adapters (equity, etf, option, future, fx-forward, crypto-spot, crypto-perpetual, bond), market data by row set, a model or inline targets on a rebalance schedule, an execution policy with settlement lags, external flows, a calendar, and the margin check with forced liquidation. Every fill, flow, lifecycle fact, and liquidation is a portfolio event; the equity is the ledger's net asset value. The result is portfolioBacktest(...) verbatim. Opt-in (backtestPack): payloads and runtime are heavier than the default set; bulk row sets above the row cap travel by handle.
| Pack / profiles | backtest / backtesting, full |
|---|---|
| Default discovery | Opt-in |
| Required capabilities | None |
| Effects / authorization | none / none |
| Cost / cancellation | job / Do not assume inline interruption |
| Handle-eligible inputs | marketData |
| Idempotency | not-applicable |
Input schema
{
"type": "object",
"properties": {
"accounting": {
"type": "object",
"properties": {
"baseCurrency": {
"type": "string",
"minLength": 1
},
"initialCash": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"minLength": 1
},
"amount": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"currency",
"amount"
]
},
"minItems": 1
},
"lotRelief": {
"type": "string",
"enum": [
"fifo",
"lifo",
"highest-cost",
"specific-lot"
]
},
"settlement": {
"type": "object",
"additionalProperties": {
"type": "string",
"enum": [
"T+0",
"T+1",
"T+2"
]
}
}
},
"additionalProperties": false,
"required": [
"baseCurrency",
"initialCash"
]
},
"instruments": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"equity",
"etf",
"option",
"future",
"fx-forward",
"crypto-spot",
"crypto-perpetual",
"bond"
],
"description": "A built-in kind; 'custom' brings its own adapter and is SDK-only"
},
"currency": {
"type": "string",
"minLength": 1
},
"contractMultiplier": {
"type": "number",
"exclusiveMinimum": 0
},
"contract": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "option",
"type": "string"
},
"underlyingInstrumentId": {
"type": "string",
"minLength": 1
},
"right": {
"type": "string",
"enum": [
"call",
"put"
]
},
"strikePricePerUnit": {
"type": "number",
"exclusiveMinimum": 0
},
"expiryTimestampMs": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"kind",
"underlyingInstrumentId",
"right",
"strikePricePerUnit",
"expiryTimestampMs"
]
},
{
"type": "object",
"properties": {
"kind": {
"const": "future",
"type": "string"
},
"underlyingInstrumentId": {
"type": "string",
"minLength": 1
},
"expiryTimestampMs": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"kind",
"underlyingInstrumentId",
"expiryTimestampMs"
]
},
{
"type": "object",
"properties": {
"kind": {
"const": "perpetual",
"type": "string"
},
"underlyingInstrumentId": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"kind",
"underlyingInstrumentId"
]
}
]
},
"assetClass": {
"type": "string",
"enum": [
"equity",
"etf",
"option",
"future",
"fx-forward",
"crypto-spot",
"crypto-perpetual",
"bond",
"cash"
]
},
"classification": {
"type": "object",
"properties": {
"underlying": {
"type": "string"
},
"assetClass": {
"type": "string"
},
"strategy": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"roll": {
"type": "object",
"properties": {
"toInstrumentId": {
"type": "string",
"minLength": 1
},
"sessionsBeforeExpiry": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"toInstrumentId",
"sessionsBeforeExpiry"
]
},
"coupon": {
"type": "object",
"properties": {
"annualRate": {
"type": "number"
},
"paymentsPerYear": {
"type": "integer",
"exclusiveMinimum": 0
},
"faceValuePerUnit": {
"type": "number",
"exclusiveMinimum": 0
},
"dayCount": {
"type": "string",
"enum": [
"ACT/365F",
"30/360"
]
},
"issueDate": {
"type": "string",
"format": "date"
},
"maturityDate": {
"type": "string",
"format": "date"
}
},
"additionalProperties": false,
"required": [
"annualRate",
"paymentsPerYear",
"issueDate",
"maturityDate"
]
},
"forward": {
"type": "object",
"properties": {
"maturityTimestampMs": {
"type": "number"
},
"baseCurrency": {
"type": "string",
"minLength": 1
},
"quoteCurrency": {
"type": "string",
"minLength": 1
},
"contractRate": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"maturityTimestampMs",
"baseCurrency",
"quoteCurrency",
"contractRate"
]
}
},
"additionalProperties": false,
"required": [
"kind",
"currency"
],
"description": "An instrument specification; the terms each kind needs are validated by the engine"
}
},
"marketData": {
"type": "object",
"properties": {
"bars": {
"type": "array",
"items": {
"type": "object",
"properties": {
"symbol": {
"type": "string",
"minLength": 1
},
"timestampMs": {
"type": "number"
},
"open": {
"type": "number"
},
"high": {
"type": "number"
},
"low": {
"type": "number"
},
"close": {
"type": "number"
},
"volume": {
"type": "number"
},
"vwap": {
"type": "number"
},
"adjusted": {
"type": "boolean"
}
},
"additionalProperties": false,
"required": [
"symbol",
"timestampMs",
"open",
"high",
"low",
"close"
]
}
},
"quotes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"symbol": {
"type": "string",
"minLength": 1
},
"timestampMs": {
"type": "number"
},
"bid": {
"type": "number"
},
"ask": {
"type": "number"
},
"bidSize": {
"type": "number"
},
"askSize": {
"type": "number"
},
"exchange": {
"type": "string"
},
"conditions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"symbol",
"timestampMs",
"bid",
"ask"
]
}
},
"trades": {
"type": "array",
"items": {
"type": "object",
"properties": {
"symbol": {
"type": "string",
"minLength": 1
},
"timestampMs": {
"type": "number"
},
"price": {
"type": "number"
},
"size": {
"type": "number"
},
"exchange": {
"type": "string"
},
"conditions": {
"type": "array",
"items": {
"type": "string"
}
},
"sequence": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"symbol",
"timestampMs",
"price",
"size"
]
}
},
"orderBooks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"symbol": {
"type": "string",
"minLength": 1
},
"timestampMs": {
"type": "number"
},
"bids": {
"type": "array",
"items": {
"type": "object",
"properties": {
"price": {
"type": "number"
},
"size": {
"type": "number"
},
"exchange": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"price",
"size"
]
}
},
"asks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"price": {
"type": "number"
},
"size": {
"type": "number"
},
"exchange": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"price",
"size"
]
}
}
},
"additionalProperties": false,
"required": [
"symbol",
"timestampMs",
"bids",
"asks"
]
}
},
"optionChains": {
"type": "array",
"items": {
"type": "object",
"properties": {
"asOf": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Epoch ms, YYYY-MM-DD, or a zoned ISO datetime"
},
"underlyingPrice": {
"type": "number",
"exclusiveMinimum": 0
},
"quotes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"contract": {
"type": "object",
"properties": {
"underlying": {
"type": "string",
"minLength": 1
},
"type": {
"type": "string",
"enum": [
"call",
"put"
]
},
"style": {
"type": "string",
"enum": [
"european",
"american"
]
},
"strike": {
"type": "number",
"exclusiveMinimum": 0
},
"expiry": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}([Tt ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?([Zz]|[+-]\\d{2}:?\\d{2}))?$",
"description": "Display label: 'YYYY-MM-DD' or a zoned ISO datetime (matches the builders)"
},
"expiresAt": {
"type": "number",
"description": "Resolved expiration instant (epoch ms) — stamped by the builders"
},
"expiryConvention": {
"type": "string",
"enum": [
"us-equity-close",
"explicit-instant"
],
"description": "How the label resolved to the instant"
},
"multiplier": {
"type": "number",
"exclusiveMinimum": 0
},
"settlement": {
"type": "string",
"enum": [
"physical",
"cash"
]
},
"exerciseTime": {
"type": "string",
"enum": [
"AM",
"PM"
]
},
"currency": {
"type": "string"
},
"root": {
"type": "string"
},
"occSymbol": {
"type": "string"
},
"deliverable": {
"type": "object",
"properties": {
"cash": {
"type": "number"
},
"shares": {
"type": "array",
"items": {
"type": "object",
"properties": {
"symbol": {
"type": "string",
"minLength": 1
},
"quantity": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"symbol",
"quantity"
]
}
},
"notes": {
"type": "string"
}
},
"additionalProperties": false
},
"adjusted": {
"type": "boolean"
}
},
"additionalProperties": false,
"required": [
"underlying",
"type",
"style",
"strike",
"expiry",
"expiresAt",
"expiryConvention"
]
},
"timestampMs": {
"type": "number"
},
"bid": {
"type": "number"
},
"ask": {
"type": "number"
},
"bidSize": {
"type": "number",
"minimum": 0
},
"askSize": {
"type": "number",
"minimum": 0
},
"mid": {
"type": "number"
},
"last": {
"type": "number"
},
"mark": {
"type": "number"
},
"volume": {
"type": "number",
"minimum": 0
},
"openInterest": {
"type": "number",
"minimum": 0
},
"underlyingPrice": {
"type": "number",
"exclusiveMinimum": 0
},
"impliedVolatility": {
"type": "number",
"minimum": 0
},
"greeks": {
"type": "object",
"properties": {
"delta": {
"type": "number"
},
"gamma": {
"type": "number"
},
"theta": {
"type": "number"
},
"vega": {
"type": "number"
},
"rho": {
"type": "number"
},
"provenance": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"model": {
"type": "string"
},
"timestampMs": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"source"
]
}
},
"additionalProperties": false,
"required": [
"delta"
],
"description": "Per-share Greeks in display units (theta per day, vega per vol point, rho per 1%), with optional provenance"
},
"exchange": {
"type": "string"
},
"conditions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"contract",
"timestampMs"
]
}
}
},
"additionalProperties": false,
"required": [
"asOf",
"underlyingPrice",
"quotes"
]
}
},
"fxRates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestampMs": {
"type": "number"
},
"baseCurrency": {
"type": "string",
"minLength": 1
},
"quoteCurrency": {
"type": "string",
"minLength": 1
},
"quotePerBase": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"timestampMs",
"baseCurrency",
"quoteCurrency",
"quotePerBase"
]
}
},
"forwardRates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"instrumentId": {
"type": "string",
"minLength": 1
},
"timestampMs": {
"type": "number"
},
"forwardRate": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"instrumentId",
"timestampMs",
"forwardRate"
]
}
},
"fundingRates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"instrumentId": {
"type": "string",
"minLength": 1
},
"timestampMs": {
"type": "number"
},
"fundingRate": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"instrumentId",
"timestampMs",
"fundingRate"
]
}
},
"corporateActions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"symbol": {
"type": "string",
"minLength": 1
},
"effectiveDate": {
"type": "string",
"format": "date"
},
"type": {
"type": "string",
"enum": [
"split",
"reverseSplit",
"dividend",
"symbolChange",
"merger",
"spinoff",
"other"
]
},
"ratio": {
"type": "number",
"exclusiveMinimum": 0
},
"cash": {
"type": "number"
},
"newSymbol": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"additionalProperties": false,
"required": [
"symbol",
"effectiveDate",
"type"
]
}
},
"dividends": {
"type": "array",
"items": {
"type": "object",
"properties": {
"instrumentId": {
"type": "string",
"minLength": 1
},
"exDate": {
"type": "string",
"format": "date"
},
"amount": {
"type": "number",
"exclusiveMinimum": 0
},
"payDate": {
"type": "string",
"format": "date"
}
},
"additionalProperties": false,
"required": [
"instrumentId",
"exDate",
"amount"
]
}
},
"coupons": {
"type": "array",
"items": {
"type": "object",
"properties": {
"instrumentId": {
"type": "string",
"minLength": 1
},
"paymentDate": {
"type": "string",
"format": "date"
},
"amountPerUnit": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"instrumentId",
"paymentDate",
"amountPerUnit"
]
}
}
},
"additionalProperties": false
},
"strategy": {
"type": "object",
"properties": {
"model": {
"anyOf": [
{
"type": "object",
"additionalProperties": {},
"description": "A ModelPortfolio artifact"
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"group": {
"type": "object",
"properties": {
"instrumentId": {
"type": "string"
},
"sleeveId": {
"type": "string"
},
"assetClass": {
"type": "string"
},
"currency": {
"type": "string"
},
"tag": {
"type": "string"
},
"underlying": {
"type": "string"
},
"strategy": {
"type": "string"
}
},
"additionalProperties": false,
"description": "Exactly one group key"
},
"weight": {
"type": "number"
},
"riskBudget": {
"type": "number"
},
"driftBand": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"group"
]
},
"minItems": 1
}
]
},
"schedule": {
"type": "object",
"properties": {
"frequency": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly",
"quarterly"
]
}
},
"additionalProperties": false,
"required": [
"frequency"
]
},
"policy": {
"type": "object",
"additionalProperties": {},
"description": "An InvestmentPolicy (limits, handling); targets come from the model"
},
"scope": {
"type": "string",
"enum": [
"to-target",
"drift-only"
]
}
},
"additionalProperties": false,
"required": [
"model",
"schedule"
],
"description": "The declarative strategy; an onSession callback is SDK-only"
},
"execution": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1
},
"ambiguity": {
"type": "string",
"enum": [
"optimistic",
"pessimistic",
"deterministic-path",
"reject"
]
},
"costs": {
"type": "object",
"properties": {
"commission": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {
"const": "none",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"model"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "bps",
"type": "string"
},
"bps": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"bps"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "perShare",
"type": "string"
},
"amountPerShare": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"amountPerShare"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "fixed",
"type": "string"
},
"amount": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"amount"
]
}
],
"description": "A declarative commission model (fees.none / bps / perShare / fixed)"
},
"slippage": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {
"const": "none",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"model"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "bps",
"type": "string"
},
"bps": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"bps"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "fixed",
"type": "string"
},
"perShare": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"perShare"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "spread",
"type": "string"
},
"spread": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"spread"
]
}
],
"description": "A declarative slippage model (slippage.none / bps / fixed / spread)"
},
"spread": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {
"const": "none",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"model"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "halfSpreadBps",
"type": "string"
},
"bps": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"bps"
]
}
]
},
"marketImpact": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {
"const": "none",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"model"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "squareRoot",
"type": "string"
},
"coefficient": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"coefficient"
]
}
]
},
"latencySessions": {
"type": "integer",
"minimum": 0
},
"participation": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"partialFills": {
"type": "string",
"enum": [
"allow",
"reject"
]
},
"timeInForce": {
"type": "object",
"properties": {
"default": {
"type": "string",
"enum": [
"day",
"gtc"
]
},
"expireAtSessionClose": {
"type": "boolean"
}
},
"additionalProperties": false,
"required": [
"default",
"expireAtSessionClose"
]
},
"margin": {
"type": "object",
"properties": {
"buyingPowerMultiplier": {
"type": "number",
"exclusiveMinimum": 0
},
"initialMarginRate": {
"type": "number",
"minimum": 0
},
"maintenanceMarginRate": {
"type": "number",
"minimum": 0
},
"forcedLiquidation": {
"type": "string",
"enum": [
"none",
"close-largest-loss",
"pro-rata"
]
}
},
"additionalProperties": false,
"required": [
"buyingPowerMultiplier",
"initialMarginRate",
"maintenanceMarginRate",
"forcedLiquidation"
]
}
},
"additionalProperties": false,
"required": [
"label"
],
"description": "A declared execution policy over session bars (execution.declared): the label is the caller's claim; a caller fill model, session rules, and quote/order-book observations are SDK-only"
},
"externalFlows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestampMs": {
"type": "number"
},
"amount": {
"type": "number"
},
"currency": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"timestampMs",
"amount",
"currency"
]
}
},
"calendar": {
"type": "string",
"enum": [
"NYSE",
"CBOE",
"ALWAYS_OPEN"
]
},
"window": {
"type": "object",
"properties": {
"fromTimestampMs": {
"type": "number"
},
"toTimestampMs": {
"type": "number"
}
},
"additionalProperties": false
},
"periodsPerYear": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Default 252"
},
"seed": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"accounting",
"instruments",
"marketData",
"strategy"
]
}Output schema
{
"type": "object",
"properties": {
"ledger": {
"type": "object"
},
"timeline": {
"type": [
"object",
"null"
]
},
"pnl": {
"type": [
"object",
"null"
]
},
"orders": {
"type": "array",
"items": {
"type": "object"
}
},
"fills": {
"type": "array",
"items": {
"type": "object"
}
},
"rejections": {
"type": "array",
"items": {
"type": "object"
}
},
"liquidations": {
"type": "array",
"items": {
"type": "object"
}
},
"events": {
"type": "array",
"items": {
"type": "object"
}
},
"valuationMarks": {
"type": "array",
"items": {
"type": "object"
}
},
"points": {
"type": "array",
"items": {
"type": "object"
}
},
"returns": {
"type": "array",
"items": {
"type": "number"
}
},
"performance": {
"type": "object",
"description": "The standard performance summary"
},
"finalValue": {
"type": "number"
},
"runId": {
"type": "string"
},
"assumptions": {
"type": "object",
"description": "Applied conventions"
},
"diagnostics": {
"type": "object",
"description": "Engine, method, warnings"
}
},
"required": [
"ledger",
"timeline",
"pnl",
"orders",
"fills",
"rejections",
"liquidations",
"events",
"valuationMarks",
"points",
"returns",
"performance",
"finalValue",
"runId",
"assumptions",
"diagnostics"
]
}