form4api 0.1.0__tar.gz

form4api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Form4API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

form4api-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: form4api
+Version: 0.1.0
+Summary: Python client for the Form4API — real-time SEC Form 4 insider trading data
+License-Expression: MIT
+Project-URL: Homepage, https://form4api.com
+Project-URL: Documentation, https://form4api.com/docs
+Project-URL: Repository, https://github.com/theodor90/form4api-py.git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Dynamic: license-file
+
+# form4api
+
+Python client for [Form4API](https://form4api.com) — real-time SEC Form 4 insider trading data.
+
+Supports Python 3.11+. Uses `httpx` for both sync and async HTTP.
+
+## Installation
+
+```bash
+pip install form4api
+```
+
+## Sync quickstart
+
+```python
+from form4api import Form4ApiClient
+
+client = Form4ApiClient("YOUR_API_KEY")
+
+# Recent open-market purchases at Apple
+txns = client.transactions.list(ticker="AAPL", code="P", per_page=5)
+for t in txns:
+    print(t.insider_name, t.shares_amount, "@", t.price_per_share)
+
+# Company overview
+company = client.companies.get("MSFT")
+print(company.name, company.active_insiders, "active insiders")
+
+# Insider detail
+insider = client.insiders.get("0001234567")
+print(insider.name, insider.officer_title)
+
+# Cluster-buy signals (Business plan)
+signals = client.signals.list(ticker="NVDA")
+for sig in signals:
+    if sig.is_cluster_buy:
+        print(sig.company_name, sig.insider_count, "buyers")
+```
+
+## Async quickstart
+
+```python
+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
+
+| Resource | Methods |
+|---|---|
+| `client.transactions` | `.list(**params)`, `.paginate(**params)` |
+| `client.insiders` | `.get(cik)`, `.transactions(cik, **params)` |
+| `client.companies` | `.get(ticker)`, `.insiders(ticker)` |
+| `client.signals` | `.list(**params)` — Business plan |
+| `client.webhooks` | `.create(url, event_types)`, `.list()`, `.delete(id)`, `.events(**params)` |
+
+## Error handling
+
+```python
+from form4api import Form4ApiClient, AuthError, PlanError, RateLimitError, NotFoundError
+
+client = Form4ApiClient("YOUR_API_KEY")
+
+try:
+    signals = client.signals.list()
+except PlanError as e:
+    print(f"Upgrade to {e.required_plan}")
+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

form4api-0.1.0/README.md

@@ -0,0 +1,86 @@
+# form4api
+
+Python client for [Form4API](https://form4api.com) — real-time SEC Form 4 insider trading data.
+
+Supports Python 3.11+. Uses `httpx` for both sync and async HTTP.
+
+## Installation
+
+```bash
+pip install form4api
+```
+
+## Sync quickstart
+
+```python
+from form4api import Form4ApiClient
+
+client = Form4ApiClient("YOUR_API_KEY")
+
+# Recent open-market purchases at Apple
+txns = client.transactions.list(ticker="AAPL", code="P", per_page=5)
+for t in txns:
+    print(t.insider_name, t.shares_amount, "@", t.price_per_share)
+
+# Company overview
+company = client.companies.get("MSFT")
+print(company.name, company.active_insiders, "active insiders")
+
+# Insider detail
+insider = client.insiders.get("0001234567")
+print(insider.name, insider.officer_title)
+
+# Cluster-buy signals (Business plan)
+signals = client.signals.list(ticker="NVDA")
+for sig in signals:
+    if sig.is_cluster_buy:
+        print(sig.company_name, sig.insider_count, "buyers")
+```
+
+## Async quickstart
+
+```python
+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
+
+| Resource | Methods |
+|---|---|
+| `client.transactions` | `.list(**params)`, `.paginate(**params)` |
+| `client.insiders` | `.get(cik)`, `.transactions(cik, **params)` |
+| `client.companies` | `.get(ticker)`, `.insiders(ticker)` |
+| `client.signals` | `.list(**params)` — Business plan |
+| `client.webhooks` | `.create(url, event_types)`, `.list()`, `.delete(id)`, `.events(**params)` |
+
+## Error handling
+
+```python
+from form4api import Form4ApiClient, AuthError, PlanError, RateLimitError, NotFoundError
+
+client = Form4ApiClient("YOUR_API_KEY")
+
+try:
+    signals = client.signals.list()
+except PlanError as e:
+    print(f"Upgrade to {e.required_plan}")
+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

form4api-0.1.0/form4api/__init__.py

@@ -0,0 +1,30 @@
+from form4api._client import AsyncForm4ApiClient, Form4ApiClient
+from form4api._errors import AuthError, Form4ApiError, NotFoundError, PlanError, RateLimitError
+from form4api._types import (
+    Company,
+    Insider,
+    InsiderSignal,
+    Transaction,
+    WebhookCreated,
+    WebhookEvent,
+    WebhookSubscription,
+)
+from form4api._webhook_utils import verify_webhook
+
+__all__ = [
+    "Form4ApiClient",
+    "AsyncForm4ApiClient",
+    "Form4ApiError",
+    "AuthError",
+    "PlanError",
+    "NotFoundError",
+    "RateLimitError",
+    "Transaction",
+    "Insider",
+    "Company",
+    "InsiderSignal",
+    "WebhookCreated",
+    "WebhookEvent",
+    "WebhookSubscription",
+    "verify_webhook",
+]

form4api-0.1.0/form4api/_client.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import asyncio
+import re
+import time
+from typing import Any, TypeVar
+
+import httpx
+
+from form4api._errors import AuthError, Form4ApiError, NotFoundError, PlanError, RateLimitError
+from form4api.resources._companies import CompaniesResource
+from form4api.resources._insiders import InsidersResource
+from form4api.resources._signals import SignalsResource
+from form4api.resources._transactions import TransactionsResource
+from form4api.resources._webhooks import WebhooksResource
+
+DEFAULT_BASE_URL = "https://api.form4api.com"
+_RETRY_DELAYS = [0.5, 1.0, 2.0]
+
+T = TypeVar("T")
+
+
+def _camel_to_snake(name: str) -> str:
+    s = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
+    return re.sub(r"([a-z\d])([A-Z])", r"\1_\2", s).lower()
+
+
+def _normalise(obj: Any) -> Any:
+    if isinstance(obj, dict):
+        return {_camel_to_snake(k): _normalise(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_normalise(i) for i in obj]
+    return obj
+
+
+class Form4ApiClient:
+    """Synchronous client for the Form4API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 2,
+        timeout: float = 30.0,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._http = httpx.Client(
+            timeout=timeout,
+            headers={"X-Api-Key": api_key},
+        )
+        self.transactions = TransactionsResource(self)
+        self.insiders = InsidersResource(self)
+        self.companies = CompaniesResource(self)
+        self.signals = SignalsResource(self)
+        self.webhooks = WebhooksResource(self)
+
+    def __enter__(self) -> Form4ApiClient:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        url = self._base_url + path
+        last_exc: Exception | None = None
+
+        for attempt in range(self._max_retries + 1):
+            if attempt > 0:
+                time.sleep(_RETRY_DELAYS[min(attempt - 1, len(_RETRY_DELAYS) - 1)])
+            try:
+                res = self._http.request(method, url, **kwargs)
+                if res.status_code < 500:
+                    return res
+                if attempt == self._max_retries:
+                    return res
+                last_exc = None
+            except httpx.TransportError as exc:
+                if attempt == self._max_retries:
+                    raise
+                last_exc = exc
+
+        raise last_exc  # type: ignore[misc]
+
+    def _get(self, path: str, params: dict[str, str] | None = None) -> Any:
+        res = self._request("GET", path, params=params)
+        return _normalise(self._parse(res))
+
+    def _post(self, path: str, body: Any = None) -> Any:
+        res = self._request("POST", path, json=body)
+        return _normalise(self._parse(res))
+
+    def _delete(self, path: str) -> None:
+        res = self._request("DELETE", path)
+        if not res.is_success and res.status_code != 204:
+            self._raise(res)
+
+    def _parse(self, res: httpx.Response) -> Any:
+        if res.is_success:
+            return res.json()
+        self._raise(res)
+
+    def _raise(self, res: httpx.Response) -> None:
+        try:
+            body = res.json()
+        except Exception:
+            body = {}
+        error = body.get("error", {}) if isinstance(body, dict) else {}
+        code = error.get("code") if isinstance(error, dict) else None
+        message = (error.get("message") if isinstance(error, dict) else None) or f"HTTP {res.status_code}"
+
+        if res.status_code == 401:
+            raise AuthError(message, code)
+        if res.status_code == 402:
+            raise PlanError(message, body.get("requiredPlan") if isinstance(body, dict) else None)
+        if res.status_code == 404:
+            raise NotFoundError(message, code)
+        if res.status_code == 429:
+            retry_after = res.headers.get("Retry-After")
+            raise RateLimitError(message, int(retry_after) if retry_after else None)
+        raise Form4ApiError(message, res.status_code, code)
+
+
+class AsyncForm4ApiClient:
+    """Async client for the Form4API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 2,
+        timeout: float = 30.0,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._http = httpx.AsyncClient(
+            timeout=timeout,
+            headers={"X-Api-Key": api_key},
+        )
+        self.transactions = TransactionsResource(self)  # type: ignore[arg-type]
+        self.insiders = InsidersResource(self)  # type: ignore[arg-type]
+        self.companies = CompaniesResource(self)  # type: ignore[arg-type]
+        self.signals = SignalsResource(self)  # type: ignore[arg-type]
+        self.webhooks = WebhooksResource(self)  # type: ignore[arg-type]
+
+    async def __aenter__(self) -> AsyncForm4ApiClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        url = self._base_url + path
+        last_exc: Exception | None = None
+
+        for attempt in range(self._max_retries + 1):
+            if attempt > 0:
+                await asyncio.sleep(_RETRY_DELAYS[min(attempt - 1, len(_RETRY_DELAYS) - 1)])
+            try:
+                res = await self._http.request(method, url, **kwargs)
+                if res.status_code < 500:
+                    return res
+                if attempt == self._max_retries:
+                    return res
+                last_exc = None
+            except httpx.TransportError as exc:
+                if attempt == self._max_retries:
+                    raise
+                last_exc = exc
+
+        raise last_exc  # type: ignore[misc]
+
+    async def _get(self, path: str, params: dict[str, str] | None = None) -> Any:
+        res = await self._request("GET", path, params=params)
+        return _normalise(self._parse(res))
+
+    async def _post(self, path: str, body: Any = None) -> Any:
+        res = await self._request("POST", path, json=body)
+        return _normalise(self._parse(res))
+
+    async def _delete(self, path: str) -> None:
+        res = await self._request("DELETE", path)
+        if not res.is_success and res.status_code != 204:
+            self._raise(res)
+
+    def _parse(self, res: httpx.Response) -> Any:
+        if res.is_success:
+            return res.json()
+        self._raise(res)
+
+    def _raise(self, res: httpx.Response) -> None:
+        try:
+            body = res.json()
+        except Exception:
+            body = {}
+        error = body.get("error", {}) if isinstance(body, dict) else {}
+        code = error.get("code") if isinstance(error, dict) else None
+        message = (error.get("message") if isinstance(error, dict) else None) or f"HTTP {res.status_code}"
+
+        if res.status_code == 401:
+            raise AuthError(message, code)
+        if res.status_code == 402:
+            raise PlanError(message, body.get("requiredPlan") if isinstance(body, dict) else None)
+        if res.status_code == 404:
+            raise NotFoundError(message, code)
+        if res.status_code == 429:
+            retry_after = res.headers.get("Retry-After")
+            raise RateLimitError(message, int(retry_after) if retry_after else None)
+        raise Form4ApiError(message, res.status_code, code)

form4api-0.1.0/form4api/_errors.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+
+class Form4ApiError(Exception):
+    def __init__(self, message: str, status_code: int, error_code: str | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+
+
+class AuthError(Form4ApiError):
+    def __init__(self, message: str, error_code: str | None = None) -> None:
+        super().__init__(message, 401, error_code)
+
+
+class PlanError(Form4ApiError):
+    def __init__(self, message: str, required_plan: str | None = None) -> None:
+        super().__init__(message, 402, "PLAN_REQUIRED")
+        self.required_plan = required_plan
+
+
+class NotFoundError(Form4ApiError):
+    def __init__(self, message: str, error_code: str | None = None) -> None:
+        super().__init__(message, 404, error_code)
+
+
+class RateLimitError(Form4ApiError):
+    def __init__(self, message: str, retry_after: int | None = None) -> None:
+        super().__init__(message, 429, "RATE_LIMIT_EXCEEDED")
+        self.retry_after = retry_after

form4api-0.1.0/form4api/_types.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Transaction:
+    ticker: str
+    company_name: str
+    insider_name: str
+    insider_cik: str
+    accession_number: str
+    security_title: str
+    transaction_code: str
+    shares_amount: float
+    price_per_share: float | None
+    shares_owned_after: float | None
+    direct_indirect: str | None
+    is_derivative: bool
+    transaction_date: str
+    period_of_report: str
+
+
+@dataclass
+class Insider:
+    cik: str
+    name: str
+    is_director: bool
+    is_officer: bool
+    is_ten_percent_owner: bool
+    officer_title: str | None
+    total_filings: int
+
+
+@dataclass
+class Company:
+    cik: str
+    name: str
+    ticker: str | None
+    exchange: str | None
+    total_filings: int
+    active_insiders: int
+
+
+@dataclass
+class InsiderSignal:
+    ticker: str | None
+    company_name: str
+    signal_date: str
+    buy_sell_ratio: float
+    is_cluster_buy: bool
+    is_cluster_sell: bool
+    insider_count: int
+
+
+@dataclass
+class WebhookCreated:
+    subscription_id: int
+    url: str
+    event_types: list[str]
+    secret: str
+    created_at: str
+    warning: str | None
+
+
+@dataclass
+class WebhookSubscription:
+    subscription_id: int
+    url: str
+    event_types: list[str]
+    created_at: str
+    is_active: bool
+
+
+@dataclass
+class WebhookEvent:
+    delivery_id: int
+    subscription_id: int
+    event_type: str
+    attempt_count: int
+    delivered_at: str | None
+    next_retry_at: str | None
+    last_status_code: int | None
+    is_dead: bool
+    payload: str
+
+
+

form4api-0.1.0/form4api/_webhook_utils.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def verify_webhook(payload: str | bytes, signature: str, secret: str) -> bool:
+    """Return True if the X-Insider-Signature header matches the payload.
+
+    Usage::
+
+        body = request.get_data(as_text=True)
+        sig  = request.headers["X-Insider-Signature"]
+        if not verify_webhook(body, sig, WEBHOOK_SECRET):
+            abort(401)
+    """
+    if isinstance(payload, str):
+        payload = payload.encode()
+    expected = "sha256=" + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature)
+
+
+

form4api-0.1.0/form4api/resources/__init__.py

@@ -0,0 +1,16 @@
+from form4api.resources._companies import CompaniesResource
+from form4api.resources._insiders import InsidersResource
+from form4api.resources._signals import SignalsResource
+from form4api.resources._transactions import TransactionsResource
+from form4api.resources._webhooks import WebhooksResource
+
+__all__ = [
+    "CompaniesResource",
+    "InsidersResource",
+    "SignalsResource",
+    "TransactionsResource",
+    "WebhooksResource",
+]
+
+
+

form4api-0.1.0/form4api/resources/_companies.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from form4api._types import Company, Insider
+
+if TYPE_CHECKING:
+    from form4api._client import Form4ApiClient
+
+
+class CompaniesResource:
+    def __init__(self, client: Form4ApiClient) -> None:
+        self._client = client
+
+    def get(self, ticker: str) -> Company:
+        data = self._client._get(f"/v1/companies/{ticker}")
+        return Company(**data)
+
+    def insiders(self, ticker: str) -> list[Insider]:
+        data = self._client._get(f"/v1/companies/{ticker}/insiders")
+        return [Insider(**item) for item in data]
+
+
+

form4api-0.1.0/form4api/resources/_insiders.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from form4api._types import Insider, Transaction
+
+if TYPE_CHECKING:
+    from form4api._client import Form4ApiClient
+
+
+class InsidersResource:
+    def __init__(self, client: Form4ApiClient) -> None:
+        self._client = client
+
+    def get(self, cik: str) -> Insider:
+        data = self._client._get(f"/v1/insiders/{cik}")
+        return Insider(**data)
+
+    def transactions(
+        self,
+        cik: str,
+        *,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        page: int = 1,
+        per_page: int = 50,
+    ) -> list[Transaction]:
+        params: dict[str, str] = {"page": str(page), "per_page": str(per_page)}
+        if from_date is not None:
+            params["from"] = from_date
+        if to_date is not None:
+            params["to"] = to_date
+        data = self._client._get(f"/v1/insiders/{cik}/transactions", params)
+        return [Transaction(**item) for item in data]
+
+
+

form4api-0.1.0/form4api/resources/_signals.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from form4api._types import InsiderSignal
+
+if TYPE_CHECKING:
+    from form4api._client import Form4ApiClient
+
+
+class SignalsResource:
+    def __init__(self, client: Form4ApiClient) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        ticker: str | None = None,
+        page: int = 1,
+        per_page: int = 100,
+    ) -> list[InsiderSignal]:
+        params: dict[str, str] = {"page": str(page), "per_page": str(per_page)}
+        if ticker is not None:
+            params["ticker"] = ticker
+        data = self._client._get("/v1/signals", params)
+        return [InsiderSignal(**item) for item in data]
+
+
+

form4api-0.1.0/form4api/resources/_transactions.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+from typing import TYPE_CHECKING
+
+from form4api._types import Transaction
+
+if TYPE_CHECKING:
+    from form4api._client import Form4ApiClient
+
+
+class TransactionsResource:
+    def __init__(self, client: Form4ApiClient) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        ticker: str | None = None,
+        cik: str | None = None,
+        insider_cik: str | None = None,
+        code: str | None = None,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        page: int = 1,
+        per_page: int = 50,
+    ) -> list[Transaction]:
+        params: dict[str, str] = {"page": str(page), "per_page": str(per_page)}
+        if ticker is not None:
+            params["ticker"] = ticker
+        if cik is not None:
+            params["cik"] = cik
+        if insider_cik is not None:
+            params["insider_cik"] = insider_cik
+        if code is not None:
+            params["code"] = code
+        if from_date is not None:
+            params["from"] = from_date
+        if to_date is not None:
+            params["to"] = to_date
+        data = self._client._get("/v1/transactions", params)
+        return [Transaction(**item) for item in data]
+
+    def paginate(
+        self,
+        *,
+        ticker: str | None = None,
+        cik: str | None = None,
+        insider_cik: str | None = None,
+        code: str | None = None,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        per_page: int = 50,
+    ) -> Generator[list[Transaction], None, None]:
+        page = 1
+        while True:
+            batch = self.list(
+                ticker=ticker, cik=cik, insider_cik=insider_cik,
+                code=code, from_date=from_date, to_date=to_date,
+                page=page, per_page=per_page,
+            )
+            if not batch:
+                break
+            yield batch
+            if len(batch) < per_page:
+                break
+            page += 1
+
+
+

form4api-0.1.0/form4api/resources/_webhooks.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from form4api._types import WebhookCreated, WebhookEvent, WebhookSubscription
+
+if TYPE_CHECKING:
+    from form4api._client import Form4ApiClient
+
+
+class WebhooksResource:
+    def __init__(self, client: Form4ApiClient) -> None:
+        self._client = client
+
+    def create(self, url: str, event_types: list[str]) -> WebhookCreated:
+        data = self._client._post("/v1/webhooks", {"url": url, "eventTypes": event_types})
+        return WebhookCreated(**data)
+
+    def list(self) -> list[WebhookSubscription]:
+        data = self._client._get("/v1/webhooks")
+        return [WebhookSubscription(**item) for item in data]
+
+    def delete(self, subscription_id: int) -> None:
+        self._client._delete(f"/v1/webhooks/{subscription_id}")
+
+    def events(self, *, since: str | None = None) -> list[WebhookEvent]:
+        params: dict[str, str] = {}
+        if since is not None:
+            params["since"] = since
+        data = self._client._get("/v1/webhooks/events", params or None)
+        return [WebhookEvent(**item) for item in data]
+
+
+

form4api-0.1.0/form4api.egg-info/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: form4api
+Version: 0.1.0
+Summary: Python client for the Form4API — real-time SEC Form 4 insider trading data
+License-Expression: MIT
+Project-URL: Homepage, https://form4api.com
+Project-URL: Documentation, https://form4api.com/docs
+Project-URL: Repository, https://github.com/theodor90/form4api-py.git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Dynamic: license-file
+
+# form4api
+
+Python client for [Form4API](https://form4api.com) — real-time SEC Form 4 insider trading data.
+
+Supports Python 3.11+. Uses `httpx` for both sync and async HTTP.
+
+## Installation
+
+```bash
+pip install form4api
+```
+
+## Sync quickstart
+
+```python
+from form4api import Form4ApiClient
+
+client = Form4ApiClient("YOUR_API_KEY")
+
+# Recent open-market purchases at Apple
+txns = client.transactions.list(ticker="AAPL", code="P", per_page=5)
+for t in txns:
+    print(t.insider_name, t.shares_amount, "@", t.price_per_share)
+
+# Company overview
+company = client.companies.get("MSFT")
+print(company.name, company.active_insiders, "active insiders")
+
+# Insider detail
+insider = client.insiders.get("0001234567")
+print(insider.name, insider.officer_title)
+
+# Cluster-buy signals (Business plan)
+signals = client.signals.list(ticker="NVDA")
+for sig in signals:
+    if sig.is_cluster_buy:
+        print(sig.company_name, sig.insider_count, "buyers")
+```
+
+## Async quickstart
+
+```python
+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
+
+| Resource | Methods |
+|---|---|
+| `client.transactions` | `.list(**params)`, `.paginate(**params)` |
+| `client.insiders` | `.get(cik)`, `.transactions(cik, **params)` |
+| `client.companies` | `.get(ticker)`, `.insiders(ticker)` |
+| `client.signals` | `.list(**params)` — Business plan |
+| `client.webhooks` | `.create(url, event_types)`, `.list()`, `.delete(id)`, `.events(**params)` |
+
+## Error handling
+
+```python
+from form4api import Form4ApiClient, AuthError, PlanError, RateLimitError, NotFoundError
+
+client = Form4ApiClient("YOUR_API_KEY")
+
+try:
+    signals = client.signals.list()
+except PlanError as e:
+    print(f"Upgrade to {e.required_plan}")
+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

form4api-0.1.0/form4api.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+form4api/__init__.py
+form4api/_client.py
+form4api/_errors.py
+form4api/_types.py
+form4api/_webhook_utils.py
+form4api.egg-info/PKG-INFO
+form4api.egg-info/SOURCES.txt
+form4api.egg-info/dependency_links.txt
+form4api.egg-info/requires.txt
+form4api.egg-info/top_level.txt
+form4api/resources/__init__.py
+form4api/resources/_companies.py
+form4api/resources/_insiders.py
+form4api/resources/_signals.py
+form4api/resources/_transactions.py
+form4api/resources/_webhooks.py
+tests/test_client.py

form4api-0.1.0/form4api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

form4api-0.1.0/form4api.egg-info/requires.txt

@@ -0,0 +1,6 @@
+httpx>=0.27
+
+[dev]
+pytest>=8
+pytest-httpx>=0.30
+respx>=0.21

form4api-0.1.0/form4api.egg-info/top_level.txt

@@ -0,0 +1 @@
+form4api

form4api-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "form4api"
+version = "0.1.0"
+description = "Python client for the Form4API — real-time SEC Form 4 insider trading data"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27"]
+license = "MIT"
+readme = "README.md"
+
+[project.urls]
+Homepage = "https://form4api.com"
+Documentation = "https://form4api.com/docs"
+Repository = "https://github.com/theodor90/form4api-py.git"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-httpx>=0.30", "respx>=0.21"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["form4api*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

form4api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

form4api-0.1.0/tests/test_client.py

@@ -0,0 +1,270 @@
+import pytest
+import httpx
+import respx
+
+from form4api import (
+    Form4ApiClient,
+    AuthError,
+    NotFoundError,
+    PlanError,
+    RateLimitError,
+    Form4ApiError,
+    Transaction,
+    Insider,
+    Company,
+    InsiderSignal,
+    verify_webhook,
+)
+
+BASE = "https://api.form4api.com"
+
+TX = {
+    "ticker": "AAPL",
+    "companyName": "Apple Inc.",
+    "insiderName": "Cook Timothy D",
+    "insiderCik": "0001214156",
+    "accessionNumber": "0001234567-26-000001",
+    "securityTitle": "Common Stock",
+    "transactionCode": "P",
+    "sharesAmount": 1000.0,
+    "pricePerShare": 212.45,
+    "sharesOwnedAfter": 5000.0,
+    "directIndirect": "D",
+    "isDerivative": False,
+    "transactionDate": "2026-01-15T00:00:00Z",
+    "periodOfReport": "2026-01-15T00:00:00Z",
+}
+
+INSIDER = {
+    "cik": "0001214156",
+    "name": "Cook Timothy D",
+    "isDirector": False,
+    "isOfficer": True,
+    "isTenPercentOwner": False,
+    "officerTitle": "CEO",
+    "totalFilings": 42,
+}
+
+COMPANY = {
+    "cik": "0000320193",
+    "name": "Apple Inc.",
+    "ticker": "AAPL",
+    "exchange": "NASDAQ",
+    "totalFilings": 100,
+    "activeInsiders": 12,
+}
+
+SIGNAL = {
+    "ticker": "AAPL",
+    "companyName": "Apple Inc.",
+    "signalDate": "2026-01-15",
+    "buySellRatio": 2.5,
+    "isClusterBuy": True,
+    "isClusterSell": False,
+    "insiderCount": 4,
+}
+
+
+@pytest.fixture
+def client():
+    with Form4ApiClient("test-key", max_retries=0) as c:
+        yield c
+
+
+# ── transactions ───────────────────────────────────────────────────────────────
+
+@respx.mock
+def test_transactions_list_returns_typed_objects(client):
+    respx.get(f"{BASE}/v1/transactions").mock(return_value=httpx.Response(200, json=[TX]))
+    results = client.transactions.list()
+    assert len(results) == 1
+    assert isinstance(results[0], Transaction)
+    assert results[0].ticker == "AAPL"
+    assert results[0].company_name == "Apple Inc."
+    assert results[0].insider_cik == "0001214156"
+    assert results[0].transaction_code == "P"
+
+
+@respx.mock
+def test_transactions_list_sends_filters(client):
+    route = respx.get(f"{BASE}/v1/transactions").mock(return_value=httpx.Response(200, json=[]))
+    client.transactions.list(ticker="AAPL", code="P", from_date="2026-01-01", per_page=10)
+    assert route.called
+    qs = dict(route.calls[0].request.url.params)
+    assert qs["ticker"] == "AAPL"
+    assert qs["code"] == "P"
+    assert qs["from"] == "2026-01-01"
+    assert qs["per_page"] == "10"
+
+
+@respx.mock
+def test_transactions_paginate_stops_on_short_page(client):
+    respx.get(f"{BASE}/v1/transactions").mock(side_effect=[
+        httpx.Response(200, json=[TX]),
+        httpx.Response(200, json=[]),
+    ])
+    pages = list(client.transactions.paginate(per_page=1))
+    assert len(pages) == 1
+    assert pages[0][0].ticker == "AAPL"
+
+
+# ── insiders ──────────────────────────────────────────────────────────────────
+
+@respx.mock
+def test_insiders_get_returns_typed_object(client):
+    respx.get(f"{BASE}/v1/insiders/0001214156").mock(return_value=httpx.Response(200, json=INSIDER))
+    result = client.insiders.get("0001214156")
+    assert isinstance(result, Insider)
+    assert result.cik == "0001214156"
+    assert result.is_officer is True
+    assert result.total_filings == 42
+
+
+@respx.mock
+def test_insiders_transactions_returns_list(client):
+    respx.get(f"{BASE}/v1/insiders/0001214156/transactions").mock(
+        return_value=httpx.Response(200, json=[TX])
+    )
+    results = client.insiders.transactions("0001214156")
+    assert len(results) == 1
+    assert isinstance(results[0], Transaction)
+
+
+# ── companies ─────────────────────────────────────────────────────────────────
+
+@respx.mock
+def test_companies_get_returns_typed_object(client):
+    respx.get(f"{BASE}/v1/companies/AAPL").mock(return_value=httpx.Response(200, json=COMPANY))
+    result = client.companies.get("AAPL")
+    assert isinstance(result, Company)
+    assert result.ticker == "AAPL"
+    assert result.total_filings == 100
+    assert result.active_insiders == 12
+
+
+@respx.mock
+def test_companies_insiders_returns_list(client):
+    respx.get(f"{BASE}/v1/companies/AAPL/insiders").mock(
+        return_value=httpx.Response(200, json=[INSIDER])
+    )
+    results = client.companies.insiders("AAPL")
+    assert len(results) == 1
+    assert isinstance(results[0], Insider)
+
+
+# ── signals ───────────────────────────────────────────────────────────────────
+
+@respx.mock
+def test_signals_list_returns_typed_objects(client):
+    respx.get(f"{BASE}/v1/signals").mock(return_value=httpx.Response(200, json=[SIGNAL]))
+    results = client.signals.list(ticker="AAPL")
+    assert len(results) == 1
+    assert isinstance(results[0], InsiderSignal)
+    assert results[0].is_cluster_buy is True
+    assert results[0].buy_sell_ratio == 2.5
+
+
+# ── error handling ────────────────────────────────────────────────────────────
+
+@respx.mock
+def test_401_raises_auth_error(client):
+    respx.get(f"{BASE}/v1/transactions").mock(
+        return_value=httpx.Response(401, json={"error": {"code": "INVALID_API_KEY", "message": "Bad key"}})
+    )
+    with pytest.raises(AuthError) as exc:
+        client.transactions.list()
+    assert exc.value.status_code == 401
+    assert exc.value.error_code == "INVALID_API_KEY"
+
+
+@respx.mock
+def test_402_raises_plan_error(client):
+    respx.get(f"{BASE}/v1/signals").mock(
+        return_value=httpx.Response(402, json={"error": {"code": "PLAN_REQUIRED", "message": "Upgrade"}, "requiredPlan": "Business"})
+    )
+    with pytest.raises(PlanError) as exc:
+        client.signals.list()
+    assert exc.value.required_plan == "Business"
+
+
+@respx.mock
+def test_404_raises_not_found_error(client):
+    respx.get(f"{BASE}/v1/insiders/0000000000").mock(
+        return_value=httpx.Response(404, json={"error": {"code": "NOT_FOUND", "message": "Not found"}})
+    )
+    with pytest.raises(NotFoundError):
+        client.insiders.get("0000000000")
+
+
+@respx.mock
+def test_429_raises_rate_limit_error_with_retry_after(client):
+    respx.get(f"{BASE}/v1/transactions").mock(
+        return_value=httpx.Response(
+            429,
+            headers={"Retry-After": "42"},
+            json={"error": {"code": "RATE_LIMIT_EXCEEDED", "message": "Slow down"}},
+        )
+    )
+    with pytest.raises(RateLimitError) as exc:
+        client.transactions.list()
+    assert exc.value.retry_after == 42
+
+
+@respx.mock
+def test_500_raises_form4_api_error(client):
+    respx.get(f"{BASE}/v1/transactions").mock(return_value=httpx.Response(500, json={}))
+    with pytest.raises(Form4ApiError) as exc:
+        client.transactions.list()
+    assert exc.value.status_code == 500
+
+
+# ── retries ───────────────────────────────────────────────────────────────────
+
+@respx.mock
+def test_retries_on_5xx_then_succeeds():
+    with Form4ApiClient("test-key", max_retries=1) as client:
+        respx.get(f"{BASE}/v1/transactions").mock(side_effect=[
+            httpx.Response(503, json={}),
+            httpx.Response(200, json=[TX]),
+        ])
+        results = client.transactions.list()
+    assert len(results) == 1
+
+
+@respx.mock
+def test_no_retry_on_4xx():
+    call_count = 0
+
+    def handler(_):
+        nonlocal call_count
+        call_count += 1
+        return httpx.Response(401, json={"error": {"code": "INVALID_API_KEY", "message": "Bad"}})
+
+    with Form4ApiClient("test-key", max_retries=2) as client:
+        respx.get(f"{BASE}/v1/transactions").mock(side_effect=handler)
+        with pytest.raises(AuthError):
+            client.transactions.list()
+
+    assert call_count == 1  # no retries on 401
+
+
+# ── webhook verification ──────────────────────────────────────────────────────
+
+def test_verify_webhook_valid_signature():
+    import hashlib, hmac as _hmac
+    payload = b'{"type":"TransactionFiled"}'
+    secret = "mysecret"
+    sig = "sha256=" + _hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
+    assert verify_webhook(payload, sig, secret) is True
+
+
+def test_verify_webhook_invalid_signature():
+    assert verify_webhook(b"payload", "sha256=badhash", "mysecret") is False
+
+
+def test_verify_webhook_accepts_str_payload():
+    import hashlib, hmac as _hmac
+    payload = '{"type":"TransactionFiled"}'
+    secret = "mysecret"
+    sig = "sha256=" + _hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
+    assert verify_webhook(payload, sig, secret) is True