API REFERENCE · v1 · 2026-10-02

API DOCUMENTATION

The only multi-market insider-trades API covering 43 markets(AMF · SEC · BaFin · SIX SER · RNS · SEDI · Consob · CNMV · AFM · FSMA · Oslo · Helsinki · Copenhagen · ASX · FMA · CVM · HKEX · BSE-Sofia · Tadawul · DART · EDINET · SSE · SZSE · SEBI · KNF · PSE · NZX · JSE) in one unified schema. FX-normalised amounts in EUR/USD. Retail T+30/T+90/T+365 backtests inline. Transparent scoring (9 decomposable factors). AI-native: MCP server for Claude, Cursor, Windsurf. API on Pro and Quant.

Interactive Swagger UI ↗MCP server for AI ↗Generate an API key ↗OpenAPI JSON spec ↗Compare vs Quiver, OpenInsider ↗

API ACCESS · CLOSED BETA
Sigma is in closed beta. The API and MCP server unlock with the Pro and Quant tiers. Join the waitlist for early access (334 req/day, 5-year API history, MCP, email alerts).
Join the beta waitlist →Free account

Live · GET /v1/declarations
$ 

Getting started

Quickstart

Three steps to make your first request:

Create an account, then go to My account → API keys.
Generate a named key (e.g. "Production bot"). Copy it immediately, it won't be shown again.
Add the header Authorization: Bearer <key> to every request.

curl https://insiders-trades.com/api/v1/me \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Security

Authentication

Every request must include exactly one valid, non-revoked API key. Two formats are accepted:

Authorization: Bearer <key> · standard, recommended.
X-Api-Key: <key> · alternative if your HTTP client doesn't handle the Authorization header well.

The key is shown only once at creation. If lost, revoke it and generate a new one. Limit: 10 active keys per account. Revoked keys remain visible in history.

Key format

text

sit_live_<32 base62 characters>

Example visible prefix (safe for logs): sit_live_Ab1C
The full key is ~40 characters. Stored hashed (SHA-256) server-side,
never retrievable in plain text.

Invalid, expired or revoked key

Any authentication error returns an HTTP 401 in a uniform format:

json

{
 "error": {
 "code": "invalid_api_key",
 "message": "Invalid, unknown or revoked API key. Generate a new key from your account.",
 "status": 401
 }
}

Fundamentals

Key concepts

Base URL

text

https://insiders-trades.com

Universal metadata

Every 200 response includes a meta object. It contains the server latency and a dataFreshness mini-dictionary with the last update date of each data block, letting your client decide whether to invalidate its cache.

json

{
 "items": [ /* ... */ ],
 "meta": {
 "requestedAt": "2026-04-20T18:32:11.123Z",
 "latencyMs": 47,
 "dataFreshness": {
 "priceAt": "2026-04-20T16:01:45.120Z",
 "financialsAt": "2026-04-20T15:04:10.940Z"
 }
 }
}

Pagination

Listing endpoints support ?limit (default 50, max 200) and ?offset (default 0). The returned total field allows paginating through all results.

Timestamp format

All timestamps are in ISO 8601 UTC (2026-04-20T18:32:11.123Z).

Nullable fields

A missing field in the database is serialised as null (never omitted). This lets you distinguish between "absent data" and a field error.

BigInt (amounts)

Fields like marketCap, revenue, totalAmount can exceed JS float capacity (2⁵³). They are returned as numbers, but for large totals (L'Oréal at €195bn…) your client code should use BigInt if precision matters below €1.

API Reference

Endpoints

18 endpoints, all read-only. Grouped by domain. Cross-market filter via ?market=fr|us|de|ch|uk|ca|it|es on every listing endpoint.

── Authentication

GET/api/v1/me

Verify a key and retrieve identity

Returns the information of the key owner + metadata about the key itself. Use it as a ping to validate that a key is still active.

curl https://insiders-trades.com/api/v1/me -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

── Health & stats

GET/api/v1/health

System status

Pings the database (with measured latency), timestamps each pipeline stage. Useful for detecting a stopped hourly cron or scoring job.

bash

curl https://insiders-trades.com/api/v1/health -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response (excerpt)

json

{
 "status": "ok",
 "database": { "reachable": true, "latencyMs": 187 },
 "lastAmfPublicationAt": "2026-04-20T16:20:03.577Z",
 "lastIngestAt": "2026-04-20T16:59:53.841Z",
 "lastScoringAt": "2026-04-20T17:59:59.061Z",
 "lastBacktestAt": "2026-04-19T20:13:54.245Z",
 "lastFinancialsAt": "2026-04-20T15:04:10.940Z",
 "lastPriceAt": "2026-04-20T16:01:45.120Z"
}

GET/api/v1/stats

Global counters

Total number of filings, companies, insiders, backtests, breakdowns by time window (24h / 7d / 30d), global average score.

bash

curl https://insiders-trades.com/api/v1/stats -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

GET/api/v1/markets

List supported markets / regulators

Catalogue of the 8 ingested regulators with live counters (declarations, companies) and per-market coverage window. Call once at integration startup to verify what's available.

bash

curl https://insiders-trades.com/api/v1/markets -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

json

{
 "total": { "markets": 8, "declarations": 31420, "companies": 2480 },
 "markets": [
 { "code": "fr", "iso": "FR", "label": "FR", "regulator": "AMF",
 "currency": "EUR", "declarations": 18900, "companies": 1240,
 "coverage": { "oldestPubDate": "2015-01-05T...", "latestPubDate": "2026-05-17T..." } },
 { "code": "us", "iso": "US", "label": "US", "regulator": "SEC (Form 4)",
 "currency": "USD", "declarations": 9100, "companies": 720, "coverage": { ... } },
 { "code": "de", "regulator": "BaFin", ... },
 { "code": "ch", "regulator": "SIX SER", ... },
 { "code": "uk", "regulator": "RNS (LSE)", ... },
 { "code": "ca", "regulator": "SEDI", ... },
 { "code": "it", "regulator": "Consob", ... },
 { "code": "es", "regulator": "CNMV", ... }
 ],
 "meta": { "requestedAt": "...", "latencyMs": 90 }
}

── Companies

GET/api/v1/companies

List companies

Returns filtered companies.

Paramètres de requête

Nom	Type	Défaut	Description
`q`	`string`	·	Case-insensitive name search
`isin`	`string`	·	Exact ISIN filter
`market`	`string`	·	Listing market filter (e.g. Euronext Paris)
`marketCode`	`enum`	·	Regulator jurisdiction: fr \| us \| de \| ch \| uk \| ca \| it \| es
`hasLogo`	`boolean`	·	Return only companies with (true) or without (false) a logo
`sort`	`enum`	name	name \| marketCap \| recent
`order`	`enum`	asc	asc \| desc
`limit`	`integer`	50	1 → 200
`offset`	`integer`	0	Pagination offset

bash

curl "https://insiders-trades.com/api/v1/companies?q=lvmh&limit=3" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response (truncated)

json

{
 "total": 585, "offset": 0, "limit": 3,
 "items": [
 {
 "name": "LVMH MOET HENNESSY-LOUIS VUITTON",
 "slug": "lvmh-moet-hennessy-louis-vuitton-0042",
 "isin": "FR0000121014",
 "market": "Euronext Paris",
 "yahooSymbol": "MC.PA",
 "marketCap": 320200000000,
 "currentPrice": 643.40,
 "trailingPE": 22.43,
 "analystReco": "buy",
 "targetMean": 595.72,
 "logoUrl": "https://.../lvmh.webp",
 "declarationsCount": 147,
 "priceAt": "2026-04-20T16:01:45.120Z",
 "financialsAt": "2026-04-20T15:04:10.940Z"
 }
 ],
 "meta": { "requestedAt": "...", "latencyMs": 650, "dataFreshness": { ... } }
}

GET/api/v1/companies/{slug}

Company detail (full fundamentals)

Returns the complete profile: income statement, balance sheet, valuation (P/E, P/B, beta), analyst consensus (reco, target mean/high/low), technicals (52-week, 50/200 DMA, dividend yield).

Paramètres de chemin

Nom	Type	Défaut	Description
`slug`requis	`string`	·	Unique URL identifier for the company (present in the list)

bash

curl https://insiders-trades.com/api/v1/companies/bouygues-1454 \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Yahoo fields (trailingPE, analystReco, targetMean…) may be null for micro-caps not covered by analysts.

GET/api/v1/companies/{slug}/declarations

Insider filings for a company

Complete transaction history of executives for a company, sorted by pubDate desc.

Paramètres de chemin

Nom	Type	Défaut	Description
`slug`requis	`string`	·	Company slug

Paramètres de requête

Nom	Type	Défaut	Description
`direction`	`enum`	·	BUY \| SELL (default: all)
`minScore`	`number`	·	signalScore threshold
`limit`	`integer`	50	1 → 200
`offset`	`integer`	0	Pagination offset

bash

curl "https://insiders-trades.com/api/v1/companies/bouygues-1454/declarations?direction=BUY&minScore=40&limit=5" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

GET/api/v1/companies/{slug}/insider-flow

Aggregated net buy/sell insider flow

Net buy minus net sell on a single company, bucketed by month (or ISO week), with per-insider rollups and a rolling 90-day signal. Designed to spot accumulation / distribution phases.

Paramètres de chemin

Nom	Type	Défaut	Description
`slug`requis	`string`	·	Company slug

Paramètres de requête

Nom	Type	Défaut	Description
`windowDays`	`integer`	730	30 → 3650 days
`bucket`	`enum`	month	month \| week

bash

curl "https://insiders-trades.com/api/v1/companies/bouygues-1454/insider-flow?windowDays=365&bucket=month" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

json

{
 "company": { "name": "BOUYGUES", "slug": "bouygues-1454", "marketCap": 12400000000 },
 "windowDays": 365, "bucket": "month",
 "totals": { "tradeCount": 47, "buyAmount": 18450000, "sellAmount": 2100000, "netAmount": 16350000, "sellToBuyRatio": 0.114 },
 "rolling90d": { "buyAmount": 7800000, "sellAmount": 0, "netAmount": 7800000 },
 "buckets": [
 { "period": "2025-06", "buyAmount": 1200000, "sellAmount": 0, "netAmount": 1200000, "tradeCount": 4 },
 { "period": "2025-07", "buyAmount": 840000, "sellAmount": 320000, "netAmount": 520000, "tradeCount": 3 }
 ],
 "topInsiders": [
 { "name": "M. BOUYGUES", "slug": "martin-bouygues", "function": "PDG",
 "buyAmount": 6400000, "sellAmount": 0, "netAmount": 6400000, "tradeCount": 12 }
 ]
}

── Executives

GET/api/v1/insiders

List executives

2,091 executives tracked. Fuzzy name search.

Paramètres de requête

Nom	Type	Défaut	Description
`q`	`string`	·	Case-insensitive name search
`limit`	`integer`	50	1 → 200
`offset`	`integer`	0	Pagination offset

bash

curl "https://insiders-trades.com/api/v1/insiders?q=arnault&limit=5" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

GET/api/v1/insiders/{slug}

Executive detail

Profile + companies they are associated with and their role + average and max score of their filings.

Paramètres de chemin

Nom	Type	Défaut	Description
`slug`requis	`string`	·	Executive slug

bash

curl https://insiders-trades.com/api/v1/insiders/bernard-arnault \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

GET/api/v1/insiders/{slug}/declarations

Transaction history for an executive

Complete trade chain, all companies combined, sorted by pubDate desc.

Paramètres de chemin

Nom	Type	Défaut	Description
`slug`requis	`string`	·	Executive slug

Paramètres de requête

Nom	Type	Défaut	Description
`limit`	`integer`	50	Max 200
`offset`	`integer`	0	Pagination offset

bash

curl https://insiders-trades.com/api/v1/insiders/bernard-arnault/declarations \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

GET/api/v1/insiders/{slug}/timeline

Chronological timeline with running cumulative position

Time-ordered transactions for a single insider, with a per-company running cumulative volume so you see the position build up trade by trade.

Paramètres de chemin

Nom	Type	Défaut	Description
`slug`requis	`string`	·	Executive slug

Paramètres de requête

Nom	Type	Défaut	Description
`from`	`ISO date`	·	Lower bound on pubDate (optional)
`to`	`ISO date`	·	Upper bound on pubDate (optional)
`limit`	`integer`	500	1 → 2000

bash

curl "https://insiders-trades.com/api/v1/insiders/bernard-arnault/timeline?from=2024-01-01&limit=200" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

── Filings

GET/api/v1/declarations

Advanced filing search

General-purpose endpoint with 12 combinable filters. The main entry point for exporting a historical corpus or analysing by criterion.

Paramètres de requête

Nom	Type	Défaut	Description
`market`	`enum`	·	Jurisdiction: fr \| us \| de \| ch \| uk \| ca \| it \| es (default: all)
`currency`	`enum`	·	EUR \| USD \| GBP \| CHF \| SEK \| NOK \| DKK \| AUD \| CAD · adds transaction.converted
`since`	`ISO date`	·	Alias of from. Pair with sort=pubDate&order=asc for incremental polling.
`include`	`string`	·	CSV of related objects to inline. Supported: backtest
`from`	`ISO date`	·	Filter pubDate >= from
`to`	`ISO date`	·	Filter pubDate <= to
`minScore`	`number`	·	Minimum signalScore threshold
`maxScore`	`number`	·	Maximum signalScore threshold
`direction`	`enum`	·	BUY \| SELL
`cluster`	`boolean`	·	true = cluster trades only
`minAmount`	`number`	·	Minimum amount in €
`company`	`string`	·	Company name search
`insider`	`string`	·	Executive name search
`isin`	`string`	·	Exact ISIN filter
`sort`	`enum`	pubDate	pubDate \| signalScore \| amount
`order`	`enum`	desc	asc \| desc
`limit`	`integer`	50	1 → 200
`offset`	`integer`	0	Pagination offset

bash

# Top 20 buy signals with v3 score ≥ 50 (high conviction) over the last 30 days
curl "https://insiders-trades.com/api/v1/declarations?direction=BUY&minScore=50&from=2026-03-20&sort=signalScore&order=desc&limit=20" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Multi-market variants

bash

# US-only buys, amounts in EUR, with backtest inline
curl "https://insiders-trades.com/api/v1/declarations?market=us&direction=BUY&currency=EUR&include=backtest&limit=20" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# Incremental polling, every new filing since yesterday, asc
curl "https://insiders-trades.com/api/v1/declarations?since=2026-05-16&sort=pubDate&order=asc&limit=200" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# DE+CH cluster buys (German Vorstand + Swiss board) above EUR 500k
curl "https://insiders-trades.com/api/v1/declarations?market=de&cluster=true&minAmount=500000" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

GET/api/v1/declarations/{amfId}

Filing detail (with backtest)

Complete object including the retail T+30/90/365 backtest if computed. Entry: pubDate+1 close.

Paramètres de chemin

Nom	Type	Défaut	Description
`amfId`requis	`string`	·	AMF identifier (e.g. 2026DD1108988)

bash

curl https://insiders-trades.com/api/v1/declarations/2026DD1108988 \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Backtest block excerpt

json

"backtest": {
"returnBasis": "retail_pubDate_plus_1_close",
 "direction": "BUY",
"priceAtPub": 33.10,
"returnsPct": {
  "T30": 4.16,
  "T90": 8.23,
  "T365": 19.88
},
"pubLeakPct": 2.0,
 "computedAt": "2026-04-19T20:13:54.245Z"
}

── Signals

GET/api/v1/signals

Top signals (buys / sells)

Shortcut to get the best scores over a rolling window. Ideal for a dashboard or notification bot.

Paramètres de requête

Nom	Type	Défaut	Description
`direction`	`enum`	BUY	BUY \| SELL
`lookbackDays`	`integer`	7	Window (1 → 90)
`minScore`	`integer`	40	Minimum score (0 → 100)
`limit`	`integer`	20	Max 100

bash

curl "https://insiders-trades.com/api/v1/signals?direction=BUY&minScore=50&lookbackDays=7&limit=5" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

── Scoring (transparency)

GET/api/v1/scoring/explain/{amfId}

Decompose a signalScore into 7 weighted factors

Returns the value, raw points awarded, cap, and a short rationale for each of the 7 factors of the v3 composite score. No black box, audit any signal yourself. Methodology: see /methodology.

Paramètres de chemin

Nom	Type	Défaut	Description
`amfId`requis	`string`	·	Unique identifier (e.g. 2026DD1108988 or SEC:0001127602-25-009876)

bash

curl https://insiders-trades.com/api/v1/scoring/explain/SEC:0001127602-25-009876 \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

json

{
 "declaration": { "amfId": "SEC:...", "storedScore": 78, "direction": "BUY", ... },
 "breakdown": {
 "sumFactorPoints": 78,
 "factors": [
 { "key": "pctOfMarketCap", "label": "Trade size vs market cap",
 "value": 0.42, "points": 14, "maxPoints": 16, "description": "Log-scaled..." },
 { "key": "directionalCluster", "label": "Directional cluster (±30d)",
 "value": 3, "points": 15, "maxPoints": 18, "description": "..." },
 { "key": "trackRecord", "label": "Insider track record (Bayesian-shrunk)",
 "value": 8.4, "sampleSize": 12, "points": 11, "maxPoints": 14, "description": "..." }
 ],
 "notes": [ "Sum of factor points is clamped to [0, 100]." ]
 }
}

── Backtest

GET/api/v1/backtest

Global backtest statistics

Average retail returns by horizon (T+30, T+90, T+365) and win rate at T+90. Filterable by direction / score / period.

Paramètres de requête

Nom	Type	Défaut	Description
`direction`	`enum`	·	BUY \| SELL (default: both)
`minScore`	`number`	·	Filter on the underlying declaration's signalScore
`from`	`ISO`	·	Filter pubDate >= from
`to`	`ISO`	·	Filter pubDate <= to

bash

curl "https://insiders-trades.com/api/v1/backtest?direction=BUY&minScore=50" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Sample response

json

{
 "filters": { "direction": "BUY", "minScore": "50", "from": null, "to": null },
 "total": 2 340,
 "byDirection": { "BUY": 2340 },
"returnBasis": "retail_pubDate_plus_1_close",
 "averageReturnsPct": {
"T30": 1.24, "T90": 4.62, "T365": 9.85
 },
 "sampleCounts": {
"T30": 2340, "T90": 2290, "T365": 1940
 },
 "winRates90d": { "BUY": 0.582, "SELL": null }
}

── Search

GET/api/v1/search

Cross-entity search

Fuzzy search across companies + executives in one call. Used by the site autocomplete.

Paramètres de requête

Nom	Type	Défaut	Description
`q`requis	`string`	·	Query (min 2 characters)
`limit`	`integer`	8	Max per bucket (1 → 50)

bash

curl "https://insiders-trades.com/api/v1/search?q=total" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

── Strategy & performance

GET/api/v1/strategy/winning

Live winning-strategy cohort

Signals matching the Sigma Winning Strategy's 6 filters (cluster, mid-cap, key roles, freshness ≤ 7d, acquisition, score v3 ≥ 40). Returns 4-year historical proof in the payload.

Paramètres de requête

Nom	Type	Défaut	Description
`lookbackDays`	`integer`	365	30 → 1825
`minScore`	`integer`	70	0 → 100

bash

curl "https://insiders-trades.com/api/v1/strategy/winning?minScore=70" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

GET/api/v1/oos-performance

Out-of-sample tracker (live)

Realized returns since deployment, computed on daily snapshots. Intentionally public (honesty number), no API key required.

bash

curl "https://insiders-trades.com/api/v1/oos-performance"

── Anonymous sandbox

GET/api/v1/sandbox/{path}

Anonymous proxy (10 calls / 24h, no key)

Proxies READ /api/v1/* routes without auth. Sliding 24h cap: 10 calls per fingerprint (3 for bot UAs). Datacenter IPs denied, captcha from call 6 onward, watermark in every response. Bulk export, MCP, webhooks are NOT proxied.

bash

# No header needed. Try it:
curl "https://insiders-trades.com/api/v1/sandbox/declarations?limit=3"
curl "https://insiders-trades.com/api/v1/sandbox/signals?direction=BUY&limit=5"
curl "https://insiders-trades.com/api/v1/sandbox/status"

POST/api/v1/sandbox/challenge

POW for bot user-agents

Issues an HMAC challenge (16-bit difficulty, 10-min TTL). Client must find a nonce s.t. sha256(challenge + ':' + nonce) starts with 4 hex zeroes, then resend X-Sandbox-POW-Challenge + X-Sandbox-POW-Solution on the next call.

bash

curl -X POST "https://insiders-trades.com/api/v1/sandbox/challenge"

Schema

Data model

Five main entities. Here are the fields exposed in the API (some internal fields such as indexes or technical timestamps are not included).

Company

`slug`	`string`	URL identifier, e.g. bouygues-1454
`name`	`string`	Company name (AMF source)
`isin`	`string \| null`	International Securities ID Number
`market`	`string \| null`	E.g. Euronext Paris
`yahooSymbol`	`string \| null`	Yahoo ticker for prices / fundamentals
`marketCap`	`number \| null`	Market capitalisation in €
`currentPrice`	`number \| null`	Latest known price
`trailingPE, forwardPE, priceToBook, beta`	`number \| null`	Yahoo valuation metrics
`analystReco, analystScore, targetMean, targetHigh, targetLow`	`mixed`	Analyst consensus
`dividendYield, fiftyTwoWeekHigh/Low, fiftyDayAverage, twoHundredDayAverage`	`number \| null`	Technicals
`logoUrl`	`string \| null`	CDN Vercel Blob
`priceAt, financialsAt, analystAt`	`ISO date-time`	Freshness per data block

Insider

`slug`	`string`	URL identifier
`name`	`string`	Executive name (AMF source)
`gender`	`string \| null`	M / F inferred by AI
`declarationsCount`	`integer`	Total number of transactions
`companies`	`Company[]`	Associated companies with held role

Declaration

`amfId`	`string`	Unique AMF identifier (e.g. 2026DD1108988)
`pubDate`	`ISO date-time`	AMF publication date
`transactionDate`	`ISO date-time \| null`	Effective transaction date
`pdfUrl`	`string`	Link to official AMF PDF
`transaction`	`object`	nature, instrument, isin, unitPrice, volume, totalAmount, currency, venue
`insider`	`object`	name, slug, function
`company`	`object`	name, slug, yahooSymbol, marketCap
`signal`	`object`	score (0-100), pctOfMarketCap, pctOfInsiderFlow, insiderCumNet, isCluster, scoredAt

BacktestResult (nested in Declaration.backtest)

`direction`	`string`	BUY \| SELL \| OTHER
`returnBasis`	`string`	retail_pubDate_plus_1_close
`priceAtPub`	`number \| null`	Retail entry price (pubDate+1 close)
`returnsPct.T30 / T90 / T365`	`number \| null`	Retail returns by horizon
`pubLeakPct`	`number \| null`	Move between transaction and publication
`computedAt`	`ISO date-time`	When the computation ran

Signal (v3 scoring component, computed on the fly)

`score`	`number (0-100)`	v3 composite score (10 components · see /methodologie)
`pctOfMarketCap`	`number \| null`	Amount / market cap ratio (%)
`pctOfInsiderFlow`	`number \| null`	Share of the executive's total flow
`insiderCumNet`	`number \| null`	Cumulative net (buy - sell) up to this trade
`isCluster`	`boolean`	≥ 2 executives in the SAME direction ±30d (v3 directional)

Errors

Error handling

All errors follow a uniform format (RFC-7807-like):

json

{
 "error": {
 "code": "<machine_readable_slug>",
 "message": "<human-readable description>",
 "status": <http_status>
 }
}

Error codes

Status	Code	When
`401`	`missing_api_key`	No Authorization or X-Api-Key header
`401`	`invalid_api_key`	Malformed, unknown, or revoked key. Banned user = same.
`404`	`company_not_found`	Non-existent company slug
`404`	`insider_not_found`	Non-existent executive slug
`404`	`declaration_not_found`	Non-existent amfId
`500`	`internal_error`	Server error, please share the URL + time with us

Retry any response ≥ 500 with exponential back-off (e.g. 1 s, 2 s, 4 s, max 5 attempts). Never retry 401 / 404.

Quotas

Rate limits & best practices

Default limits during the beta phase:

Closed beta: no web page limit, 20 sandbox requests/day with a Free account (counter resets at 00:00 UTC). API keys start on Pro and Quant.
10 req/second (burst) · sufficient for most use cases. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (ISO 8601).
10 active keys maximum per account. Beyond that, revoke one from your keys page.
Usage counters are visible in real-time by the user (total + today) and by the admin (with top consumers).

Best practices

Respect freshness. Data doesn't change every second. Yahoo prices are refreshed 1×/day (4 AM UTC), insider filings from our 43 markets (AMF, SEC, BaFin, SIX SER, RNS, SEDI, Consob, CNMV, AFM, FSMA, Oslo, Helsinki, Copenhagen, ASX, FMA, CVM, HKEX, BSE-Sofia, Tadawul, DART, EDINET, SSE, SZSE, SEBI, KNF, PSE, NZX, JSE and more) several times a day, depending on the source. Check meta.dataFreshness to adapt your polling frequency.
Cache aggressively. A company detail rarely changes, cache it client-side until priceAt + 1h.
Paginate correctly. Use a reasonable limit (20–50) and offset for large datasets.
Retry 5xx. With exponential back-off, max 5 attempts.
Store your key securely. Never in plain text in a Git repo, in the frontend, or in logs.

Examples

Code samples

Fetch today's top signals

const API = "https://insiders-trades.com";
const KEY = process.env.INSIDERS_API_KEY;

async function topSignals(direction = "BUY", days = 1) {
 const url = new URL(API + "/api/v1/signals");
 url.searchParams.set("direction", direction);
 url.searchParams.set("lookbackDays", String(days));
 url.searchParams.set("minScore", "50");
 url.searchParams.set("limit", "10");

 const res = await fetch(url, {
 headers: { Authorization: "Bearer " + KEY },
 });
 if (!res.ok) throw new Error(`HTTP ${res.status}`);
 const { items, meta } = await res.json();

 console.log(`${items.length} signals · latency ${meta.latencyMs}ms`);
 for (const s of items) {
 console.log(
 `[${s.signal.score}] ${s.company.name.padEnd(32)} ${s.insider.name} · ${s.transaction.amount}€`
);
 }
}

topSignals();

CSV export of all filings for a company

import csv, os, requests

API = "https://insiders-trades.com"
KEY = os.environ["INSIDERS_API_KEY"]

def fetch_all(slug):
 items, offset = [], 0
 while True:
 r = requests.get(
 f"{API}/api/v1/companies/{slug}/declarations",
 params={"limit": 100, "offset": offset},
 headers={"Authorization": f"Bearer {KEY}"},
)
 r.raise_for_status()
 page = r.json()
 items.extend(page["items"])
 if offset + 100 >= page["total"]:
 break
 offset += 100
 return items

with open("bouygues_declarations.csv", "w", newline="") as f:
 rows = fetch_all("bouygues-1454")
 w = csv.writer(f)
 w.writerow(["pubDate", "insider", "role", "nature",
 "isin", "unitPrice", "volume", "amount", "score"])
 for d in rows:
 w.writerow([
 d["pubDate"],
 d["insider"]["name"],
 d["insider"]["function"],
 d["transaction"]["nature"],
 d["transaction"]["isin"],
 d["transaction"]["unitPrice"],
 d["transaction"]["volume"],
 d["transaction"]["totalAmount"],
 d["signal"]["score"],
 ])
print(f"Wrote {len(rows)} rows")

Versioning

Changelog

v1.0.0 · 2026-04-20

Public API launch.
18 endpoints, API key authentication, freshness + rate-limit metadata on every response.
Interactive Swagger UI available at /api/docs.

Support

Help, feedback, SLA

The API is in private beta. Access is by invitation. No contractual SLA is provided during the beta, but the team monitors data freshness daily (hourly multi-market cron + daily Yahoo).

Beta access request or quota increase: contact contact@insiders-trades.com.
Bug / anomaly: include the exact URL, the time (UTC), and the prefix of the key used.
Roadmap: POST endpoints for push notifications, webhooks on new signals, granular scopes.

Ethical use. Insider filings (AMF, SEC, BaFin, SIX, RNS, SEDI, Consob, CNMV, AFM, FSMA, Oslo, Helsinki, Stockholm, Copenhagen, ASX, FMA, Dublin and more) are public, but the rate limit also prevents overloading upstream servers (Yahoo Finance, BDIF, EDGAR, etc.). Abusive patterns result in immediate key revocation.

Ready to integrate the insider signal?

Generate a key in 10 seconds, copy the cURL example from the quickstart, and explore the endpoints live with Swagger.

Generate my key →Open Swagger ↗