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)

# One row per app per date instead of one blended row per date
# — see "App ratings: the per-app view" below.
fb.app_ratings.ticker("AMZN",
                      date_from="2025-01-01",
                      date_to="2025-06-30",
                      as_dataframe=True,
                      per_app=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 nullable. Historical rows were backfilled in place by the pipeline's reconcile upload, so nulls are rare — but code should still handle them. 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=[...]). All four fields — owner, amountRaw, amountFlag and disclosureDate — are also present on fb.screener.congress_house() and fb.screener.congress_senate() rows.

Company identifier (cik)

Rows from the four SEC/government datasets — fb.insider_transactions, fb.government_contracts, fb.corporate_lobbying, and fb.patent_filings (ticker endpoints and their async equivalents) — carry cik, the SEC Central Index Key of the company as of that record:

cik is a string, not a number — the leading zeros are part of the identifier, so keep the column as text when loading into other tools. Rows without an entity resolution (for example, records of companies absent from the SEC's public company file) carry null; with as_dataframe=True the column stays object-typed and missing values read as None. Use it to join FinBrain rows to SEC-keyed datasets (EDGAR filings, financial statements, 13F holdings) or to your own security master.

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
]

App ratings: the per-app view (per_app=True)

A company can publish many apps — Apple has 140 on iOS. The default frame reports one row per date, carrying the company's biggest app on each store, so a portfolio collapses to two numbers. per_app=True returns the granular alternative: one row per app per observation, with no blending and no derived company score, so you decide which apps matter and how to weight them.

apps = fb.app_ratings.ticker(
    "AMZN",
    date_from="2025-01-01",
    date_to="2025-06-30",
    as_dataframe=True,
    per_app=True,
)

apps.columns
# ['date', 'platform', 'app_id', 'app_name',
#  'score', 'ratings_count', 'install_count']

# Which apps exist, and how big each is
apps.groupby(["platform", "app_id", "app_name"])["ratings_count"].max()

# One app's own series
apps[apps["app_id"] == "com.amazon.mShop.android.shopping"]

Three things to know:

• Not indexed by date. A single date carries one row per app, so a date index would not be unique. The blended frame (per_app=False, the default) is still indexed by date and is unchanged.
• app_id is null on older observations, collected before the API keyed rows per app. Those rows carry the platform but not the app identity — we know the store, not which app produced the number. Filter them with apps["app_id"].notna() if you need identified apps only.
• Purely additive. per_app=False behaviour is untouched, and an API that predates the per-app view returns an empty frame rather than an error.

⚡ 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")

# Chart one specific app rather than the company's biggest on that store.
# Ids come from the per_app frame; the app must live on the store you pass.
fb.plot.app_ratings("AMZN",
                    store="play",
                    app_id="com.amazon.mShop.android.shopping",
                    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.