beatandraise 0.1.0__tar.gz

beatandraise-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/

beatandraise-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iterative Works GmbH
+
+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.

beatandraise-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: beatandraise
+Version: 0.1.0
+Summary: Python client for the beatandraise.com SEC Filings API: the whole SEC EDGAR archive, 10-K/10-Q/8-K Items, XBRL financial statements, Form 4 insider trades and 13F holders.
+Project-URL: Homepage, https://beatandraise.com/sec-filings-api
+Project-URL: Documentation, https://beatandraise.com/sec-filings-api/docs
+Project-URL: Guides, https://beatandraise.com/sec-filings-api/guides
+Project-URL: API reference (OpenAPI), https://beatandraise.com/api/v1/openapi.json
+Project-URL: Source, https://github.com/mchennupati/beatandraise-python
+Author-email: Iterative Works GmbH <support@beatandraise.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 10-k,10-q,13f,8-k,edgar,financial-statements,form-4,insider-trading,llm,sec,sec-api,sec-filings,xbrl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# beatandraise: Python client for the SEC Filings API
+
+Python client for the [beatandraise.com SEC Filings API](https://beatandraise.com/sec-filings-api), an SEC EDGAR API designed for LLMs. It covers:
+
+- **The whole EDGAR archive.** Every filing since 1993, about 18.8 million, new filings within minutes, with every document as text.
+- **10-K, 10-Q, 8-K and 20-F Items.** Risk Factors, MD&A, or any 8-K Item, found by its heading.
+- **XBRL financial statements.** As the company presented them, with each line's tag and a link to the figure.
+- **Ownership data.** Form 4 insider transactions, 13F institutional holders and portfolios, and shares outstanding with splits.
+- **Every SEC XML form as JSON.** Form D, 144, 13D/G, N-PX and others.
+- **Verification.** Checks for quotes, figures and citations against the filing.
+
+Every result names the filing it came from. The package uses only the Python standard library and needs Python 3.9 or later.
+
+```bash
+pip install beatandraise
+export BEATANDRAISE_API_KEY=bar_...   # free key: https://beatandraise.com/api-keys
+```
+
+## Quickstart
+
+```python
+from beatandraise import Client
+
+api = Client()  # reads BEATANDRAISE_API_KEY
+
+# Find a company and its latest 10-K
+apple = api.search_companies("AAPL")
+tenk = api.filings(cik="0000320193", form="10-K", limit=1)["filings"][0]
+acc = tenk["accession_number"]
+
+# Risk Factors (Item 1A) as text: the section itself, not the table of contents
+risk_factors = api.item(acc, "1A")
+
+# Income statement across the last five 10-Ks
+history = api.financial_history(cik="0000320193", period="annual", statements="income", limit=5)
+
+# Who owns it: % held by 13F filers, top holders, buyers and sellers
+holders = api.institutional_holders("AAPL")
+q = holders["quarters"][0]
+print(q["period"], q["share_classes"][0]["pct_of_class"], "% held by", q["holders"], "13F filers")
+```
+
+## Examples
+
+```python
+# Insider sales and purchases, with the Rule 10b5-1 flag and footnotes
+rows = api.insider_transactions(cik="0001045810", from_="2026-09-01", include_footnotes=True)["transactions"]
+sales = [r for r in rows if r["transaction_code"] == "S"]
+
+# 8-K officer changes (Item 5.02) across all companies, with the Item's text
+events = api.filings(item="5.02", item_text="5.02", from_="2026-11-01", limit=25)
+
+# Full-text search, one result per company
+hits = api.search('"going concern"', form="10-K", year=2026, by_company=True)
+
+# Lines in a filing that mention a term
+lines = api.search_document("0000320193", acc, q="tariffs")
+
+# Statement lines with XBRL concept, value in full units and a highlight link
+stmts = api.statements("0000320193", acc, include_tags=True)
+
+# Check a figure before you quote it
+check = api.verify_figure("0000320193", acc, value="$478.8 billion", label="Net sales")
+
+# Any endpoint by path
+api.get("/fiscal-calendar", cik="0000320193")
+```
+
+Parameters named `from` in the API are `from_` in Python. Lists are sent comma-separated (`statements=["income", "cash_flow"]`).
+
+## Methods
+
+| Method | Endpoint |
+|---|---|
+| `filings(cik, form, from_, to, item, item_text, limit, offset)` | `GET /filings` |
+| `search(q, form, cik, year, limit, page, by_company)` | `GET /search` |
+| `search_companies(q)`, `company(cik)` | `GET /company/search`, `/company/{cik}` |
+| `identifiers(ticker, cik, cusip)` | `GET /identifiers` |
+| `sic(...)` | `GET /sic` |
+| `fiscal_calendar(cik, fiscal_year, from_, to)` | `GET /fiscal-calendar` |
+| `filing(acc)`, `filing_tables(acc)`, `files(acc)` | `GET /filing/{acc}`, `/filing/{acc}/tables`, `/files/{acc}` |
+| `download(acc, filename)` (bytes) | `GET /files/{acc}/{filename}` |
+| `document(cik, acc, filename, markdown=True)` (text) | `GET /document/{cik}/{acc}/{filename}` |
+| `search_document(cik, acc, q, filename, context)` | `GET /document/search/...` |
+| `items(acc)`, `item(acc, item)` (text) | `GET /items/{acc}`, `/items/{acc}/{item}` |
+| `form_data(cik, form, ...)` | `GET /form-data` |
+| `statements(cik, acc, include_tags)` | `GET /statements/{cik}/{acc}` |
+| `financial_history(cik, period, statements, limit, fiscal_year, fiscal_period, include_tags)` | `GET /financial-history` |
+| `insider_transactions(cik, from_, to, include_table_ii, include_footnotes)` | `GET /insider-transactions` |
+| `shares_outstanding(cik, share_class, from_, to)` | `GET /shares-outstanding` |
+| `holdings(cik, period)` | `GET /holdings/{cik}` |
+| `institutional_holders(company, quarters, holder, detail)` | `GET /institutional-holders/{company}` |
+| `verify_quote(cik, acc, filename, quote)` | `GET /document/verify/...` |
+| `verify_figure(cik, acc, value, label, filename)` | `GET /document/verify-figure/...` |
+| `figures(cik, acc, filename, near)` | `GET /document/figures/...` |
+| `check_citations(text)` | `POST /check-citations` |
+| `account()` | `GET /account` |
+
+The full reference, with an example response for each endpoint, is the [OpenAPI spec](https://beatandraise.com/api/v1/openapi.json). You can also [try any request in the browser](https://beatandraise.com/sec-filings-api/try).
+
+## Errors and limits
+
+A refused request raises `beatandraise.APIError` with `.status` and `.body`. Requests refused for rate (429) or by a busy server (502-504) are retried twice, honouring `Retry-After`. The free plan includes 100 successful requests at up to 10 a second; Pro is unlimited at 20 a second. See [plans](https://beatandraise.com/sec-filings-api#plans).
+
+## Using it from an LLM
+
+To give Claude, ChatGPT, Cursor or Codex the same data with no code, add the MCP server at `https://mcp.beatandraise.com/mcp`. Setup for each client is at [beatandraise.com/mcp](https://beatandraise.com/mcp).
+
+## Guides
+
+- [Who owns a stock: 13F institutional holders by API](https://beatandraise.com/sec-filings-api/guides/13f-institutional-holders-api)
+- [Get a 10-K's Risk Factors (Item 1A) by API](https://beatandraise.com/sec-filings-api/guides/10-k-risk-factors-api)
+- [Insider trading data by API: Form 4 transactions as filed](https://beatandraise.com/sec-filings-api/guides/insider-trading-form-4-api)
+- [Financial statements from SEC XBRL by API](https://beatandraise.com/sec-filings-api/guides/xbrl-financial-statements-api)
+
+Questions: support@beatandraise.com. Data source: SEC EDGAR. Nothing here is investment advice.

beatandraise-0.1.0/README.md

@@ -0,0 +1,116 @@
+# beatandraise: Python client for the SEC Filings API
+
+Python client for the [beatandraise.com SEC Filings API](https://beatandraise.com/sec-filings-api), an SEC EDGAR API designed for LLMs. It covers:
+
+- **The whole EDGAR archive.** Every filing since 1993, about 18.8 million, new filings within minutes, with every document as text.
+- **10-K, 10-Q, 8-K and 20-F Items.** Risk Factors, MD&A, or any 8-K Item, found by its heading.
+- **XBRL financial statements.** As the company presented them, with each line's tag and a link to the figure.
+- **Ownership data.** Form 4 insider transactions, 13F institutional holders and portfolios, and shares outstanding with splits.
+- **Every SEC XML form as JSON.** Form D, 144, 13D/G, N-PX and others.
+- **Verification.** Checks for quotes, figures and citations against the filing.
+
+Every result names the filing it came from. The package uses only the Python standard library and needs Python 3.9 or later.
+
+```bash
+pip install beatandraise
+export BEATANDRAISE_API_KEY=bar_...   # free key: https://beatandraise.com/api-keys
+```
+
+## Quickstart
+
+```python
+from beatandraise import Client
+
+api = Client()  # reads BEATANDRAISE_API_KEY
+
+# Find a company and its latest 10-K
+apple = api.search_companies("AAPL")
+tenk = api.filings(cik="0000320193", form="10-K", limit=1)["filings"][0]
+acc = tenk["accession_number"]
+
+# Risk Factors (Item 1A) as text: the section itself, not the table of contents
+risk_factors = api.item(acc, "1A")
+
+# Income statement across the last five 10-Ks
+history = api.financial_history(cik="0000320193", period="annual", statements="income", limit=5)
+
+# Who owns it: % held by 13F filers, top holders, buyers and sellers
+holders = api.institutional_holders("AAPL")
+q = holders["quarters"][0]
+print(q["period"], q["share_classes"][0]["pct_of_class"], "% held by", q["holders"], "13F filers")
+```
+
+## Examples
+
+```python
+# Insider sales and purchases, with the Rule 10b5-1 flag and footnotes
+rows = api.insider_transactions(cik="0001045810", from_="2026-09-01", include_footnotes=True)["transactions"]
+sales = [r for r in rows if r["transaction_code"] == "S"]
+
+# 8-K officer changes (Item 5.02) across all companies, with the Item's text
+events = api.filings(item="5.02", item_text="5.02", from_="2026-11-01", limit=25)
+
+# Full-text search, one result per company
+hits = api.search('"going concern"', form="10-K", year=2026, by_company=True)
+
+# Lines in a filing that mention a term
+lines = api.search_document("0000320193", acc, q="tariffs")
+
+# Statement lines with XBRL concept, value in full units and a highlight link
+stmts = api.statements("0000320193", acc, include_tags=True)
+
+# Check a figure before you quote it
+check = api.verify_figure("0000320193", acc, value="$478.8 billion", label="Net sales")
+
+# Any endpoint by path
+api.get("/fiscal-calendar", cik="0000320193")
+```
+
+Parameters named `from` in the API are `from_` in Python. Lists are sent comma-separated (`statements=["income", "cash_flow"]`).
+
+## Methods
+
+| Method | Endpoint |
+|---|---|
+| `filings(cik, form, from_, to, item, item_text, limit, offset)` | `GET /filings` |
+| `search(q, form, cik, year, limit, page, by_company)` | `GET /search` |
+| `search_companies(q)`, `company(cik)` | `GET /company/search`, `/company/{cik}` |
+| `identifiers(ticker, cik, cusip)` | `GET /identifiers` |
+| `sic(...)` | `GET /sic` |
+| `fiscal_calendar(cik, fiscal_year, from_, to)` | `GET /fiscal-calendar` |
+| `filing(acc)`, `filing_tables(acc)`, `files(acc)` | `GET /filing/{acc}`, `/filing/{acc}/tables`, `/files/{acc}` |
+| `download(acc, filename)` (bytes) | `GET /files/{acc}/{filename}` |
+| `document(cik, acc, filename, markdown=True)` (text) | `GET /document/{cik}/{acc}/{filename}` |
+| `search_document(cik, acc, q, filename, context)` | `GET /document/search/...` |
+| `items(acc)`, `item(acc, item)` (text) | `GET /items/{acc}`, `/items/{acc}/{item}` |
+| `form_data(cik, form, ...)` | `GET /form-data` |
+| `statements(cik, acc, include_tags)` | `GET /statements/{cik}/{acc}` |
+| `financial_history(cik, period, statements, limit, fiscal_year, fiscal_period, include_tags)` | `GET /financial-history` |
+| `insider_transactions(cik, from_, to, include_table_ii, include_footnotes)` | `GET /insider-transactions` |
+| `shares_outstanding(cik, share_class, from_, to)` | `GET /shares-outstanding` |
+| `holdings(cik, period)` | `GET /holdings/{cik}` |
+| `institutional_holders(company, quarters, holder, detail)` | `GET /institutional-holders/{company}` |
+| `verify_quote(cik, acc, filename, quote)` | `GET /document/verify/...` |
+| `verify_figure(cik, acc, value, label, filename)` | `GET /document/verify-figure/...` |
+| `figures(cik, acc, filename, near)` | `GET /document/figures/...` |
+| `check_citations(text)` | `POST /check-citations` |
+| `account()` | `GET /account` |
+
+The full reference, with an example response for each endpoint, is the [OpenAPI spec](https://beatandraise.com/api/v1/openapi.json). You can also [try any request in the browser](https://beatandraise.com/sec-filings-api/try).
+
+## Errors and limits
+
+A refused request raises `beatandraise.APIError` with `.status` and `.body`. Requests refused for rate (429) or by a busy server (502-504) are retried twice, honouring `Retry-After`. The free plan includes 100 successful requests at up to 10 a second; Pro is unlimited at 20 a second. See [plans](https://beatandraise.com/sec-filings-api#plans).
+
+## Using it from an LLM
+
+To give Claude, ChatGPT, Cursor or Codex the same data with no code, add the MCP server at `https://mcp.beatandraise.com/mcp`. Setup for each client is at [beatandraise.com/mcp](https://beatandraise.com/mcp).
+
+## Guides
+
+- [Who owns a stock: 13F institutional holders by API](https://beatandraise.com/sec-filings-api/guides/13f-institutional-holders-api)
+- [Get a 10-K's Risk Factors (Item 1A) by API](https://beatandraise.com/sec-filings-api/guides/10-k-risk-factors-api)
+- [Insider trading data by API: Form 4 transactions as filed](https://beatandraise.com/sec-filings-api/guides/insider-trading-form-4-api)
+- [Financial statements from SEC XBRL by API](https://beatandraise.com/sec-filings-api/guides/xbrl-financial-statements-api)
+
+Questions: support@beatandraise.com. Data source: SEC EDGAR. Nothing here is investment advice.

beatandraise-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "beatandraise"
+version = "0.1.0"
+description = "Python client for the beatandraise.com SEC Filings API: the whole SEC EDGAR archive, 10-K/10-Q/8-K Items, XBRL financial statements, Form 4 insider trades and 13F holders."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Iterative Works GmbH", email = "support@beatandraise.com" }]
+keywords = ["sec", "edgar", "sec-api", "sec-filings", "10-k", "10-q", "8-k", "xbrl", "13f", "form-4", "insider-trading", "financial-statements", "llm"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://beatandraise.com/sec-filings-api"
+Documentation = "https://beatandraise.com/sec-filings-api/docs"
+Guides = "https://beatandraise.com/sec-filings-api/guides"
+"API reference (OpenAPI)" = "https://beatandraise.com/api/v1/openapi.json"
+Source = "https://github.com/mchennupati/beatandraise-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/beatandraise"]

beatandraise-0.1.0/src/beatandraise/__init__.py

@@ -0,0 +1,7 @@
+"""beatandraise: Python client for the beatandraise.com SEC Filings API."""
+
+__version__ = "0.1.0"
+
+from .client import Client, APIError, DEFAULT_BASE_URL  # noqa: E402
+
+__all__ = ["Client", "APIError", "DEFAULT_BASE_URL", "__version__"]

beatandraise-0.1.0/src/beatandraise/client.py

@@ -0,0 +1,281 @@
+"""Client for the beatandraise.com SEC Filings API (https://beatandraise.com/sec-filings-api).
+
+Standard library only. Every method maps to one endpoint of https://beatandraise.com/api/v1/openapi.json
+and returns the decoded JSON (a dict), except the methods that return a document's text or a file's bytes.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional, Union
+
+from . import __version__
+
+DEFAULT_BASE_URL = "https://beatandraise.com/api/v1"
+
+
+class APIError(Exception):
+    """A request the API refused or failed. `status` is the HTTP status, `body` the decoded error body."""
+
+    def __init__(self, status: int, body: Any, url: str):
+        self.status = status
+        self.body = body
+        self.url = url
+        if isinstance(body, dict):
+            msg = body.get("message") or body.get("error") or json.dumps(body)
+        else:
+            msg = str(body)[:500]
+        super().__init__(f"HTTP {status}: {msg}")
+
+
+def _clean(params: Dict[str, Any]) -> Dict[str, str]:
+    out = {}
+    for k, v in params.items():
+        if v is None:
+            continue
+        k = k.rstrip("_")  # from_ -> from
+        if isinstance(v, bool):
+            v = "true" if v else "false"
+        elif isinstance(v, (list, tuple)):
+            v = ",".join(str(x) for x in v)
+        out[k] = str(v)
+    return out
+
+
+def _seg(s: Any) -> str:
+    return urllib.parse.quote(str(s), safe="")
+
+
+class Client:
+    """SEC EDGAR filings and the structured data built on them.
+
+    >>> from beatandraise import Client
+    >>> api = Client()                      # reads BEATANDRAISE_API_KEY
+    >>> api.filings(cik="0000320193", form="10-K", limit=1)
+
+    Get a free key at https://beatandraise.com/api-keys.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+    ):
+        self.api_key = api_key or os.environ.get("BEATANDRAISE_API_KEY") or os.environ.get("BAR_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "No API key: pass api_key= or set BEATANDRAISE_API_KEY. "
+                "Create a free key at https://beatandraise.com/api-keys"
+            )
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    # -- transport ---------------------------------------------------------------------------------------
+
+    def _request(self, method: str, path: str, params: Optional[Dict[str, Any]] = None,
+                 body: Optional[Dict[str, Any]] = None, raw: bool = False):
+        url = self.base_url + path
+        q = _clean(params or {})
+        if q:
+            url += "?" + urllib.parse.urlencode(q)
+        data = json.dumps(body).encode() if body is not None else None
+        headers = {
+            "X-API-Key": self.api_key,
+            "User-Agent": f"beatandraise-python/{__version__}",
+            "Accept": "application/json, text/markdown, */*",
+        }
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        attempt = 0
+        while True:
+            req = urllib.request.Request(url, data=data, method=method, headers=headers)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    payload = resp.read()
+                    if raw:
+                        return payload, dict(resp.headers)
+                    ctype = resp.headers.get("Content-Type", "")
+                    if "json" in ctype:
+                        return json.loads(payload)
+                    return payload.decode("utf-8", "replace")
+            except urllib.error.HTTPError as e:
+                payload = e.read()
+                try:
+                    err = json.loads(payload)
+                except ValueError:
+                    err = payload.decode("utf-8", "replace")
+                if e.code in (429, 502, 503, 504) and attempt < self.max_retries:
+                    wait = e.headers.get("Retry-After")
+                    try:
+                        delay = min(float(wait), 30.0) if wait else 1.0 * (2 ** attempt)
+                    except ValueError:
+                        delay = 1.0 * (2 ** attempt)
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+                raise APIError(e.code, err, url) from None
+
+    def get(self, path: str, **params):
+        """Any GET endpoint, e.g. api.get("/company/0000320193")."""
+        return self._request("GET", path, params)
+
+    # -- find ------------------------------------------------------------------------------------------
+
+    def filings(self, cik: Optional[str] = None, form: Optional[str] = None, from_: Optional[str] = None,
+                to: Optional[str] = None, item=None, item_text=None, include_item_text: Optional[bool] = None,
+                item_text_chars: Optional[int] = None, limit: Optional[int] = None, offset: Optional[int] = None):
+        """List filings by company, form type and date; for 8-Ks, by Item (item="5.02")."""
+        return self._request("GET", "/filings", dict(
+            cik=cik, form=form, from_=from_, to=to, item=item, item_text=item_text,
+            include_item_text=include_item_text, item_text_chars=item_text_chars, limit=limit, offset=offset))
+
+    def search(self, q: str, form: Optional[str] = None, cik: Optional[str] = None, year: Optional[int] = None,
+               limit: Optional[int] = None, page: Optional[int] = None, by_company: Optional[bool] = None):
+        """Full-text search across filings (2020 on). by_company=True gives each company's best match."""
+        return self._request("GET", "/search", dict(q=q, form=form, cik=cik, year=year, limit=limit,
+                                                    page=page, by_company=by_company))
+
+    def search_companies(self, q: str, limit: Optional[int] = None):
+        """Find a company's CIK by name or ticker."""
+        return self._request("GET", "/company/search", dict(q=q, limit=limit))
+
+    def company(self, cik: str):
+        return self._request("GET", f"/company/{_seg(cik)}")
+
+    def identifiers(self, ticker: Optional[str] = None, cik: Optional[str] = None, cusip: Optional[str] = None,
+                    limit: Optional[int] = None):
+        """Ticker, CIK and CUSIP: give one, get the others."""
+        return self._request("GET", "/identifiers", dict(ticker=ticker, cik=cik, cusip=cusip, limit=limit))
+
+    def sic(self, **params):
+        """SIC industry codes and the companies in them (find=, code=, exchange=, ...)."""
+        return self._request("GET", "/sic", params)
+
+    def fiscal_calendar(self, cik: str, fiscal_year: Optional[int] = None, from_: Optional[str] = None,
+                        to: Optional[str] = None, limit: Optional[int] = None):
+        """Every fiscal quarter a company reported, with exact start and end dates."""
+        return self._request("GET", "/fiscal-calendar", dict(cik=cik, fiscal_year=fiscal_year, from_=from_,
+                                                             to=to, limit=limit))
+
+    # -- read ------------------------------------------------------------------------------------------
+
+    def filing(self, accession: str):
+        """One filing's metadata and its files."""
+        return self._request("GET", f"/filing/{_seg(accession)}")
+
+    def filing_tables(self, accession: str):
+        """The XBRL viewer pages (R-pages) of a filing."""
+        return self._request("GET", f"/filing/{_seg(accession)}/tables")
+
+    def files(self, accession: str):
+        return self._request("GET", f"/files/{_seg(accession)}")
+
+    def download(self, accession: str, filename: str) -> bytes:
+        """A stored file's bytes, as filed (counts against the plan's download allowance)."""
+        payload, _ = self._request("GET", f"/files/{_seg(accession)}/{_seg(filename)}", raw=True)
+        return payload
+
+    def document(self, cik: str, accession: str, filename: str, markdown: bool = True) -> str:
+        """A document's text (markdown) or, with markdown=False, its HTML/XML."""
+        return self._request("GET", f"/document/{_seg(cik)}/{_seg(accession)}/{_seg(filename)}",
+                             dict(get_markdown=markdown))
+
+    def search_document(self, cik: str, accession: str, q: str, filename: Optional[str] = None,
+                        context: Optional[int] = None):
+        """Lines matching terms within one filing (every readable document, or one filename)."""
+        path = f"/document/search/{_seg(cik)}/{_seg(accession)}"
+        if filename:
+            path += f"/{_seg(filename)}"
+        return self._request("GET", path, dict(q=q, context=context))
+
+    def items(self, accession: str):
+        """The Items of a 10-K, 10-Q, 8-K or 20-F, with where each begins."""
+        return self._request("GET", f"/items/{_seg(accession)}")
+
+    def item(self, accession: str, item: str, part: Optional[str] = None, format: Optional[str] = None) -> str:
+        """One Item's text, e.g. item(acc, "1A") for Risk Factors or "7" for MD&A."""
+        return self._request("GET", f"/items/{_seg(accession)}/{_seg(item)}", dict(part=part, format=format))
+
+    # -- structured ------------------------------------------------------------------------------------
+
+    def form_data(self, cik: str, form: str, **params):
+        """Every filing of one XML form (Form 4, 144, 13F, D...) for a CIK as JSON or XML."""
+        return self._request("GET", "/form-data", dict(cik=cik, form=form, **params))
+
+    def statements(self, cik: str, accession: str, include_tags: Optional[bool] = None):
+        """Income statement, balance sheet and cash flow of one 10-K/10-Q/20-F/40-F, as presented."""
+        return self._request("GET", f"/statements/{_seg(cik)}/{_seg(accession)}",
+                             dict(include_tags=include_tags))
+
+    def financial_history(self, cik: str, period: Optional[str] = None, statements=None,
+                          limit: Optional[int] = None, before: Optional[str] = None,
+                          fiscal_year: Optional[int] = None, fiscal_period: Optional[str] = None,
+                          include_tags: Optional[bool] = None):
+        """The same statements across a company's last several annual (or quarterly) reports."""
+        return self._request("GET", "/financial-history", dict(
+            cik=cik, period=period, statements=statements, limit=limit, before=before,
+            fiscal_year=fiscal_year, fiscal_period=fiscal_period, include_tags=include_tags))
+
+    def insider_transactions(self, cik: str, from_: Optional[str] = None, to: Optional[str] = None,
+                             limit: Optional[int] = None, offset: Optional[int] = None,
+                             include_table_ii: Optional[bool] = None, include_footnotes: Optional[bool] = None):
+        """Form 4 transactions, newest first, as filed."""
+        return self._request("GET", "/insider-transactions", dict(
+            cik=cik, from_=from_, to=to, limit=limit, offset=offset,
+            include_table_ii=include_table_ii, include_footnotes=include_footnotes))
+
+    def shares_outstanding(self, cik: str, share_class: Optional[str] = None, from_: Optional[str] = None,
+                           to: Optional[str] = None):
+        """Cover-page share counts per class over time, with stock splits."""
+        return self._request("GET", "/shares-outstanding", dict(cik=cik, share_class=share_class,
+                                                                from_=from_, to=to))
+
+    def holdings(self, cik: str, period: Optional[str] = None, limit: Optional[int] = None,
+                 offset: Optional[int] = None):
+        """One 13F filer's positions for a report period."""
+        return self._request("GET", f"/holdings/{_seg(cik)}", dict(period=period, limit=limit, offset=offset))
+
+    def institutional_holders(self, company: str, quarters: Optional[int] = None, holder: Optional[str] = None,
+                              limit: Optional[int] = None, detail: Optional[str] = None):
+        """Who holds a company (ticker or CIK) by 13F, quarter by quarter."""
+        return self._request("GET", f"/institutional-holders/{_seg(company)}", dict(
+            quarters=quarters, holder=holder, limit=limit, detail=detail))
+
+    # -- verify ----------------------------------------------------------------------------------------
+
+    def verify_quote(self, cik: str, accession: str, filename: str, quote: str):
+        """Is this exact text in the document? Returns highlight links to each occurrence."""
+        return self._request("GET", f"/document/verify/{_seg(cik)}/{_seg(accession)}/{_seg(filename)}",
+                             dict(quote=quote))
+
+    def verify_figure(self, cik: str, accession: str, value: str, label: Optional[str] = None,
+                      filename: Optional[str] = None):
+        """Is this figure in the filing, however it is written ("$416.2 billion" vs "416,161")?"""
+        path = f"/document/verify-figure/{_seg(cik)}/{_seg(accession)}"
+        if filename:
+            path += f"/{_seg(filename)}"
+        return self._request("GET", path, dict(value=value, label=label))
+
+    def figures(self, cik: str, accession: str, filename: str, near: Optional[str] = None,
+                limit: Optional[int] = None):
+        """A document's numbers with their labels and refs, for citing."""
+        return self._request("GET", f"/document/figures/{_seg(cik)}/{_seg(accession)}/{_seg(filename)}",
+                             dict(near=near, limit=limit))
+
+    def check_citations(self, text: str):
+        """Check every [ref:...] and [calc: ...] citation in a draft against the filings."""
+        return self._request("POST", "/check-citations", body={"text": text})
+
+    # -- account ---------------------------------------------------------------------------------------
+
+    def account(self):
+        """Your plan, limits and usage."""
+        return self._request("GET", "/account")

beatandraise-0.1.0/tests/test_live.py

@@ -0,0 +1,57 @@
+"""Live smoke test: runs the README's calls against the API.
+
+BEATANDRAISE_API_KEY=bar_... python -m pytest tests/  (or python tests/test_live.py)
+BEATANDRAISE_BASE_URL overrides the base URL. Skipped without a key.
+"""
+import os
+import unittest
+
+from beatandraise import Client, APIError, DEFAULT_BASE_URL
+
+KEY = os.environ.get("BEATANDRAISE_API_KEY")
+BASE = os.environ.get("BEATANDRAISE_BASE_URL", DEFAULT_BASE_URL)
+APPLE = "0000320193"
+
+
+@unittest.skipUnless(KEY, "set BEATANDRAISE_API_KEY")
+class Live(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.api = Client(KEY, base_url=BASE)
+        cls.acc = cls.api.filings(cik=APPLE, form="10-K", limit=1)["filings"][0]["accession_number"]
+
+    def test_find(self):
+        self.assertTrue(self.api.search_companies("AAPL"))
+        self.assertIn("quarters", self.api.fiscal_calendar(APPLE, limit=4))
+        hits = self.api.search('"going concern"', form="10-K", year=2025, by_company=True, limit=3)
+        self.assertIn("companies_found", hits)
+
+    def test_read(self):
+        items = self.api.items(self.acc)["items"]
+        self.assertTrue(any(i["item"] == "1A" for i in items))
+        text = self.api.item(self.acc, "1A")
+        self.assertIn("Risk Factors", text[:200])
+        self.assertTrue(self.api.search_document(APPLE, self.acc, q="tariffs"))
+
+    def test_structured(self):
+        h = self.api.financial_history(APPLE, period="annual", statements="income", limit=2)
+        self.assertTrue(h["filings"])
+        s = self.api.statements(APPLE, self.acc, include_tags=True)
+        self.assertTrue(any(st.get("lines") for st in s["statements"]))
+        self.assertIn("transactions", self.api.insider_transactions("0001045810", from_="2026-09-01",
+                                                                    include_footnotes=True))
+        self.assertTrue(self.api.institutional_holders("AAPL")["quarters"])
+        self.assertIn("filings", self.api.filings(item="5.02", item_text="5.02", from_="2026-11-01", limit=2))
+
+    def test_verify(self):
+        v = self.api.verify_figure(APPLE, self.acc, value="$478.8 billion", label="Net sales")
+        self.assertTrue(v.get("found"))
+
+    def test_error(self):
+        with self.assertRaises(APIError) as cm:
+            self.api.filing("0000000000-00-000000")
+        self.assertEqual(cm.exception.status, 404)
+
+
+if __name__ == "__main__":
+    unittest.main()