Metadata-Version: 2.5
Name: pit-fundamentals
Version: 0.1.0
Summary: Point-in-time company fundamentals from official regulator filings (US SEC EDGAR, Taiwan TWSE, Korea OpenDART) — as-first-reported, keyed by filing date, exportable. Zero dependencies.
Project-URL: Homepage, https://www.tradingagentapp.com/fundamentals
Project-URL: Documentation, https://www.tradingagentapp.com/developers
Project-URL: Licence terms, https://www.tradingagentapp.com/licences/personal
Author-email: WU Capital Limited <tradingagentapp@gmail.com>
License: MIT
Keywords: EDGAR,OpenDART,PIT,SEC,TWSE,backtesting,factor,financial-data,fundamentals,korea,look-ahead-bias,point-in-time,quant,stock-data,taiwan
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# pit-fundamentals

**Point-in-time company fundamentals from official regulator filings — as
first reported, keyed by filing date, exportable.** Zero dependencies
(pandas optional).

Backtests leak the future when they use restated numbers or use figures
before their filing date. This dataset stores every figure **as it was first
reported** and stamps it with its **filing date**, so `as_of` queries return
exactly what was public on that day.

| Market | Source | Coverage |
|---|---|---|
| US | SEC EDGAR (public domain) | ~6,900 filers · annual + quarterly · 2014→ |
| Taiwan | TWSE OpenAPI (Open Government Data License 1.0) | every listed company · accumulating quarterly |
| Korea | FSS OpenDART | full market · loading |

## Install

```bash
pip install pit-fundamentals
```

## 60-second start (no signup — public demo key built in)

```python
import pit_fundamentals as pf

# TSMC's history, as first reported
rows = pf.fundamentals("2330.TW")

# What a backtest running on 2022-01-01 was allowed to know about Apple
snap = pf.latest("AAPL", as_of="2022-01-01")
print(snap["revenue"])   # FY2021, filed 2021-10-29 — nothing newer leaks

# The scored, resolved prediction panel (history incl. losses; delayed on free)
panel = pf.signals(market="TW", horizon="21d", limit=1000)

# pandas users
df = pf.to_df(rows)
```

The demo key covers **25 flagship tickers (US · TW · KR) at full fidelity** —
full fields, full history. Paid plans unlock every ticker; your code doesn't
change:

```bash
export PIT_FUNDAMENTALS_KEY=ta_live_xxxxxxxx
```

## Pricing & licences

Free / Personal US$29/mo / Commercial US$149/mo / Redistribution US$499/mo —
plans and full licence texts: <https://www.tradingagentapp.com/fundamentals>

What makes the licence unusual: **no export bans, no display-only clause, and
your derived research is yours forever** (explicitly, in writing — including
after cancellation). We ingest from public filings directly, so no upstream
vendor licence forbids you taking the data with you.

## Notes worth knowing

- **Taiwan income statements are cumulative year-to-date** (Taiwan reporting
  convention: Q2 = H1 total). Difference adjacent quarters for single-quarter
  flows. Balance-sheet items are point-in-time as usual.
- Every API response embeds its statutory source attribution (e.g. 臺灣證券
  交易所 under OGDL 1.0).
- Factual, historical data only — no forecasts, no advice, no price/OHLCV.

Docs: <https://www.tradingagentapp.com/developers> ·
Field dictionary and examples included.
