Metadata-Version: 2.4
Name: openbb-filingpulse
Version: 0.1.0
Summary: FilingPulse provider extension for the OpenBB Platform - SEC EDGAR Form 4 insider transactions as normalized data
Author-email: FilingPulse <keys@filingpulse.io>
License: MIT
Project-URL: Homepage, https://filingpulse.io
Project-URL: Documentation, https://filingpulse.io/docs.html
Keywords: openbb,sec,edgar,form 4,insider trading,filings
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openbb-core<2,>=1.4

# openbb-filingpulse

[FilingPulse](https://filingpulse.io) provider extension for the
[OpenBB Platform](https://docs.openbb.co/): SEC EDGAR Form 4 insider
transactions as normalized data.

FilingPulse is data infrastructure — filings as filed with EDGAR, normalized
into one stable JSON schema. It does not interpret filings, and nothing here
is investment advice.

## Install

```bash
pip install openbb-filingpulse
```

The OpenBB Platform discovers the provider automatically. If you use the
Python interface, rebuild it once after installing:

```python
import openbb
openbb.build()
```

## Credentials

Get a free API key (no card required) at
[filingpulse.io/signup.html](https://filingpulse.io/signup.html), then:

```python
from openbb import obb
obb.user.credentials.filingpulse_api_key = "fp_..."
```

or add `"filingpulse_api_key": "fp_..."` to `~/.openbb_platform/user_settings.json`.

## Usage

```python
from openbb import obb

# Latest insider transactions for a symbol
result = obb.equity.ownership.insider_trading(
    symbol="AAPL", provider="filingpulse", limit=100
)
df = result.to_df()

# A fixed, reproducible window (maps to the API's since=/until= filters)
result = obb.equity.ownership.insider_trading(
    symbol="KMI",
    provider="filingpulse",
    start_date="2026-07-01",
    end_date="2026-07-31",
)

# Amendments only
result = obb.equity.ownership.insider_trading(
    symbol="CIB", provider="filingpulse", form_type="4/A"
)
```

## Data notes

- **One row per transaction leg** — a filing's Table I (non-derivative) and
  Table II (derivative) legs each become a row; `is_derivative` tells them
  apart and `accession` groups the legs of one filing. Holdings-only filings
  report no transactions and yield no rows.
- **`limit` counts rows (legs), not filings.** The fetcher pages the API until
  it has enough.
- **Numbers are coerced from as-filed strings.** EDGAR accepts malformed
  values; anything that does not parse is `None`, never a guess. For the exact
  as-filed strings, use the [REST API](https://filingpulse.io/docs.html)
  directly.
- **Multi-owner filings** (common for funds) show the first reporting owner;
  `additional_owners` carries how many more are on the filing.
- `filing_date` is the date EDGAR accepted the filing; `transaction_date` is
  per leg, as filed.

## Rate limits

The free tier serves 2,500 requests/month at 10 req/min. One fetcher call
uses one API request per 200 filings paged. Paid tiers at
[filingpulse.io/#pricing](https://filingpulse.io/#pricing).

## Links

- Docs: https://filingpulse.io/docs.html
- Dataset status: https://filingpulse.io (live counts)
- Support: keys@filingpulse.io
