API Documentation

The Market Riddle data API gives programmatic, read-only access to the same SEC insider-trading and institutional-flow data the site is built on. It’s a Pro feature. Manage your keys and webhooks under your account.

Open the interactive API reference →

Authentication

Send your API key with every request, either as a header:

curl https://marketriddle.com/api/v1/moves \
  -H "X-API-Key: bf_live_your_key_here"

…or as a bearer token:

curl https://marketriddle.com/api/v1/moves \
  -H "Authorization: Bearer bf_live_your_key_here"

A key works only while your subscription is active on the Pro tier. Revoked keys, or keys whose account has lapsed, return 401.

Rate limits

Requests are limited per key. Every response includes the current window state in headers:

• X-RateLimit-Limit — requests allowed per minute
• X-RateLimit-Remaining — requests left in the current window
• X-RateLimit-Reset — Unix time when the window resets

Over the limit returns 429 with a Retry-After header.

Endpoints

All endpoints are under /api/v1 and return JSON. Lists are paged (page, size).

• GET /api/v1/moves — the ranked insider-transaction feed; filter by impact, role, type, date, and value
• GET /api/v1/companies — browse issuers; /companies/{cik} for detail; /companies/{cik}/transactions for history
• GET /api/v1/filers — browse insiders/funds/owners; /filers/{cik} and /filers/{cik}/transactions
• GET /api/v1/funds/top — largest institutional managers by latest-quarter 13F value

The interactive reference lists every parameter and response field, and lets you try calls with your key.

Webhooks

Instead of polling, register a webhook for a company or filer and the impact levels you care about. When a matching filing lands, we POST a signed JSON event to your URL:

POST /your-endpoint
Content-Type: application/json
X-MarketRiddle-Event: filing.new
X-MarketRiddle-Delivery: 42-0001193125-26-118517
X-MarketRiddle-Signature: sha256=<hex>

{
  "event": "filing.new",
  "delivery_id": "42-0001193125-26-118517",
  "filing": { "accession_number": "0001193125-26-118517", "form_type": "4", "impact_levels": ["high"] },
  "company": { "cik": 320193, "name": "APPLE INC" },
  "filer": { "cik": 1214128, "name": "COOK TIMOTHY D" },
  "target": { "type": "company", "cik": 320193 },
  "url": "https://marketriddle.com/companies/320193"
}

Verifying the signature

Compute the HMAC-SHA256 of the raw request body using your endpoint’s signing secret (shown once when you create the webhook) and compare it, constant-time, against the X-MarketRiddle-Signatureheader (the sha256= prefix followed by lowercase hex):

import hmac, hashlib

def verify(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Deliveries are de-duplicated per (endpoint, filing): you’ll receive each filing at most once. Respond with any 2xx to acknowledge.