# Insider API Stream — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 7c3baddf
> Fetch this file at: https://uat.finradarapi.com/llms/insider-api-stream.txt

## Authentication
All endpoints require an API key. Pass it via query parameter `?apiKey=YOUR_KEY` or header `X-API-Key: YOUR_KEY`. WebSocket endpoints accept the key in the `token` auth payload or query parameter.

---

## Insider API Stream

Real-time insider transaction feed.

### WS WebSocket (Path: /insider-module/socket.io)

Stream of parsed insider transactions and subscription management.

**Token cost:** 100 tokens per connection-day (flat rate; reconnects on the same UTC day are free)

**Response fields:**
- `event` (string): Event name — typically `"new_transaction"` for individual transactions or `"filing_processed"` for batched per-filing events. Use to dispatch handler functions client-side.
- `transaction_id` (integer): Stable internal primary key from `insiders_transactions`. Use as a deduplication key — the stream MAY replay the most-recent few minutes on reconnect.
- `ticker` (string): Issuer ticker (canonical hyphen form). Pre-filtered server-side against the `tickers` subscription filter when set — clients that subscribed to a watchlist will only receive matching tickers.
- `insider_name` (string): Reporting-person name as filed on Form 4 (typically all-caps EDGAR convention). Casing preserved verbatim; for stable identifiers use `insider_cik`.
- `insider_cik` (string): Reporting-person CIK in 10-character zero-padded form. The stable identifier for cross-event correlation (track all transactions by one insider).
- `standard_type` (string): Normalized transaction type — one of `purchase`, `sale`, `grant`, `exercise`, `gift`, `other`. The high-signal types for trading workflows are `purchase` and `sale`.
- `shares` (number): Share count for the transaction (split-adjusted). Always positive; direction encoded in `standard_type`.
- `price_per_share` (number (nullable)): Per-share transaction price in USD. Null for code-A grants and code-G gifts (no consideration). Pre-filtering by `min_value` excludes null-price events.
- `transaction_value` (number (nullable)): Computed `shares × price_per_share` in USD. Null when price is null. Pre-filtered server-side against the `min_value` subscription filter when set.
- `transaction_date` (string): ISO `YYYY-MM-DD` trade-execution date (NOT the filing date — Form 4 filing has 2-business-day window). For latency-critical workflows compare `transaction_date` against the event-receipt timestamp to gauge market reaction window.
- `sector` (string (nullable)): Sharadar sector classification. Null when ticker is unmapped in Sharadar. Use for client-side sector filtering on top of the server-side ticker filter.
- `industry` (string (nullable)): Sharadar industry classification (more specific than `sector`). Null when unmapped.

**Since:** v1.0.0

**Utility:** Real-time push stream of parsed insider transactions (Form 4 / 3 / 5) — receive each transaction within 30-60 seconds of EDGAR acceptance, AFTER our parser has extracted the structured fields (insider name, transaction type, shares, price). Server-side filtering supports `tickers` (whitelist), `min_value` (USD threshold), and `is_c_suite` (CEO/CFO/COO only) so high-value workflows like 'every CEO purchase > $1M' don't require client-side filtering of the firehose. The right choice for low-latency trading desks running event-driven insider-signal strategies — strictly faster than the daily-recommendations endpoint (which lags 24h) and the cluster endpoint (which lags 7 days). 100-token flat per-UTC-day connection fee — reconnects on same UTC day are free.

**Use case:** Monitoring CEO purchases > $1M in real-time.

**Parameters:**
- `api_key` (auth, required): API key. Three methods (first match): Socket.IO `auth.api_key` payload (recommended), HTTP header `X-API-Key` or `Authorization: Bearer`, or `?api_key=` query. Pair with `path: '/insider-module/socket.io'`. 100-token/day fee. `?token=` removed v3.20.2.
- `path` (config, required, default: /insider-module/socket.io): Custom Socket.IO HTTP path (different from the `/sec` and `/13f` streams which use the default path). Pass to your Socket.IO client constructor as `io(url, { path: '/insider-module/socket.io', auth: {...} })`. Failing to set this will return 404 on the upgrade request.
- `namespace` (config, required, default: /insider-module): Socket.IO namespace. Connect via `io('/insider-module', {...})`. Distinct from the path — namespace is a Socket.IO routing concept (selected via client API), path is the HTTP endpoint for upgrade.

**Events (server → client):**
- `filing_processed`: New Transaction. Payload: { ticker, insider_name, transaction_value, ... }
- `subscribed`: Confirmation of filter update.

**Actions (client → server):**
- `subscribe`: Filter stream.
  ```json
  {
    "tickers": [
      "AAPL",
      "TSLA"
    ],
    "min_value": 100000,
    "is_c_suite": true
  }
  ```

**Sample response:**
```json
{
  "event": "new_transaction",
  "transaction_id": 9341128,
  "ticker": "AAPL",
  "insider_name": "COOK TIMOTHY D",
  "insider_cik": "0001214156",
  "standard_type": "sale",
  "shares": 50000,
  "price_per_share": 175.25,
  "transaction_value": 8762500,
  "transaction_date": "2026-05-01",
  "sector": "Technology",
  "industry": "Consumer Electronics"
}
```