structure / wire operation
Classify options flow (sweeps / blocks / spreads)
totalfinance.structure.flow
Classify option prints into aggressor-side flow: sweeps (multi-print bursts, venue-verified when exchange codes are supplied), blocks, and multi-leg spreads. Aggressor side is NBBO-estimated (Lee–Ready style) — the honest caveats ride diagnostics.warnings as `model.limitation` entries (mirrored as `limitations` strings for quick reading); nothing is presented as exchange-confirmed unless it is.
| Pack / profiles | structure / default, full |
|---|---|
| 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": {
"trades": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestampMs": {
"type": "number",
"description": "Print timestamp (epoch ms)"
},
"type": {
"type": "string",
"enum": [
"call",
"put"
]
},
"strike": {
"type": "number",
"exclusiveMinimum": 0
},
"expiry": {
"type": "string",
"description": "ISO date YYYY-MM-DD"
},
"price": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Print price per share"
},
"size": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Print size (contracts)"
},
"bid": {
"type": "number",
"description": "NBBO bid at print time (enables aggressor-side classification)"
},
"ask": {
"type": "number",
"description": "NBBO ask at print time"
},
"exchange": {
"type": "string",
"description": "Venue code (enables venue-verified sweep detection)"
},
"openInterest": {
"type": "number",
"description": "Prior open interest (enables opening detection)"
}
},
"additionalProperties": false,
"required": [
"timestampMs",
"type",
"strike",
"expiry",
"price",
"size"
]
},
"description": "Option prints, any order (sorted internally)"
},
"underlying": {
"type": "string",
"description": "Ticker of the prints — REQUIRED, it names every contract"
},
"style": {
"type": "string",
"enum": [
"american",
"european"
],
"description": "Exercise style of the printed contracts — REQUIRED (listed US equity options are 'american'); the library never defaults it"
},
"multiplier": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Contract multiplier (default 100)"
},
"blockMinSize": {
"type": "number",
"description": "Min contracts for a block (default 100)"
},
"blockMinPremium": {
"type": "number",
"description": "Min premium $ for a block (default 100,000)"
},
"maxDetails": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Max sweeps/spreads returned in detail (default 25 each)"
}
},
"additionalProperties": false,
"required": [
"trades",
"underlying",
"style"
]
}Output schema
{
"type": "object",
"properties": {
"counts": {
"type": "object",
"description": "trades/sweeps/spreads/buy/sell/unknown totals"
},
"sweeps": {
"type": "array",
"description": "Detected sweeps (capped by maxDetails)"
},
"spreads": {
"type": "array",
"description": "Detected multi-leg spreads (capped)"
},
"assumptions": {
"type": "object",
"description": "The rules/windows the analysis ran under"
},
"diagnostics": {
"type": "object",
"description": "Warnings, including the heuristic caveats as `model.limitation` entries"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Convenience view: the `model.limitation` messages from diagnostics.warnings (diagnostics is the source of truth)"
}
},
"required": [
"counts",
"sweeps",
"spreads",
"assumptions",
"diagnostics",
"limitations"
]
}