Catalyst Calendar — earnings, IPO & lockup-expiry dates with provenance

A US-equity catalyst calendar built for AI agents and quant workflows: upcoming earnings dates, recent IPOs, and computed lockup-expiry dates — parsed from the actual SEC prospectus clause, not assumed. Every row cites its primary source and carries a deterministic version stamp.

No API keys to manage: run it on Apify, pay per event returned. Works with agent stacks out of the box (MCP tool discovery, x402 agentic payments via Apify's integration).

What one event looks like

{
  "symbol": "SGP",
  "event_type": "lockup_expiry",
  "event_date": "2026-08-06",
  "status": "confirmed",
  "detail": {
    "ipo_date": "2026-02-06",
    "lockup_days": 181,
    "lockup_basis": "parsed",
    "evidence": "…beginning 181 days after the date of this prospectus, subject to the terms of the lock-up and market standoff agreements…",
    "spac": false
  },
  "provenance": {
    "sources": ["https://www.sec.gov/Archives/edgar/data/1778922/000162828026006068/spyglass-424b4.htm"],
    "first_seen": "2026-07-09T20:02:11+00:00",
    "last_verified": "2026-07-09T20:02:11+00:00",
    "model_version": "catalyst-v0.3.0-p2",
    "inputs_hash": "9c1a4f0e2b7d6a31"
  }
}

Yes — that lockup is 181 days, not 180, because that's what the filing says. Blind 180-day assumptions ship wrong dates; this Actor reads the clause and shows you the evidence.

Why this calendar

• Provenance on every row — the SEC filing URL, seen/verified timestamps, model version, and a deterministic input hash. Auditable by machine.
• Parsed lockup terms — expiry computed from the prospectus lock-up clause (with the quoted evidence). Unparseable clauses fall back to 180 days and are labeled estimated / assumed — never passed off as fact.
• Honest earnings estimates — next expected earnings date from each company's own 8-K reporting cadence, always status: estimated, with the sample size and interval spread included so you can judge the confidence.
• Measured accuracy, published — hold-out backtest on 30 large caps: median error 2 days, 90% within ±7 days, 12/30 exact. Lockup terms: 75% parsed directly from prospectuses. These numbers will be re-published monthly.
• SPACs tagged — blank-check IPOs are flagged (detail.spac) so you can filter them.
• Primary sources only — SEC EDGAR (public domain). No aggregator scraping, no licensing time-bombs in your pipeline.

Event types

type	what	status
earnings	Next expected earnings date per symbol (8-K item-2.02 cadence model)	estimated
ipo	IPO pricing events from 424(b)(4) filings, follow-on offerings excluded	confirmed
lockup_expiry	IPO date + parsed lock-up term	confirmed when parsed, estimated when assumed

Input

field	default	notes
symbols	(empty)	Empty = full universe: ~90 US large caps ∪ all recent IPOs. Pass tickers to target.
event_types	all	Any of earnings, ipo, lockup_expiry
days_ahead	90	Horizon for upcoming events (past IPOs are kept — they anchor lockup rows)
include_estimated	true	false = confirmed rows only
next_event_only	false	One nearest event per symbol, with days_out — built for position-holding agents
changed_since	—	Delta mode (ISO timestamp). Note: until the event-history store ships, each run is a fresh fetch and past cutoffs return all current rows

Typical costs (pay per event, $0.002/event)

• Full default pull (~550 events): ≈ $1.15
• One symbol, next_event_only: ≈ $0.01
• Targeted watchlist of 20 symbols: ≈ $0.05–0.15

Limitations (read this)

• Earnings dates are estimates until IR-confirmed sources ship (roadmap): cadence models miss when companies move reporting weeks (worst backtest case: 16 days). The interval_spread_days field tells you how regular each company's cadence is.
• US-listed equities only. Foreign private issuers (6-K filers) and ETFs get no earnings estimates. Recent IPOs need 3+ reported quarters first.
• ~Half of recent 424(b)(4) IPOs are SPACs — filter with detail.spac.
• Not investment advice. This is calendar structure — dates and provenance — not signals or recommendations.

Roadmap

Lockup early-release detection (8-K/S-3 waiver monitoring), IR-confirmed earnings dates, macro release calendar, true changed_since deltas backed by an event-history store, monthly accuracy self-reports in this README.

---

Development

Monorepo: actors/catalyst-calendar/ in agent-market-api. src/events.py, src/earnings.py, src/lockup.py are pure compute (no SDK, no I/O); src/sources/edgar.py is the only network layer (throttled ≤4 req/s, bounded 5xx retry, fail-open per chunk). Requires EDGAR_USER_AGENT env var (descriptive UA with contact email — SEC fair-access policy).

pytest                                        # unit tests, no network
python -m scripts.validate_earnings_cadence   # accuracy backtest (network)
apify run --purge                             # local run