Metadata-Version: 2.4
Name: openbb-tradingagent
Version: 1.0.2
Summary: Company fundamentals from official filings, dated by filing, from tradingagentapp.com for the OpenBB Platform (US SEC EDGAR, Japan EDINET, Taiwan TWSE, Korea FSS OpenDART, France INPI, Belgium NBB, Denmark Business Authority, NZ Charities Register).
License: MIT
Keywords: openbb,fundamentals,filing-date,edgar,edinet,twse,opendart,inpi,private-companies
Author: Trading Agent
Author-email: tradingagentapp@gmail.com
Requires-Python: >=3.10,<4
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: openbb-core (>=1.6.10,<3)
Requires-Dist: openbb-equity (>=1.6.0,<3)
Project-URL: Homepage, https://www.tradingagentapp.com/fundamentals
Description-Content-Type: text/markdown

# Trading Agent provider for OpenBB

Company fundamentals from official regulator filings, each figure dated by
its **filing date** as each market records it (Taiwan: the statutory
deadline; see the
[methodology page](https://www.tradingagentapp.com/fundamentals/methodology))
— inside the OpenBB Platform.

| Market | Source | Coverage |
| --- | --- | --- |
| United States | SEC EDGAR (XBRL) | ~7,000 filers, annual + quarterly, FY2014→ |
| Japan | FSA EDINET (Public Data License 1.0) | 4,955 filers of an annual securities report, listed and unlisted |
| Taiwan | Taiwan Stock Exchange OpenAPI | every listed company |
| Korea | FSS OpenDART | 2,239 listed companies |
| France | INPI Registre national des entreprises | 1,484,946 companies, annual accounts 2017→ |
| Belgium | NBB Central Balance Sheet Office | 673,826 companies, statutory accounts, incl. private companies |
| Denmark | Danish Business Authority | 548,878 companies, published annual reports, 2013→ |
| New Zealand | Charities Register (Charities Services) | 27,100 registered charities, FY2008→ |

Every value is keyed to its **official filing date**, and queries accept an
`as_of` date, so a backtest at date *T* reads only filings dated on or before
*T* (how each market dates a filing: the
[methodology page](https://www.tradingagentapp.com/fundamentals/methodology)).
A later restatement does not replace a stored figure (Korea is an
exception being fixed: see the methodology).

## Install

```bash
pip install openbb openbb-tradingagent
openbb-build   # regenerate the static assets so the provider appears
```

Works with OpenBB 4 (openbb-core 1.6) and OpenBB 5 (openbb-core 2). The
package brings `openbb-equity`, which holds the `obb.equity.fundamental`
commands, so an existing OpenBB install is not downgraded.

## Use

The provider attaches to OpenBB's existing fundamentals commands:

```python
from openbb import obb

# No key needed — the demo tier covers every company's most recent fiscal year.
obb.equity.fundamental.latest_attributes(
    symbol="2330.TW", tag="revenue,net_income", provider="tradingagent"
)

# as_of: AAPL's reported annual revenue from filings dated on or before 2022-01-01
obb.equity.fundamental.historical_attributes(
    symbol="AAPL", tag="revenue", provider="tradingagent", as_of="2022-01-01"
)

# Quarterly rows instead of annual ones; several symbols and tags at once
obb.equity.fundamental.historical_attributes(
    symbol="AAPL,MSFT", tag="revenue,net_income", provider="tradingagent",
    frequency="quarterly",
)
```

`symbol` and `tag` take a comma-separated list (or a Python list).

## The `frequency` parameter

`historical_attributes` follows OpenBB's standard `frequency`, whose default
is `"yearly"`:

| `frequency` | Rows returned |
| --- | --- |
| `"yearly"` (default) | annual rows only (`fiscal_period` = `FY`) |
| `"quarterly"` | quarterly rows only (`Q1`–`Q4`; US and Taiwan only) |
| `None` | both, as stored |

Annual and quarterly rows are never mixed unless you ask for `None`, so a
yearly series can be summed without counting a year twice. `limit` applies
after this filter. Quarterly rows exist for US and Taiwan companies only;
every other market has annual rows only. The filings carry no daily, weekly
or monthly figures, so those values are refused.

Set a key for the full universe:

```python
obb.user.credentials.tradingagent_api_key = "ta_live_…"
```

or in `~/.openbb_platform/user_settings.json`:

```json
{ "credentials": { "tradingagent_api_key": "ta_live_…" } }
```

Without a key the provider falls back to the public `demo` key: every company
at its most recent reported fiscal year, all fields, no signup; about 60 named
companies keep full history as a worked sample. A Personal or Commercial data
licence unlocks full history and the `as_of` query (bulk files come with the
Redistribution Licence) — your code does not change.

Free Data is supplied under the Trading Agent Data Free Licence (https://www.tradingagentapp.com/licences/free); using it means you accept that licence.

## The `as_of` parameter

Every value carries its filing date, and `as_of` filters to
`filed <= as_of`:

```python
# AAPL revenue from filings dated on or before 2022-01-01
obb.equity.fundamental.latest_attributes(
    symbol="AAPL", tag="revenue", provider="tradingagent", as_of="2022-01-01"
)
```

## Fields

`historical_attributes` returns, per row: `date` (period end), `symbol`, `tag`,
`value`, `unit`, `fiscal_year`, `fiscal_period`, `filed`, `form`, `basis`,
`market`, `issuer_id`, `source_attribution`. `latest_attributes` returns
`symbol`, `tag`, `value`, `unit`, `fiscal_year`, `fiscal_period`,
`period_ending`, `filed`, `form`, `basis`, `source_attribution`.

`fiscal_period` is `FY` for an annual row. For a quarterly row (US, Taiwan),
`fiscal_year` and `fiscal_period` are the calendar year and quarter that
contain the period end, not the company's own fiscal quarter: Apple's quarter
ending 2025-12-27 is 2025 Q4, which Apple calls Q1 of fiscal 2026. In
`latest_attributes`, a quarterly `fiscal_period` means one quarter's figure.

The notices that must travel with the data reach the OBBject:
`source_attribution` on every row, the reply's attributions, licence and
depth in `extra["results_metadata"]`, and the licence notice (and, on the
free tier, a note that only the latest fiscal year was returned) in
`warnings`.

Available tags include `revenue`, `net_income`, `assets`, `liabilities`,
`equity`, `cash`, `gross_profit`, `operating_income`, `long_term_debt`,
`rnd_expense`, `eps_diluted`, `shares_diluted`, plus derived ratios
`net_margin`, `gross_margin`, `operating_margin`, `roe`, `roa`,
`debt_to_equity`, `asset_turnover`.

## Data notes

- **Taiwan income-statement figures are single-quarter (three-month)
  amounts.** Taiwan files cumulative year-to-date totals (Q2 = H1, Q4 = full
  year); they are converted by subtracting the earlier quarters of the same
  year, so do not difference adjacent quarters again. Balance-sheet items are
  period-end balances as usual.
- Values are as filed. Filers make mistakes; we do not silently correct them.

## Sources and licences

- **US** — SEC EDGAR, public information.
- **Taiwan** — Taiwan Stock Exchange, two routes: the TWSE OpenAPI for current
  quarters, under the Open Government Data License v1.0 (attribution required),
  and the MOPS XBRL archive for history from 2013, which is not open data and
  is supplied on the basis in Source Conditions Schedule clause 3.6(b). Both
  notices are embedded in every Taiwan response and must be preserved.
- **Korea** — FSS OpenDART. Public data (공공데이터) whose permitted use is not
  restricted (data.go.kr 15060626); the FSS confirmed in writing that no
  separate approval agreement is required for commercial use.
- **Japan** — Financial Services Agency, EDINET, under the EDINET terms of use
  applying the Public Data License 1.0. Source attribution is required; it is
  embedded in every API response and must be preserved.
- **France** — INPI, Registre national des entreprises, under its reuse
  licence. Attribution with the last-update date is required.
- **Belgium** — National Bank of Belgium, Central Balance Sheet Office.
  Statutory solo accounts, not group consolidation.
- **Denmark** — Danish Business Authority (Erhvervsstyrelsen), published annual
  reports. `filed` is the Copenhagen calendar date of publication. Known issue,
  being corrected: Danish dates up to 10 April 2015, and some later ones, are
  one day early. A Danish-GAAP group parent's figures are usually its own, not
  the group's; IFRS filers' figures are the consolidated group's.
- **New Zealand** — Charities Services, Department of Internal Affairs,
  Charities Register, CC BY 3.0 NZ. `filed` is the register's record date;
  known issue, being corrected: about a quarter of those dates are one day
  early. Registered charities rather than listed
  issuers: NZ company financials are not published as open data.

Factual historical data only — not investment advice, not a recommendation.

Full API documentation: <https://www.tradingagentapp.com/developers>
Pricing: <https://www.tradingagentapp.com/fundamentals> · Licence documents:
<https://www.tradingagentapp.com/licences>

MIT licensed. Operated by WU Capital Limited, Auckland, New Zealand.

