insider-trades-api

v0.2.2

Published

a month ago

Official JavaScript and TypeScript SDK for the Insider Trades API — real-time SEC Form 3, 4, and 5 insider transaction data.

Downloads

112

0High
0Medium
0Low

goodtechllc

insider-trading form-4 form-3 form-5 sec edgar insider-transactions fintech quantitative-finance financial-data api-client

Insider Trades API — Node.js SDK

Official JavaScript and TypeScript SDK for the Insider Trades API — real-time SEC Form 3, 4, and 5 insider transaction data.

Using Claude, Cursor, ChatGPT, or another AI assistant? Use the insider-trades-mcp package instead — it connects your AI tool directly to the Insider Trades API with no code required.
Using Python? See the insider-trades-api Python SDK on PyPI.

Installation

npm install insider-trades-api

Quick Start

import { InsiderTradesAPI } from "insider-trades-api";

const client = new InsiderTradesAPI({
  apiKey: process.env['INSIDER_TRADES_API_KEY'],
});

// Get recent insider purchases for Apple
const { insiderTransactions } = await client.getInsiderTransactions({
  issuerTicker: "AAPL",
  transactionTypes: "purchase",
  limit: 10,
});

for (const tx of insiderTransactions) {
  console.log(tx.reportingOwnerInformation?.name, tx.purchaseAmount);
}

Get your API key at insidertrades.us.

API Reference

For the full reference including all parameters, response schemas, and plan limits, see insidertrades.us/docs.

`new InsiderTradesAPI(options)`

| Option | Type | Required | Description | |---|---|---|---| | apiKey | string | Yes | Your API key. Defaults to process.env['INSIDER_TRADES_API_KEY'] |

`getInsiderTransactions(params?)`

Retrieve SEC insider transactions from Form 3, 4, and 5 filings.

const { insiderTransactions, count } = await client.getInsiderTransactions({
  issuerTicker: "AAPL",
  transactionTypes: ["purchase", "sale"],
  filingDateInEstStartDate: "2026-01-01",
  filingDateInEstEndDate: "2026-01-31",
  limit: 50,
});

| Parameter | Type | Description | |---|---|---| | filingId | string | Direct lookup by filing ID | | issuerTicker | string | Filter by ticker symbol, e.g. "AAPL" | | issuerCik | string | Filter by issuer CIK | | reportingOwnerCik | string | Filter by insider CIK | | accessionNumber | string | Filter by SEC accession number | | formTypes | string \| string[] | Form types: "3", "4", "5" (default: all) | | transactionTypes | TransactionType \| TransactionType[] | See transaction types below | | ownerRoles | OwnerRole \| OwnerRole[] | "director", "officer", "tenPercentOwner" | | officerTitles | string \| string[] | Normalized titles: "CEO", "CFO", "COO", etc. | | filingDateInEstStartDate | string | Filing date start YYYY-MM-DD (Eastern Time) | | filingDateInEstEndDate | string | Filing date end YYYY-MM-DD (Eastern Time) | | periodOfReportStartDate | string | Period of report start YYYY-MM-DD | | periodOfReportEndDate | string | Period of report end YYYY-MM-DD | | minTotalAmount | number | Minimum total dollar value | | maxTotalAmount | number | Maximum total dollar value | | fieldset | "minimal" \| "standard" \| "full" | Control response size (see below) | | limit | number | Page size, default 100, max 750 | | cursor | string | Opaque pagination cursor — pass back the nextCursor from a previous response (see Pagination) |

Transaction types

| Value | SEC Code | Description | |-------|----------|-------------| | "purchase" | P | Open market purchase | | "sale" | S | Open market sale | | "grant" | A | Grant or award | | "gift" | G | Bona fide gift | | "exercise" | M | Option exercise (Rule 16b-3) | | "derivativeExercise" | O, X | Derivative exercise | | "disposition" | D | Disposition to issuer | | "discretionary" | I | Discretionary transaction | | "derivativeConversion" | C | Conversion of derivative | | "derivativeExpiration" | E, H | Expiration of derivative | | "smallAcquisition" | L | Small acquisition (Rule 16a-6) | | "inheritance" | W | Inheritance | | "equitySwap" | K | Equity swap | | "tender" | U | Tender offer / change of control | | "other" | J | Other acquisition / disposition |

Fieldsets

| Fieldset | Fields included | |---|---| | "minimal" | ID, issuer, owner, key amounts, dates | | "standard" | All of minimal + all aggregates, boolean flags, links, AI summary | | "full" | All of standard + raw transaction arrays (nonDerivativeTransactions, derivativeTransactions, holdings) |

Default (no fieldset param): all stored fields are returned.

Note: minimal and standard produce significantly smaller payloads — recommended for bulk queries.

Sample response:

{
  "insiderTransactions": [
    {
      "id": "97e823b724619e921c68ba73b2f95f3b015fb83cc05666320b6ddf34b97cdcbe",
      "formType": "4",
      "accessionNumber": "0001140361-26-023363",
      "issuerCik": "320193",
      "issuerInformation": {
        "cik": "0000320193",
        "tradingSymbol": "AAPL",
        "companyName": "Apple Inc."
      },
      "reportingOwnerCik": "1214128",
      "reportingOwnerInformation": {
        "cik": "0001214128",
        "name": "LEVINSON ARTHUR D",
        "city": "CUPERTINO",
        "state": "CA",
        "isDirector": true,
        "isOfficer": false
      },
      "ownerRoles": "director",
      "filingDateInEst": "2026-05-29",
      "periodOfReport": "2026-05-27",
      "totalAmount": 15551000.0,
      "saleAmount": 15551000.0,
      "saleCount": 1,
      "netSharesAcquired": -50000.0,
      "netTradingAmount": -15551000.0,
      "hasSales": "true",
      "hasLateTransactions": false,
      "aff10b5One": false,
      "summary": "Arthur D. Levinson sold 50,000 shares of Apple Inc. common stock at $311.02 per share on May 27, 2026.",
      "linkToFilingDetail": "https://www.sec.gov/Archives/edgar/data/1214128/000114036126023363/0001140361-26-023363-index.htm"
    }
  ],
  "count": 1,
  "recordedTimeInUtc": "2026-05-29T22:30:00Z",
  "hasMore": false
}

`iterateInsiderTransactions(params?)`

Auto-paginating async generator that yields individual transactions across all pages, following nextCursor for you. Accepts the same filters as getInsiderTransactions (the cursor is managed internally). Pages are fetched lazily as you iterate.

// Walk an entire year without managing cursors yourself.
for await (const tx of client.iterateInsiderTransactions({
  filingDateInEstStartDate: "2025-01-01",
  filingDateInEstEndDate: "2025-12-31",
  limit: 750, // larger page size = fewer requests against your quota
})) {
  console.log(tx.id, tx.totalAmount);
}

Pagination

A single response holds at most limit records (capped at 750 to stay within the API's response-size limit). When more results remain, the response sets hasMore: true and includes an opaque nextCursor.

Easiest: let the SDK walk pages for you with iterateInsiderTransactions.

Manual: pass nextCursor back as cursor, keeping the same filters. A cursor minted for one set of filters is rejected (HTTP 400) if replayed against different ones.

let cursor: string | undefined;
do {
  const page = await client.getInsiderTransactions({
    issuerCik: "320193",
    periodOfReportStartDate: "2025-01-01",
    periodOfReportEndDate: "2025-12-31",
    limit: 750,
    cursor,
  });
  for (const tx of page.insiderTransactions) {
    // ...
  }
  cursor = page.nextCursor;
} while (cursor);

Each page is a separate request and counts against your monthly quota — prefer a large limit (up to 750) on big walks to minimize request count.

Usage examples

Recent Form 4 purchases by date range

const { insiderTransactions } = await client.getInsiderTransactions({
  transactionTypes: "purchase",
  formTypes: "4",
  filingDateInEstStartDate: "2026-05-01",
  filingDateInEstEndDate: "2026-05-31",
  limit: 50,
});

High-value transactions over $1M

const { insiderTransactions } = await client.getInsiderTransactions({
  minTotalAmount: 1_000_000,
  transactionTypes: "purchase",
  filingDateInEstStartDate: "2026-05-01",
  filingDateInEstEndDate: "2026-05-31",
  limit: 25,
});

All transactions by a specific insider

const { insiderTransactions } = await client.getInsiderTransactions({
  reportingOwnerCik: "1214128",
  limit: 20,
});

CEO transactions across all companies

const { insiderTransactions } = await client.getInsiderTransactions({
  officerTitles: ["CEO"],
  formTypes: "4",
  filingDateInEstStartDate: "2026-05-01",
  filingDateInEstEndDate: "2026-05-31",
  limit: 20,
});

Look up a specific filing

const { insiderTransactions } = await client.getInsiderTransactions({
  accessionNumber: "0001140361-26-023363",
});

TypeScript

Full TypeScript support is included. All request params and responses are typed.

import type {
  InsiderTransaction,
  InsiderTransactionsResponse,
  GetInsiderTransactionsParams,
  IssuerInformation,
  ReportingOwnerInformation,
  NonDerivativeTransaction,
  DerivativeTransaction,
  NonDerivativeHolding,
  DerivativeHolding,
  Footnote,
  OwnerSignature,
  TransactionCode,
  TransactionType,
  OwnerRole,
} from "insider-trades-api";

Error handling

When the API returns a non-success status code, an error is thrown with the status and message:

try {
  const { insiderTransactions } = await client.getInsiderTransactions({ issuerTicker: "AAPL" });
} catch (err) {
  if (err instanceof Error) {
    console.error(err.message); // e.g. "InsiderTrades API error 403: Forbidden"
  }
}

| Status | Meaning | |---|---| | 400 | Invalid parameters (bad date format, invalid CIK, inverted date range) | | 403 | Invalid or missing API key, or requested date range exceeds plan limit | | 429 | Rate limit exceeded — retried automatically up to 3 times with backoff | | 504 | Request timed out — retried automatically up to 3 times | | 500 | Server error |

The SDK validates date format (YYYY-MM-DD), numeric CIK, and date range order before making any network request, so many errors are caught immediately without a round trip.

Changelog

[0.1.1] - 2026-06-02

Removed the baseUrl client option — the SDK always targets the official API endpoint, so no URL configuration is needed

[0.1.0] - 2026-06-01

Initial release: getInsiderTransactions() with full query parameter support
Filters: issuerTicker, issuerCik, reportingOwnerCik, transactionTypes, ownerRoles, officerTitles, date ranges, minTotalAmount, maxTotalAmount, fieldset
Retry logic for 429 and 504 with exponential backoff
Client-side input validation for date format, CIK format, and date range order
Full TypeScript types for all fields including transaction arrays, holdings, and boolean flags

Resources

Requirements

Node.js 20 LTS or later
TypeScript 4.7 or later (if using TypeScript)

Legal disclaimer

The data provided through this SDK is for informational purposes only and does not constitute investment advice, financial advice, trading advice, or any other type of advice. GoodTech LLC makes no representations as to the accuracy, completeness, or timeliness of the data. You are solely responsible for your use of the data. Past filings and transactions do not predict future performance. Always consult a qualified financial professional before making investment decisions.