Metadata-Version: 2.4
Name: bourse-quant
Version: 1.0.0
Summary: Official Python package for the Bourse API: Congress and insider trades with the Conviction Score, 13F, lobbying, contracts, stress tests and Parquet bulk history as pandas DataFrames.
Author-email: Bourse <contact@bourse.pl>
License-Expression: MIT
Project-URL: Homepage, https://www.bourse.pl/api/
Project-URL: Documentation, https://docs.bourse.pl
Project-URL: OpenAPI spec, https://api.bourse.pl/v1/openapi.json
Project-URL: Status, https://status.bourse.pl
Keywords: insider trading,congress trading,stock act,sec form 4,13f,alternative data,quant,pandas,parquet,finance api
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Framework :: AsyncIO
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Requires-Dist: pandas>=1.3
Provides-Extra: parquet
Requires-Dist: pyarrow>=12; extra == "parquet"
Dynamic: license-file

# bourse-quant

The official Python package for the [Bourse API](https://www.bourse.pl/api/): stock trades of members of Congress, the President and the Cabinet, SEC Form 4 insider trades scored by the Bourse Conviction Score, 13F holdings, lobbying, federal contracts, the Coincidence Tracker, portfolio stress tests and full-history bulk files, returned as pandas DataFrames.

```bash
pip install bourse-quant            # add [parquet] to read Parquet bulk files
export BOURSE_KEY=bk_...            # free key: Bourse app -> Settings -> API key
```

```python
import bourse

df = bourse.get_insider_trades("NVDA")                 # SEC Form 4, every page
buys = bourse.get_insider_trades(code="P", since="2026-10-01")
top = bourse.get_conviction(min_score=90)              # Conviction Score 0-100 with reasons
congress = bourse.get_congress_trades(ticker="LMT", since="2025-01-01")
hits = bourse.get_coincidences(committee_match=True)   # Congress trades next to federal contracts
ideas = bourse.insights()                              # strategies with historical return and drawdown risk
ids = bourse.symbology(ticker="AAPL")                  # CIK, CUSIP, ISIN, FIGI
risk = bourse.stress_test({"AAPL": 40, "MSFT": 30, "TLT": 30})   # API Pro / Enterprise / pay-as-you-go
risk["historical_scenarios_df"]
```

Any dataset works the same way:

```python
bourse.get_dataset("warn-layoffs", state="TX", since="2026-01-01")
bourse.list_datasets().keys()
```

## What you get in every row

- `filed_at_source_timestamp`: when the SEC, the House, the Senate or another source published the filing (null when the source gives no time).
- `processed_by_bourse_timestamp`: when Bourse stored the record. Use both to avoid look-ahead bias in backtests.
- `cik`, `cusip`, `isin`, `figi` on every row with a ticker.

Date and timestamp columns are parsed to timezone-aware pandas datetimes.

## Reliability

The client pages through results (1,000 rows per request), retries on HTTP 429 with back-off, retries on 5xx and network errors, and raises `bourse.BourseError(status, code, message)` otherwise. `client().remaining_today`, `client().plan` and `client().data_delay` mirror the response headers. API responses are never served from a cache.

## Async

```python
import asyncio, bourse

async def main():
    async with bourse.AsyncClient(concurrency=4) as b:
        frames = await b.gather(b.insider_trades, ["NVDA", "AAPL", "MSFT"])

asyncio.run(main())
```

## Bulk history (backtesting)

```python
paths = bourse.download_bulk("congress", format="csv.gz")          # API Pro
df = bourse.download_bulk("insiders", format="parquet", read=True)  # Enterprise: Parquet from Amazon S3
```

Files are refreshed every night. Links are pre-signed and valid for one hour.

## Webhooks

```python
ok = bourse.verify_webhook(secret, request.headers["Bourse-Signature"], request.get_data())
```

## Plans

- Free key: 1,000 requests a day, event data delayed 48 hours, personal use.
- Pay-as-you-go: $1 per 1,000 requests, live data, commercial license.
- API Pro: $499 a month, 250,000 requests a day, nightly CSV/NDJSON files, stress-test API.
- Enterprise: $1,000 a month, Parquet history on Amazon S3, 99.9% uptime SLA.

Reference: https://docs.bourse.pl · Status: https://status.bourse.pl · Terms: https://www.bourse.pl/legal/api/

Data comes from public filings. It is not investment advice. The code is MIT licensed.
