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

# ---------- 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)

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

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

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.