SEC EDGAR Filing Monitor

First-seen change-detection over the live SEC EDGAR filing stream. Give it a watchlist (CIKs and/or tickers) plus a form-type filter (8-K, 4, SC 13D/13G, S-1, 10-K/10-Q, 424B); each run emits one normalized record per newly-appeared accession, joined to issuer metadata (name, ticker, CIK, SIC, state) and classified for high-value events (new 13D/13G ownership stakes, Form 4 insider buys/sells, 8-K material events), with a new-since-last-run high-water-mark mode across scheduled runs.

Clean REST/JSON — no browser, no proxy, no login, no API key required. Data source: SEC EDGAR (U.S. federal, public domain, 17 U.S.C. §105).

This product uses data from the U.S. Securities and Exchange Commission's EDGAR system, but is not endorsed or certified by the SEC.

Status: scaffold (v0.1, in progress). This Actor is being built in slices; the runtime logic (src/edgar.js, src/filters.js, src/main.js) is landing incrementally. This README documents the intended product surface. See CHANGELOG.md for what's implemented so far.

---

What it does

For each run it resolves the watchlist (tickers → CIKs via SEC's company_tickers.json), queries the per-issuer submissions feed GET https://data.sec.gov/submissions/CIK##########.json (zero-padded 10-digit CIK) and the cross-issuer full-text search GET https://efts.sec.gov/LATEST/search-index?q=&forms=&startdt=&enddt=&from=&hits=, applies your form-type filter, keeps only accessions accepted after the last-run high-water-mark, dedupes on the accession number (adsh), and pushes one dataset item per filing.

• First-seen change-detection (the moat): farms bulk-download filings; this instead watches the live stream and emits each accession the first run it appears, normalized and issuer-joined.
• Watchlist + form filter: monitor specific CIKs/tickers and/or specific form families.
• Event classification: new 13D/13G stakes, Form 4 insider trades, 8-K material events.
• New-filing monitor: monitorNewOnly persists the max acceptance-datetime seen (in the Actor's key-value store) and, on the next scheduled run, emits only accessions accepted after it.

Inputs

Input	Type	Notes
ciks	string[]	CIKs to watch (any form; normalized to 10-digit). Empty = market-wide by form only
tickers	string[]	Tickers to watch, resolved to CIKs via company_tickers.json
forms	string[]	Form types (8-K, 4, SC 13D, S-1, 10-K…). Empty = all
since	string	startdt delta cursor (YYYY-MM-DD). Empty = recent trailing window
until	string	Optional enddt upper bound (YYYY-MM-DD). Empty = up to today
query	string	Optional full-text q (phrase in quotes). Empty = match all (q=*)
monitorNewOnly	boolean	Emit only accessions after the stored acceptance-datetime high-water-mark
maxResults	integer	Cap total filings returned (0 = no cap)
proxyConfiguration	object	Optional; the API is open and needs no proxy. Default: none

Output — one record per filing (intended shape)

{
  "adsh": "0001437749-12-001697",
  "cik": "0000320193",
  "issuerName": "Apple Inc.",
  "tickers": ["AAPL"],
  "form": "8-K",
  "rootForm": "8-K",
  "filingDate": "2026-07-09",
  "acceptanceDateTime": "2026-07-09T16:31:12.000Z",
  "primaryDocument": "aapl-20260709.htm",
  "primaryDocumentUrl": "https://www.sec.gov/Archives/edgar/data/320193/000143774912001697/aapl-20260709.htm",
  "periodOfReport": "2026-07-09",
  "sic": "3571",
  "sicDescription": "Electronic Computers",
  "stateOfIncorp": "CA",
  "bizState": "CA",
  "fileNumber": "001-36743",
  "eventType": "material-event",
  "isNew": true,
  "attribution": "This product uses data from the U.S. Securities and Exchange Commission's EDGAR system, but is not endorsed or certified by the SEC.",
  "fetchedAt": "2026-07-10T14:00:00.000Z"
}

adsh (accession number) is the dedupe key. cik is the zero-padded 10-digit issuer key. isNew is true when an accession was not seen in a previous run (only meaningful with monitorNewOnly). Every record carries the required SEC no-endorsement attribution string.

Control records (not charged)

Two non-filing records may be pushed to signal run state. Neither triggers a filing-returned charge:

Record	When	Shape
_noData	No filings matched the watchlist/form/window	{ "_noData": true, "filters": {...}, "message": "...", "fetchedAt": "..." }
_error	The fetch failed after retries, or normalization threw	{ "_error": true, "filters": {...}, "message": "...", "fetchedAt": "..." }

_noData keeps a zero-result run green and auditable rather than pushing a silent empty dataset.

Pricing (pay-per-event)

One filing-returned event is charged per filing record pushed to the dataset. Cost scales with results, not runtime. Use ciks / tickers / forms / maxResults / monitorNewOnly to keep spend proportional to signal. (Live price shown on the Store page; see docs/PRICING.md, lands in a later slice.)

Data source & attribution

SEC EDGAR data is U.S.-government public domain (17 U.S.C. §105). Per SEC's Website Dissemination policy: "Information presented on sec.gov is considered public information and may be copied or further distributed by users of the web site without the SEC's permission." No API key is required. This Actor surfaces a no-endorsement attribution string on every record and in the listing: "This product uses data from the U.S. Securities and Exchange Commission's EDGAR system, but is not endorsed or certified by the SEC." Full compliance record: COMPLIANCE.md (lands in a later slice).

EDGAR relays filer-submitted data; filings may be corrected, amended, or refiled. This Actor relays the data as published; it does not certify accuracy.

Maintenance notes (scaffold — carried into the API layer, slice 2)

• Mandatory descriptive User-Agent. SEC fair-access requires a declared UA on every request; undeclared tools get an "Undeclared Automated Tool" error. Wire this exact constant into the API layer (src/edgar.js): ByteHaven Studios EDGAR Monitor developer@bytehavenstudios.com
• Rate limit — stay under SEC's 10 requests/second fair-access ceiling; throttle + back off on 403/429.
• Zero-pad CIK to 10 digits for data.sec.gov/submissions/CIK##########.json.
• EFTS coverage/cap — full-text search covers 2001-present only and returns ≤10,000 hits per query; window/paginate by date (startdt/enddt, from/hits) to stay under it.
• Form taxonomy drift — match on both form and root_forms; new form variants appear.
• Ticker map refresh — re-fetch company_tickers.json periodically for new listings/renames.
• Trademark caveat — text reference to "EDGAR" is fine, but do NOT use the SEC seal or EDGAR marks in the product NAME/branding.
• /cgi-bin is robots-disallowed — never use browse-edgar/getcurrent; the JSON hosts (data.sec.gov, efts.sec.gov) and /Archives/edgar/, /files/ are the sanctioned paths.