Alpaca options: verify the venue reality before any commitment — agreement, cash-account support, multi-leg, assignment events

[eaitbrahim]

Options on Alpaca collide with keel's constitution by construction — and the decision (the ADR-0005 issue) must not be made from documentation alone. #412's lesson applies verbatim: Robinhood's order-object shapes were doc-only until one real order was observed. Discovery first, decision second, code never before both.

What must be verified on the venue, not in the docs

• Cash-account options: can an Alpaca cash account trade options at all, or does the options agreement imply the margin agreement? (keel enforces multiplier == 1 at broker build via CashAccountRequired — Cash-account posture: encode and document no-margin / PDT-adjacent constraints #372 — so this is the load-bearing question)
• Multi-leg order support in the Trading API: spreads as single orders, or leg-by-leg? (keel's port carries no multi-leg order kind today)
• Contract multiplier semantics: how the venue reports quantity/notional for multiplier-100 contracts, and where that would collide with the cash rail
• Exercise and assignment events: does the stream/webhook deliver assignments, what does an assignment do to a cash position, and can it arrive outside the trading session
• Cash-securedness enforcement: can the venue reject a naked leg on a cash account, or must keel enforce covered-call/cash-secured-put-only itself at order construction
• Expiry cadence interactions: expiry-week and PDT interactions for an hourly-cadence engine

Rules of engagement

• Discovery only. No code, no posture change, no config flag. Read-only API calls against a paper/options-enabled account are in scope; live trading is not.
• Findings land on this issue; the ADR-0005 issue consumes them.
• If any answer is "the venue cannot tell us," that itself is a finding, and it weights the decision toward holding the line at cash-spot.

[eaitbrahim]

Desk-research pass — doc-only, and it does not close this issue

Full artifact in #753 (docs/research/2026-09-07-alpaca-options-venue-reality.md).

This answers none of the checkboxes to this issue's own standard. No API call was made. Per the rules of engagement, every finding below is documentation, and the artifact marks each one [DOC] / [DOC-GAP] / [KEEL] / [ARITH].

Against the six boxes

#	question	status
1	cash-account options	[DOC-GAP] — undocumented, and it is the crux
2	multi-leg support	[DOC] answered: order_class: "mleg", 2–4 legs, POST /v2/orders, Level 3
3	multiplier semantics	[DOC] partly: whole-number qty, 100× contracts. Real quantity/notional reporting needs a call
4	exercise & assignment	[DOC] answered, and worse than assumed — see below
5	cash-securedness enforcement	[DOC] Level 1 validates "sufficient underlying shares" / "sufficient options buying power"; whether it refuses a naked leg is untested
6	expiry / PDT cadence	[DOC] partly; PDT position unchanged from verify_cash_account's docstring — the cadence is the safety, not the posture

The four things worth reading the artifact for

1. Box 1 cannot be answered from docs, and the downside is asymmetric. Alpaca offers no cash accounts at all — "All accounts are set up as margin accounts." keel already handles that with the multiplier == 1 proxy. Whether options approval survives max_margin_multiplier: 1 is stated nowhere. If enabling options moves the multiplier, verify_cash_account raises and the adapter stops building — breaking the equities trading that already ships. Options would then be a strictly destructive change.

2. Rail 19 already refuses an OCC symbol, and its own comment says spot-only is the charter. SPY250127C00608000 has no hyphen → parse_spot_product_id returns None. The rail runs in every mode, both sides, DCA included, deliberately outside LIVE_STATE_RAILS — so paper cannot skip it and there is no rehearsal path. keel could not paper-trade an option to gather evidence without amending the rail first. That is the amendment #637 is being asked to consider, and this sizes it: one rail, one grammar, one charter sentence.

3. The venue acts on inventory without keel. ITM auto-exercises at $0.01; where buying power is short, "Alpaca will sell-out the position within 1 hour before expiry." And assignment arrives by polling only — "Options assignments are not delivered through websocket events" — so it is also the first inventory event with no originating keel order. The port has no shape for that.

4. It is unexecutable at current size regardless of the fiqh. A cash-secured put is collateralised at strike × 100 and cannot be fractionalised — $1,800 for the cheapest plausible underlying, against config.live.yaml's budget_usd: 50. ~36×. This one needs no jurisprudence to decide.

On fees: the pass-through total is ~$0.084/contract round trip (4.6 bp of premium on a CSP open) — negligible, which is the trap. The real cost is the bid-ask spread and no document states it. Arguing the ADR from the fee schedule would repeat the error 2026-09-05-restatement-restated.md corrected for crypto.

What would actually close this

Paper accounts get Level 3 automatically ("there's nothing you need to do"), so boxes 2–5 are verifiable free, with no options agreement and nothing at stake. Box 4 needs a short option held to expiry ITM, so it has a calendar on it.

Box 1 is not among them — paper grants Level 3 to everyone, so it says nothing about a live account pinned at multiplier 1. That needs Alpaca support in writing, or a live application.

Recording per the rules of engagement: box 1 currently answers "the venue cannot tell us", which weights toward holding the line.