portfolio / wire operation
Analyze a portfolio (snapshot, timeline, monitor)
totalfinance.portfolio.analyze
One report of up to three direct results: the valuation snapshot at `asOf` (always), the dated timeline with P&L since each prior mark and drawdown (when `marks` are supplied), and the policy monitor with its alerts and carried state (when `monitor` is supplied). Each result is the direct function verbatim; nothing is aggregated across them, and one `assumptions` says which parts ran and why the others did not.
| Pack / profiles | portfolio / full, portfolio |
|---|---|
| Default discovery | Opt-in |
| Required capabilities | None |
| Effects / authorization | none / none |
| Cost / cancellation | medium / Do not assume inline interruption |
| Handle-eligible inputs | ledger, market |
| Idempotency | not-applicable |
Input schema
{
"type": "object",
"properties": {
"ledger": {
"type": "object",
"properties": {
"kind": {
"const": "totalfinance.portfolio-ledger",
"type": "string"
},
"schemaVersion": {
"type": "integer"
},
"portfolioId": {
"type": "string"
},
"baseCurrency": {
"type": "string"
},
"lotRelief": {
"type": "string",
"enum": [
"fifo",
"lifo",
"highest-cost",
"specific-lot"
]
},
"events": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "Portfolio event envelopes (each re-validated by readPortfolioLedgerSnapshot)"
},
"provenance": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"dataset": {
"type": "string"
},
"asOf": {
"type": "number"
},
"receivedAt": {
"type": "number"
},
"sourceVersion": {
"type": "string"
},
"requestId": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"required": [
"kind",
"schemaVersion",
"baseCurrency",
"lotRelief",
"events"
],
"description": "A serialized portfolio ledger (totalfinance.portfolio-ledger, the FC7 JSON form)"
},
"asOf": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "The valuation and monitoring instant"
},
"market": {
"type": "object",
"properties": {
"kind": {
"const": "totalfinance.market-snapshot",
"type": "string"
},
"schemaVersion": {
"type": "integer"
},
"asOf": {
"type": "number",
"description": "Epoch ms (resolved on the artifact)"
},
"conventions": {
"type": "object",
"properties": {
"conventionsVersion": {
"type": "string"
},
"asOfConvention": {
"type": "string",
"enum": [
"explicit-instant",
"date-midnight-utc"
],
"description": "How asOf was expressed at create time (a bare date is refused by option pricing)"
},
"dayCount": {
"type": "string"
},
"compounding": {
"type": "string"
},
"calendar": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"conventionsVersion",
"asOfConvention"
]
},
"observations": {
"type": "object",
"properties": {
"spots": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"riskFreeRates": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"dividendYields": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"volatilities": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"curves": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"surfaces": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"chains": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
}
},
"additionalProperties": false
},
"provenance": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"dataset": {
"type": "string"
},
"asOf": {
"type": "number"
},
"receivedAt": {
"type": "number"
},
"sourceVersion": {
"type": "string"
},
"requestId": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"required": [
"kind",
"schemaVersion",
"asOf",
"conventions",
"observations"
],
"description": "A Gate B market snapshot (totalfinance.market-snapshot); its interior is re-validated by the read door"
},
"currencyConversions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"baseCurrency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quoteCurrency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quotePerBase": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"baseCurrency",
"quoteCurrency",
"quotePerBase"
]
}
},
"instrumentClassification": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"underlying": {
"type": "string"
},
"assetClass": {
"type": "string"
},
"strategy": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"description": "Identity metadata per instrument for grouping; unknown instruments group as unclassified"
},
"marks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"valuationDate": {
"type": "string",
"format": "date",
"description": "Strict YYYY-MM-DD; the mark instant is 00:00 UTC"
},
"market": {
"type": "object",
"properties": {
"kind": {
"const": "totalfinance.market-snapshot",
"type": "string"
},
"schemaVersion": {
"type": "integer"
},
"asOf": {
"type": "number",
"description": "Epoch ms (resolved on the artifact)"
},
"conventions": {
"type": "object",
"properties": {
"conventionsVersion": {
"type": "string"
},
"asOfConvention": {
"type": "string",
"enum": [
"explicit-instant",
"date-midnight-utc"
],
"description": "How asOf was expressed at create time (a bare date is refused by option pricing)"
},
"dayCount": {
"type": "string"
},
"compounding": {
"type": "string"
},
"calendar": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"conventionsVersion",
"asOfConvention"
]
},
"observations": {
"type": "object",
"properties": {
"spots": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"riskFreeRates": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"dividendYields": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"volatilities": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"curves": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"surfaces": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"chains": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
}
},
"additionalProperties": false
},
"provenance": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"dataset": {
"type": "string"
},
"asOf": {
"type": "number"
},
"receivedAt": {
"type": "number"
},
"sourceVersion": {
"type": "string"
},
"requestId": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"required": [
"kind",
"schemaVersion",
"asOf",
"conventions",
"observations"
],
"description": "A Gate B market snapshot (totalfinance.market-snapshot); its interior is re-validated by the read door"
},
"currencyConversions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"baseCurrency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quoteCurrency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quotePerBase": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"baseCurrency",
"quoteCurrency",
"quotePerBase"
]
}
}
},
"additionalProperties": false,
"required": [
"valuationDate",
"market"
]
},
"minItems": 2,
"description": "At least two dated marks, strictly ascending — adds portfolioTimeline when supplied"
},
"monitor": {
"type": "object",
"properties": {
"policy": {
"type": "object",
"properties": {
"targets": {
"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"
]
}
},
"model": {
"type": "object",
"additionalProperties": {},
"description": "A model portfolio envelope (totalfinance.model-portfolio), validated by the policy grammar"
},
"withinGroupAllocation": {
"type": "string",
"enum": [
"proportional-to-current",
"equal"
]
},
"driftBand": {
"type": "number"
},
"reviewCadenceDays": {
"type": "number"
},
"maximumTurnover": {
"type": "number"
},
"maximumEstimatedTransactionCost": {
"type": "number"
},
"minimumCash": {
"type": "number"
},
"minimumCashWeight": {
"type": "number"
},
"limits": {
"type": "object",
"properties": {
"maximumPositionWeight": {
"type": "number"
},
"maximumGroupWeights": {
"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"
},
"maximumWeight": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"group",
"maximumWeight"
]
}
},
"maximumGrossLeverage": {
"type": "number"
},
"maximumDrawdown": {
"type": "number"
},
"maximumDailyLoss": {
"type": "number"
},
"maximumDaysToLiquidate": {
"type": "number"
},
"minimumSettledCash": {
"type": "number"
}
},
"additionalProperties": false
},
"allowedInstruments": {
"type": "array",
"items": {
"type": "string"
}
},
"restrictedInstruments": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedAccounts": {
"type": "array",
"items": {
"type": "string"
}
},
"benchmark": {
"type": "object",
"properties": {
"benchmarkId": {
"type": "string",
"minLength": 1
},
"asOf": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Epoch ms, YYYY-MM-DD, or a zoned ISO datetime"
},
"constituents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"instrumentId": {
"type": "string"
},
"weight": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"instrumentId",
"weight"
]
}
}
},
"additionalProperties": false,
"required": [
"benchmarkId"
]
},
"performanceObjective": {
"type": "string"
},
"contributionHandling": {
"type": "string",
"enum": [
"invest-to-targets",
"hold-as-cash"
]
},
"withdrawalHandling": {
"type": "string",
"enum": [
"raise-from-overweights",
"pro-rata"
]
},
"incomeReinvestment": {
"type": "string",
"enum": [
"reinvest",
"hold-as-cash"
]
},
"lotSelectionObjective": {
"type": "string"
}
},
"additionalProperties": false
},
"previousState": {
"anyOf": [
{
"type": "object",
"properties": {
"schemaVersion": {
"type": "integer"
},
"asOf": {
"type": "number"
},
"netAssetValue": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"peakNetAssetValue": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"evaluationCount": {
"type": "integer",
"minimum": 0
},
"rules": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"active": {
"type": "boolean"
},
"consecutiveBreaches": {
"type": "integer",
"minimum": 0
},
"lastRaisedAtMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"acknowledged": {
"type": "boolean"
},
"lastValue": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"active",
"consecutiveBreaches",
"lastRaisedAtMs",
"acknowledged",
"lastValue"
]
}
}
},
"additionalProperties": false,
"required": [
"schemaVersion",
"asOf",
"netAssetValue",
"peakNetAssetValue",
"evaluationCount",
"rules"
]
},
{
"type": "null"
}
],
"description": "The prior evaluation's state, or null for the first evaluation — required, exactly as monitorPortfolio requires it"
},
"rules": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"threshold": {
"type": "number"
},
"direction": {
"type": "string",
"enum": [
"above",
"below"
]
},
"hysteresis": {
"type": "object",
"properties": {
"enter": {
"type": "number"
},
"exit": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"enter",
"exit"
]
},
"debounceEvaluations": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Default 1"
},
"cooldownMs": {
"type": "number",
"minimum": 0,
"description": "Default 0"
},
"severity": {
"type": "string",
"enum": [
"informational",
"warning",
"critical"
]
}
},
"additionalProperties": false
},
"description": "Per alert family"
},
"acknowledgments": {
"type": "array",
"items": {
"type": "string"
}
},
"averageDailyVolumes": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"marketStalenessLimitMs": {
"type": "number"
},
"unusualPnlThreshold": {
"type": "number"
},
"residualTolerance": {
"type": "number"
},
"optionExpirationWarningDays": {
"type": "number"
},
"assignmentRiskMoneyness": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"policy",
"previousState"
],
"description": "monitorPortfolio inputs beyond the shared portfolio / market / asOf / currencyConversions"
}
},
"additionalProperties": false,
"required": [
"ledger",
"asOf",
"market"
]
}Output schema
{
"type": "object",
"properties": {
"snapshot": {
"type": "object",
"description": "portfolioSnapshot(...) verbatim"
},
"timeline": {
"type": [
"object",
"null"
],
"description": "portfolioTimeline(...) verbatim, or null when no marks were supplied"
},
"monitor": {
"type": [
"object",
"null"
],
"description": "monitorPortfolio(...) verbatim, or null when no monitor request was supplied"
},
"assumptions": {
"type": "object",
"description": "Applied conventions"
},
"diagnostics": {
"type": "object",
"description": "Engine, method, warnings"
}
},
"required": [
"snapshot",
"timeline",
"monitor",
"assumptions",
"diagnostics"
]
}