form4api

Python client for Form4API — real-time SEC Form 4 insider trading, Form 144 intent-to-sell, institutional 13F-HR, and congressional STOCK Act trading data, including the insider/Congress convergence signal.

Supports Python 3.11+. Uses httpx for both sync and async HTTP.

Installation

pip install form4api

Sync quickstart

from form4api import Form4ApiClient

client = Form4ApiClient("YOUR_API_KEY")

# Recent open-market purchases at Apple (excluding 10b5-1 plan trades)
txns = client.transactions.list(ticker="AAPL", code="P", exclude_10b5=True, per_page=5)
for t in txns:
    print(t.insider_name, t.insider_title, t.shares_amount, "@", t.price_per_share)
    print(f"  open market: {t.is_open_market}, 10b5 plan: {t.is10b5_plan}, value: ${t.total_value:,.0f}")

# Company overview (includes SIC, state, website)
company = client.companies.get("MSFT")
print(company.name, company.active_insiders, "active insiders")
print(company.sic_description, company.state_of_incorporation)

# Insider detail
insider = client.insiders.get("0001234567")
print(insider.name, insider.officer_title)

# Cluster-buy signals (Business plan)
signals = client.signals.list(cluster_buy=True)
for sig in signals:
    print(sig.company_name, sig.insider_count, "buyers on", sig.signal_date)

Async quickstart

import asyncio
from form4api import AsyncForm4ApiClient

async def main():
    async with AsyncForm4ApiClient("YOUR_API_KEY") as client:
        txns = await client.transactions.list(ticker="AAPL", per_page=5)
        for t in txns:
            print(t.insider_name, t.shares_amount, "@", t.price_per_share)

asyncio.run(main())

Resources

Every plan-gated endpoint the API exposes has a typed method here. Calling one your key isn't entitled to raises PlanError (HTTP 402) carrying required_plan, current_plan, and upgrade_url rather than failing opaquely.

An AsyncForm4ApiClient mirrors the whole surface with the same resources and method names — await client.insiders.leaderboard().

For the full parameter reference see the REST docs. For LLM workflows, form4api-mcp exposes the same endpoints as tools.

Transaction filters

client.transactions.list(
    ticker="AAPL",        # filter by ticker — accepts up to 25 comma-separated symbols
    cik="0000320193",     # or by company CIK
    insider_cik="...",    # filter by insider CIK
    code="P",             # transaction code: P=purchase, S=sale, A=grant, etc.
    from_date="2026-01-01",
    to_date="2026-12-31",
    filed_from="2026-01-01",  # filters on Filing.FiledAt (when it hit EDGAR), not the trade date
    filed_to="2026-12-31",
    exclude_10b5=True,    # omit trades filed under a Rule 10b5-1 plan
    per_page=100,
    page=1,
)

# Multi-ticker lookup in one call
client.transactions.list(ticker="AAPL,MSFT,NVDA")

Granular filtering (v0.4.0+)

# The "just show me real buys & sells" preset: open-market only,
# no 10b5-1 plan trades, no derivatives.
client.transactions.list(ticker="AAPL", significant=True)

# Multi-code include / exclude (comma-separated SEC codes)
client.transactions.list(codes="P,S")
client.transactions.list(exclude_codes="A,M,F,G")

# Whole-category filters: open_market | grants | derivatives | gifts | other
client.transactions.list(category="open_market")
client.transactions.list(exclude_category="derivatives")
client.transactions.list(exclude_derivative=True)

# Trade-size screening (Pro plan or higher)
client.transactions.list(min_value=1_000_000)          # USD, shares x price
client.transactions.list(min_shares=10_000, max_shares=100_000)

Transaction fields

Company fields

Pagination

paginate() pages through the data until it runs out (a short or empty page) or, since the backend's 2026-08-01 plan-gated pagination depth (Free: 20 pages, Starter: 100, Pro+: unlimited), the next page is rejected with a 402. That 402 is not swallowed — it raises PaginationLimitError mid-iteration, after every page already yielded has been delivered to your loop. Pages you already received are real and complete; the error only means iteration stopped early. Pass max_pages to stop deliberately before that ever happens, or catch PaginationLimitError to know when a Free/Starter key ran out of depth on a bulk pull:

from form4api import PaginationLimitError

# transactions.paginate() — yields one list per page automatically
all_txns = []
try:
    for batch in client.transactions.paginate(ticker="NVDA", exclude_10b5=True, per_page=100):
        all_txns.extend(batch)
except PaginationLimitError as e:
    print(f"Stopped after {e.pages_yielded} pages — {e}")
    # all_txns still holds every page yielded before the limit hit

# signals.paginate()
all_signals = []
for batch in client.signals.paginate(cluster_buy=True, per_page=100, max_pages=10):
    all_signals.extend(batch)

Error handling

from form4api import (
    Form4ApiClient,
    AuthError,
    PlanError,
    PaginationLimitError,
    RateLimitError,
    NotFoundError,
)

client = Form4ApiClient("YOUR_API_KEY")

try:
    signals = client.signals.list()
except PaginationLimitError as e:
    print(f"Paginate stopped after {e.pages_yielded} pages — upgrade to go deeper")
except PlanError as e:
    print(f"Upgrade required")
except RateLimitError as e:
    print(f"Retry after {e.retry_after}s")
except AuthError:
    print("Invalid API key")
except NotFoundError:
    print("Resource not found")

License

MIT