Metadata-Version: 2.4
Name: balanceproof
Version: 0.1.1
Summary: SEC fundamentals that prove they add up: checked balance sheets, income statements and cash flow, point-in-time.
License-Expression: MIT
Project-URL: Homepage, https://balanceproof.dev
Project-URL: Documentation, https://balanceproof.dev/api
Keywords: sec,edgar,xbrl,fundamentals,balance sheet,backtesting,point-in-time
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == "pandas"

# balanceproof

Python client for [BalanceProof](https://balanceproof.dev): US public-company
fundamentals from SEC EDGAR, where each balance sheet, income statement and
cash flow is checked against its own totals when the filing reports the lines
needed (otherwise it is marked not testable instead of passing), and a filing
that does not add up is flagged with the reason instead of passed through.

```bash
pip install "balanceproof[pandas]"
```

```python
import balanceproof as bp

client = bp.Client("YOUR_KEY")        # free key: https://balanceproof.dev/dashboard
                                      # or set BALANCEPROOF_API_KEY

client.balance_sheet("AAPL")
client.statements("AAPL", period="quarterly")

# The balance sheet's verdict, also returned as `check` inside balance_sheet().
v = client.check("CELH")
v["identity_status"]      # "balanced", "missing_tag", "broken", "not_testable", ...
v["reconciles"]           # True / False, or None when the filing cannot be tested
v["attribution"]          # "none", "filer", "extraction" (a line we did not read), "unknown"
if v["attribution"] == "extraction":
    ...                   # the filer's own totals agree: use the stated totals

# Point-in-time (Pro and above): only what had been filed by that date,
# so a backtest never sees a figure before it was public.
client.balance_sheet("AAPL", as_of="2025-03-01")

# A pandas panel, one row per company and period.
df = client.panel(["AAPL", "MSFT", "KO"], ["revenue", "net_income", "operating_cash_flow"],
                  period="quarterly")
clean = df[df.checks_failed.str.len() == 0]      # drop periods that failed a check

# Failed checks and restatements across every company (Pro: 90 days, Business: all).
feed = client.exceptions(type="restatement")
client.to_frame(feed)
```

Derived figures (Q4 as the year minus nine months, Q2/Q3 cash flow from
year-to-date filings) are listed in each period's `derived`.

A call that needs a higher plan raises `balanceproof.PlanRequired`, whose
`required_plan` names it.
