strategy / wire operation
Analyze an options strategy
totalfinance.strategy.analyze
Build a multi-leg options position from its legs and return breakevens, net debit/credit, max profit, and max loss. Legs may be given without premiums: pass `premiums: "model"` with a `market` snapshot (spot, volatility, riskFreeRate, asOf, expiry) and every unpriced leg is priced by the BSM engine — so an iron condor’s P&L and probability-of-profit come from strikes alone. Set `probability: true` (with `market`) to also get probability-of-profit, expected value, risk/reward, and probability-of-touch. `premiumSource` reports whether premiums were user- or model-supplied.
| Pack / profiles | strategy / default, full, strategies |
|---|---|
| Default discovery | Included |
| Required capabilities | None |
| Effects / authorization | none / none |
| Cost / cancellation | small / Do not assume inline interruption |
| Handle-eligible inputs | None |
| Idempotency | not-applicable |
Input schema
{
"type": "object",
"properties": {
"legs": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "stock",
"type": "string"
},
"quantity": {
"type": "number",
"description": "Signed shares: positive = long, negative = short"
},
"price": {
"type": "number",
"description": "Entry price per share; omit to model-price the leg at `market.spot`"
}
},
"additionalProperties": false,
"required": [
"kind",
"quantity"
]
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"call",
"put"
]
},
"strike": {
"type": "number",
"exclusiveMinimum": 0
},
"quantity": {
"type": "number",
"description": "Signed contracts: positive = long, negative = short"
},
"premium": {
"type": "number",
"description": "Entry premium per share; omit to model-price the leg from `market`"
},
"expiry": {
"type": "string",
"description": "Per-leg expiry (YYYY-MM-DD or datetime) for calendars/diagonals"
},
"impliedVolatility": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Per-leg implied volatility (decimal)"
}
},
"additionalProperties": false,
"required": [
"kind",
"strike",
"quantity"
]
}
]
},
"description": "The option/stock legs of the position — supply legs OR strategy+input"
},
"strategy": {
"type": "string",
"description": "A named builder from totalfinance.strategy.list (e.g. ironCondor); pair with `input`"
},
"input": {
"type": "object",
"additionalProperties": {},
"description": "The named builder's input (shape per totalfinance.strategy.list examples)"
},
"premiums": {
"type": "string",
"enum": [
"user",
"model"
],
"description": "Entry-premium source: 'user' (from the leg premiums, default) or 'model' (price unpriced legs from `market`)"
},
"market": {
"type": "object",
"properties": {
"spot": {
"type": "number",
"exclusiveMinimum": 0
},
"volatility": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Annualized implied volatility (decimal, e.g. 0.18)"
},
"riskFreeRate": {
"type": "number",
"description": "Continuously-compounded risk-free rate (decimal)"
},
"asOf": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Entry/valuation instant — epoch ms or a zoned ISO datetime (a bare date is refused)"
},
"expiry": {
"type": "string",
"description": "Default expiry for legs without their own (YYYY-MM-DD → the US close, 16:00 ET or 13:00 ET on early-close days; or a zoned datetime)"
},
"dividendYield": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"spot",
"volatility",
"riskFreeRate",
"asOf"
],
"description": "Market snapshot; required for `premiums: model` and for `probability`"
},
"probability": {
"type": "boolean",
"description": "Also compute probability-of-profit, expected value, risk/reward, and probability-of-touch (needs `market`)"
},
"multiplier": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Contract multiplier for option legs (default 100)"
}
},
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"premiumSource": {
"type": "string",
"enum": [
"user",
"model"
]
},
"classification": {
"type": "array",
"items": {
"type": "string"
},
"description": "Named strategies these legs structurally match (derived via classifyStrategy; empty = custom)"
},
"metrics": {
"type": "object",
"properties": {
"netDebit": {
"type": "number"
},
"netCredit": {
"type": "number"
},
"maxProfit": {
"type": [
"number",
"null"
],
"description": "Maximum profit at expiration; null when unbounded (see bounded.profit)"
},
"maxLoss": {
"type": [
"number",
"null"
],
"description": "Maximum loss at expiration (negative); null when unbounded (see bounded.loss)"
},
"bounded": {
"type": "object",
"properties": {
"profit": {
"type": "boolean"
},
"loss": {
"type": "boolean"
}
},
"required": [
"profit",
"loss"
]
},
"breakevens": {
"type": "array",
"items": {
"type": "number"
}
}
},
"required": [
"netDebit",
"netCredit",
"maxProfit",
"maxLoss",
"bounded",
"breakevens"
]
},
"legs": {
"type": "array",
"items": {
"type": "object"
}
},
"assumptions": {
"type": "object",
"description": "Position-construction assumptions (premium source, multiplier, provenance)"
},
"diagnostics": {
"type": "object",
"description": "Warnings from the metric/probability computations (empty array when none)"
},
"probability": {
"type": "object",
"description": "Present when `probability: true` was supplied (requires `market`)",
"properties": {
"probabilityOfProfit": {
"type": "number"
},
"expectedValue": {
"type": "number"
},
"riskReward": {
"type": [
"number",
"null"
],
"description": "|maxProfit / maxLoss|; null when undefined (an unbounded side or a zero max loss) — see diagnostics"
},
"probabilityOfTouch": {
"type": "array"
},
"model": {
"type": "object"
},
"assumptions": {
"type": "object",
"description": "Probability-model conventions, including `marketSource` (construction | call | merged)"
}
}
}
},
"required": [
"premiumSource",
"metrics",
"legs",
"classification",
"assumptions",
"diagnostics"
]
}