Alpaca Options Credit-Spread Agent
Submission for lablab.ai's Alpaca AI Trading Agents Hackathon
(28 Aug – 4 Sep 2026).
Team rookieriot: Alex (@Alejdro83), Guillaume (@massemolle), [third teammate].
Decision log with evidence for every architecture choice: PLAN.md · failure-mode checklist: PREMORTEM.md.
An autonomous agent that trades credit vertical spreads on liquid index
ETFs (default SPY/QQQ/IWM): a bull put when swing signals are long, a bear
call when short — neutrals are rejected. Defined-risk from open, sized and
gated by explicit quantity-aware rules the LLM cannot override. Judged as a
constrained-agent experiment with a live mechanical/random ablation, not
as proven LLM alpha.
Live dashboard: https://alpaca-agent-dashboard.vercel.app (also opens
as a Telegram Mini App via @Alpaca_alejdro_bot — same page, same code, either way).
Why this design
- Screening/signals: vendored, unmodified, from a real trading system
(
trading_bot/ on the author's own infrastructure — 400+ live paper
trading cycles before this hackathon existed) — day/swing multi-horizon
signal generation, EMA50/200 + ADX trend filtering, liquid-universe
filters. This project reuses its underlying selection logic and
translates the resulting direction into an options structure instead of
an equity order.
- Options execution — 100% via Alpaca's official MCP
server (
mcp_client.py,
spread_builder.py, executor_mcp.py) — every chain lookup, quote, and
order placement goes through MCP tool calls, never the raw SDK.
- Delta computed in-process, not broker-supplied (
black_scholes.py)
— verified live against the real account that real-time OPRA options
data (needed for Alpaca's own Greeks) requires a paid Algo Trader Plus
subscription; the free/paper indicative feed returns quotes with no
Greeks at all. Rather than degrade to picking strikes by a fixed dollar
distance, delta is computed with a standard closed-form Black-Scholes
formula, using the same realized-volatility estimate the entry filter
already computes as the implied-vol proxy — labeled as a proxy
throughout, not overclaiming real IV.
- Risk gates (
risk_gate.py, pretrade_gate.py, sizing.py,
reconciler.py) — quantity-aware max-loss / BP / concentration checks,
missing quote timestamps fail closed, broker↔DB reconciliation blocks
entries on mismatch, bounded limit orders with idempotent client IDs and
pending→filled tracking.
- Autonomous decision layer (
llm_reasoner.py) — among whatever
survives the gate, an LLM picks which spread(s) to open; hard-capped to
remaining budget. Same immutable menu feeds mechanical + random shadows
(selector.py, shadow_book.py).
- Deployment:
run_options_cron.sh (flock + non-zero exit on failure)
every ~30min during market hours.
- Dashboard: Next.js app (Telegram Mini App capable) — equity curve,
spreads, cycle reasoning, ablation with abstention / gate-block / slippage
meta.
- Go-live: keep
DRY_RUN=true until the Monday rehearsal in
docs/runbooks/monday.md passes; default
MAX_CONTRACTS_PER_SPREAD=1.
The full trading cycle, end to end
Two instances run this codebase (team decision D18): Alex/Will's (dashboard above)
and Guillaume's (https://alpaca-trading-rookieriot.vercel.app — same Telegram Mini
App pattern). Each instance's .env sets its own account, universe and knobs.
Every 30 minutes during US market hours (cron, Mon–Fri), one cycle:
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
