WebSocket (Path: /insider-module/socket.io)Stream of parsed insider transactions and subscription management.
Stream of parsed insider transactions and subscription management.
100 tokens/conn-daySince v1.0.0
Why use this
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.
Common use case
Monitoring CEO purchases > $1M in real-time.
Socket.IO WebSocket stream for live Form 4 insider transactions. Connect to /insider-module/socket.io and subscribe to new_transaction for every parsed Form 4 row, or per-ticker rooms (e.g. join: ticker_AAPL). Each message carries the full transaction payload (insider_name, standard_type, shares, price_per_share, transaction_value, sector, industry). Flat 100-token-per-UTC-day connection cost; same-day reconnects free.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| 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. | tok_test_abc123 |
| path | config | required | /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. | /insider-module/socket.io |
| namespace | config | required | /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. | /insider-module |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| event | string | no | 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 | no | 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 | no | 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 | no | 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 | no | 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 | no | Normalized transaction type — one of `purchase`, `sale`, `grant`, `exercise`, `gift`, `other`. The high-signal types for trading workflows are `purchase` and `sale`. |
| shares | number | no | Share count for the transaction (split-adjusted). Always positive; direction encoded in `standard_type`. |
| price_per_share | number | yes | 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 | yes | 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 | no | 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 | yes | 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 | yes | Sharadar industry classification (more specific than `sector`). Null when unmapped. |
Sample response
·
- "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"
Errors
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected server-side failure. Retry with backoff; report if persistent. |
Code samples
curl -X WS "https://api.finradar.aiWebSocket (Path: /insider-module/socket.io)?api_Token=YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).