FinBrain Python SDK 

Official Python client for the FinBrain API v2. Fetch deep-learning price predictions, sentiment scores, insider trades, LinkedIn metrics, options data, news and more — with a single import.

Python ≥ 3.9 • requests, pandas, numpy & plotly • asyncio optional.

✨ Features

• One-line auth (FinBrainClient(api_key="…")) with Bearer token
• Complete v2 endpoint coverage (predictions, sentiments, options, insider, news, screener, etc.)
• Transparent retries & custom error hierarchy (FinBrainError)
• Response envelope auto-unwrapping (v2 {success, data, meta} format)
• Async parity with finbrain.aio (httpx)
• Auto-version from Git tags (setuptools-scm)
• MIT-licensed, fully unit-tested

🚀 Quick start

Install the SDK:

pip install finbrain-python

Create a client and fetch data:

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_KEY")        # create once, reuse below

# ---------- discovery ----------
fb.available.markets()                         # list markets with regions
fb.available.tickers("daily", as_dataframe=True)
fb.available.regions()                         # markets grouped by region

# ---------- app ratings ----------
fb.app_ratings.ticker("AMZN",
                      date_from="2025-01-01",
                      date_to="2025-06-30",
                      as_dataframe=True)

# ---------- analyst ratings ----------
fb.analyst_ratings.ticker("AMZN",
                          date_from="2025-01-01",
                          date_to="2025-06-30",
                          as_dataframe=True)

# ---------- house trades ----------
# Rows include `disclosureDate`, `owner`, `amountRaw` and `amountFlag`
# alongside the transaction `date` — see "Congressional trade fields" below.
fb.house_trades.ticker("AMZN",
                       date_from="2025-01-01",
                       date_to="2025-06-30",
                       as_dataframe=True)

# ---------- senate trades ----------
fb.senate_trades.ticker("META",
                        date_from="2025-01-01",
                        date_to="2025-06-30",
                        as_dataframe=True)

# ---------- corporate lobbying ----------
fb.corporate_lobbying.ticker("AAPL",
                             date_from="2024-01-01",
                             date_to="2025-06-30",
                             as_dataframe=True)

# ---------- reddit mentions ----------
fb.reddit_mentions.ticker("TSLA",
                          date_from="2026-03-01",
                          date_to="2026-03-17",
                          as_dataframe=True)

# ---------- government contracts ----------
fb.government_contracts.ticker("LMT",
                               date_from="2025-01-01",
                               date_to="2025-12-31",
                               limit=50,
                               as_dataframe=True)

# ---------- patent filings ----------
fb.patent_filings.ticker("AAPL",
                         date_from="2025-01-01",
                         date_to="2025-12-31",
                         limit=50,
                         as_dataframe=True)

# ---------- insider transactions ----------
fb.insider_transactions.ticker("AMZN", as_dataframe=True)

# ---------- LinkedIn metrics ----------
fb.linkedin_data.ticker("AMZN",
                        date_from="2025-01-01",
                        date_to="2025-06-30",
                        as_dataframe=True)

# ---------- options put/call ----------
fb.options.put_call("AMZN",
                    date_from="2025-01-01",
                    date_to="2025-06-30",
                    as_dataframe=True)

# ---------- price predictions ----------
fb.predictions.ticker("AMZN", as_dataframe=True)

# ---------- news sentiment ----------
fb.sentiments.ticker("AMZN",
                     date_from="2025-01-01",
                     date_to="2025-06-30",
                     as_dataframe=True)

# ---------- news articles ----------
fb.news.ticker("AMZN", limit=20, as_dataframe=True)

# ---------- screener (cross-ticker) ----------
fb.screener.sentiment(market="S&P 500", as_dataframe=True)
fb.screener.predictions_daily(limit=100, as_dataframe=True)
fb.screener.insider_trading(limit=50)
fb.screener.reddit_mentions(limit=100, as_dataframe=True)
fb.screener.government_contracts(limit=100, as_dataframe=True)
fb.screener.patent_filings(limit=100, as_dataframe=True)
fb.screener.congress_house(limit=50)     # rows carry `disclosureDate` and `owner`
fb.screener.congress_senate(limit=50)

# ---------- recent data ----------
fb.recent.news(limit=100, as_dataframe=True)
fb.recent.analyst_ratings(limit=50)

Congressional trade fields

House and Senate trade rows carry two dates, and the gap between them is the reporting lag — often weeks:

Rows also identify whose account traded and how the filed amount was normalized:

amount is normalized to the ten statutory STOCK Act brackets (e.g. "$1,001 - $15,000") whenever the filed string is an unambiguous formatting variant of one; open-ended filing categories like "Over $1,000,000" are kept as filed. A filing with no usable amount at all reports amount as "Unknown" with amountFlag = review. Senate filings that leave the owner column blank report owner as UNKNOWN; House filings that leave it blank report SELF, per the House PTR-form instructions.

disclosureDate and owner are null on historical rows collected before the fields were captured upstream. With as_dataframe=True, date is the index and the other fields are columns whose missing values read as None or NaN depending on your pandas version — test them with pandas.isna() rather than is None. Note that .dropna() on such a frame will discard every row with any missing field — use .dropna(subset=[...]). disclosureDate and owner are also present on fb.screener.congress_house() and fb.screener.congress_senate() rows.

date_from / date_to bound the transaction date, not the disclosure date — a trade executed inside the window is returned even if it was disclosed after date_to.

trades = fb.house_trades.ticker("AMZN")["trades"]
lag_days = [
    (pd.Timestamp(t["disclosureDate"]) - pd.Timestamp(t["date"])).days
    for t in trades
    if t["disclosureDate"]
]

# Only the member's own trades, skipping flagged amounts
own = [
    t for t in trades
    if t["owner"] == "SELF" and t["amountFlag"] is None
]

⚡ Async Usage

For async/await support, install with the async extra:

pip install finbrain-python[async]

Then use AsyncFinBrainClient with httpx:

import asyncio
from finbrain.aio import AsyncFinBrainClient

async def main():
    async with AsyncFinBrainClient(api_key="YOUR_KEY") as fb:
        # All methods are async and return the same data structures
        markets = await fb.available.markets()

        # Fetch predictions
        predictions = await fb.predictions.ticker("AMZN", as_dataframe=True)

        # Fetch sentiment data
        sentiment = await fb.sentiments.ticker(
            "AMZN",
            date_from="2025-01-01",
            date_to="2025-06-30",
            as_dataframe=True
        )

        # All other endpoints work the same way
        app_ratings = await fb.app_ratings.ticker("AMZN", as_dataframe=True)
        analyst_ratings = await fb.analyst_ratings.ticker("AMZN", as_dataframe=True)
        news = await fb.news.ticker("AMZN", limit=10)
        screener = await fb.screener.sentiment(market="S&P 500")

asyncio.run(main())

Note: The async client uses httpx.AsyncClient and must be used with async with context manager for proper resource cleanup.

📈 Plotting

Plot helpers in a nutshell

• show – defaults to True, so the chart appears immediately.

• as_json=True – skips display and returns the figure as a Plotly-JSON string, ready to embed elsewhere.

# ---------- App Ratings Chart - Apple App Store or Google Play Store ----------
fb.plot.app_ratings("AMZN",
                    store="app",                # "play" for Google Play Store
                    date_from="2025-01-01",
                    date_to="2025-06-30")

# ---------- LinkedIn Metrics Chart ----------
fb.plot.linkedin("AMZN",
                 date_from="2025-01-01",
                 date_to="2025-06-30")

# ---------- Put-Call Ratio Chart ----------
fb.plot.options("AMZN",
                kind="put_call",
                date_from="2025-01-01",
                date_to="2025-06-30")

# ---------- Predictions Chart ----------
fb.plot.predictions("AMZN")         # prediction_type="monthly" for monthly predictions

# ---------- Sentiments Chart ----------
fb.plot.sentiments("AMZN",
                   date_from="2025-01-01",
                   date_to="2025-06-30")

# ---------- Insider Transactions, House & Senate Trades, Corporate Lobbying (requires user price data) ----------
# These plots overlay transaction markers on a price chart.
# Since FinBrain doesn't provide historical prices, you must provide your own:

import pandas as pd

# Example: Load your price data from any legal source
# (broker API, licensed data provider, CSV file, etc.)
price_df = pd.DataFrame({
    "close": [150.25, 151.30, 149.80],  # Your price data
    "date": pd.date_range("2025-01-01", periods=3)
}).set_index("date")

# Plot insider transactions on your price chart
fb.plot.insider_transactions("AAPL", price_data=price_df)

# Plot House member trades on your price chart
fb.plot.house_trades("NVDA",
                     price_data=price_df,
                     date_from="2025-01-01",
                     date_to="2025-06-30")

# Plot Senate member trades on your price chart
fb.plot.senate_trades("META",
                      price_data=price_df,
                      date_from="2025-01-01",
                      date_to="2025-06-30")

# Plot corporate lobbying spend on your price chart
fb.plot.corporate_lobbying("AAPL",
                           price_data=price_df,
                           date_from="2024-01-01",
                           date_to="2025-06-30")

# Plot Reddit mentions (stacked bars per subreddit) on your price chart
fb.plot.reddit_mentions("TSLA",
                        price_data=price_df,
                        date_from="2026-03-01",
                        date_to="2026-03-17")

# Plot patent grants (bars sized by claim count) on your price chart
fb.plot.patent_filings("AAPL",
                       price_data=price_df,
                       date_from="2024-01-01",
                       date_to="2025-06-30")

# Plot analyst ratings & price targets (markers coloured by action) on your price chart
fb.plot.analyst_ratings("AAPL",
                        price_data=price_df,
                        date_from="2024-01-01",
                        date_to="2025-06-30")

# ---------- Reddit Mentions Screener Chart (no price data needed) ----------
# Stacked horizontal bar chart of top 15 most mentioned tickers
fb.plot.reddit_mentions_top(market="S&P 500")

# Customize the number of tickers shown
fb.plot.reddit_mentions_top(top_n=10, region="US")

Price Data Requirements:

• DataFrame with DatetimeIndex
• Must contain a price column: close, Close, price, Price, adj_close, or Adj Close
• Obtain from legal sources: broker API, Bloomberg, Alpha Vantage, FMP, etc.

🔑 Authentication

To call the API you need an API key, obtained by purchasing a FinBrain API subscription. (The Terminal-only subscription does not include an API key.)

1. Subscribe at https://www.finbrain.tech → FinBrain API.
2. Copy the key from your dashboard.
3. Pass it once when you create the client:

from finbrain import FinBrainClient
fb = FinBrainClient(api_key="YOUR_KEY")

Or set the FINBRAIN_API_KEY environment variable and omit the argument:

fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var

📚 Supported endpoints

🛠️ Error-handling

from finbrain.exceptions import BadRequest
try:
    fb.predictions.ticker("MSFT", prediction_type="weekly")
except BadRequest as exc:
    print("Invalid parameters:", exc)
    print("Error code:", exc.error_code)        # e.g. "VALIDATION_ERROR"
    print("Details:", exc.error_details)         # structured details dict

🔄 Versioning & release

• Semantic Versioning (MAJOR.MINOR.PATCH)

• Version auto-generated from Git tags (setuptools-scm)

git tag -a v0.2.0 -m "v2 API migration"
git push --tags # GitHub Actions builds & uploads to PyPI

🧑‍💻 Development

git clone https://github.com/finbrain-tech/finbrain-python
cd finbrain-python
python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]

ruff check . # lint / format
pytest -q # unit tests (mocked)

🤝 Contributing

1. Fork → create a feature branch

2. Add tests & run ruff check --fix

3. Ensure pytest & CI pass

4. Open a PR — thanks!

🔒 Security

Please report vulnerabilities to info@finbrain.tech. We respond within 48 hours.

📜 License

MIT — see LICENSE.

© 2026 FinBrain Technologies — Built with ❤️ for the quant community.