Insider Flow

insider-flow

You hand over a ticker. The skill pulls every Form 4 filed against the issuer over the lookback window, classifies each transaction, separates the signal (open-market buys, non-scheduled sales) from the noise (grants, option exercises, 10b5-1 scheduled sales), detects cluster buys, and emits a sentiment label backed by the underlying dollar flow.

The point is to answer the question a PM actually asks: are insiders buying or selling this name, and does it matter? The default read ignores 10b5-1 sales (pre-committed months in advance) and comp-related grants because they carry no signal about what management thinks of the current price.

When to invoke

• A PM asks "any insider activity on NVDA in the last 6 months?"
• A fundamental analyst wants a heads-up on the CEO's stock transactions over a cycle
• Screening a watchlist for cluster buys as a bullish overlay on weakness
• The user says "insider flow", "Form 4 activity", "who's buying / selling", "insider signal"

Not for: real-time (Form 4 is filed within 2 business days, so this is days-fresh, not tick-fresh). Not for 13-F holdings (institutional ownership is a separate skill).

What you need

• A ticker (--ticker, required)
• MASSIVE_API_KEY exported in the environment
• Stocks Basic plan minimum. The /stocks/filings/vX/form-4 endpoint is included on every Stocks plan.

Optional:

• --lookback-days (default 180): calendar-day window back from today.
• --exclude-directors: drop pure-director rows (is_director AND NOT is_officer AND NOT is_ten_percent_owner). Useful for names with VC or PE board reps unwinding a fund position, which structurally look bearish but carry no operator signal. Executives who also sit on the board are kept (they carry operator signal).

What you get back

Two output layers from one run.

Layer 1: canonical JSON matching output-schema.json. Top-level summary (sentiment label + reasoning, conviction buy / discretionary sale / scheduled sale / routine comp counts and dollars, net conviction flow), clusters[] (detected 14-day cluster buy windows sorted by dollar volume), notable_buys[] (top 5 open-market buys by dollar), notable_sales[] (top 5 discretionary sales), by_role (aggregate flow keyed on officer / director / 10% owner).

Layer 2: rendered note. Sentiment label at the top, transaction- flow block, cluster buys (when detected), notable individual transactions, by-role aggregation, one-line Take. See references/rendering.md.

How it works

1. Pull Form 4 rows via GET /stocks/filings/vX/form-4?tickers={T}&filing_date.gte={from_date}&limit=1000&sort=filing_date.desc. Massive returns one row per transaction leg (a single Form 4 filing can have multiple non-derivative + derivative legs).
2. Classify each row by SEC transaction code + Rule 10b5-1 status. See references/transaction-codes.md for the full mapping:
   • conviction_buy: code P (open-market purchase, non-derivative)
   • discretionary_sale: code S with aff_10b5_one=false
   • scheduled_sale: code S with aff_10b5_one=true
   • routine_comp: codes A (grant), M (derivative exercise), F (tax withholding)
   • non_informative: everything else (gifts, expiries, swaps)
3. Detect cluster buys. Rolling 14-day windows where >= 2 distinct insiders made open-market purchases (code P) summing to >= $100k. One entry per detected cluster.
4. Aggregate by role. Officer / director / 10% owner net flow. Officers dominate signal typically; 10% owners can be activists or founders with idiosyncratic reasons.
5. Emit sentiment on the net conviction flow (buys minus discretionary sales, 10b5-1 sales excluded). Buckets:
   • strong_bullish: cluster detected + positive net, or net > $250k
   • bullish: net > $50k
   • neutral: between -$250k and +$50k
   • bearish: net < -$250k
   • strong_bearish: net < -$1M

Foundations used

• massive-api-patterns for REST auth, retry, and pagination on the filings endpoint.

Output mode: note

Narrative note. Insider activity for a single name is a small number of rows (typically 50-300 in six months for an active name); a wide table would waste space. The rendered format optimizes for a PM reading the note once and either dismissing (no signal), noting a cluster buy, or noting a specific insider's discretionary sale.

Endpoints used

• GET /stocks/filings/vX/form-4?tickers={T}&filing_date.gte={D} Every Form 4 row for the ticker since D. Paginated; one call per page.

Doesn't handle (yet)

• Cross-ticker roll-up. A watchlist mode ("scan my 30 names for cluster buys this week") would compose this skill and aggregate. Queued.
• Base rate context. No per-name "typical monthly volume of discretionary sales" percentile. A $2M sale is different for JPM than for MU. Queued.
• Price context. No overlay of transaction date vs price. Insider buys near 52-week lows are stronger signal; sales at highs are weaker signal. Queued as a chain with technical-briefing.
• 10b5-1 plan adoption date. The endpoint returns aff_10b5_one as a boolean but not when the plan was adopted. Plans adopted right before a material corporate event are themselves a red flag; that data is in footnotes but requires text parsing.
• 13-D / 13-G triggers. Not covered; those are institutional filings on a different form.

These are clean PR extensions. The output schema is forward-compatible.