Market Predictions API

Retrieve AI-powered price predictions for all tickers in a specific market. Use this endpoint to screen an entire market for trading signals.

Endpoint

GET /v1/market/{market}/predictions/{type}

Authentication

Requires API key via token query parameter.

Parameters

Path Parameters

Parameter	Type	Required	Description
`market`	string	Yes	Market identifier (e.g., `S&P 500`, `NASDAQ`)
`type`	string	Yes	Prediction type: `daily` or `monthly`

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	Your API key
`dateFrom`	string	No	Start date (YYYY-MM-DD)
`dateTo`	string	No	End date (YYYY-MM-DD)

Request

# Get daily predictions for S&P 500
curl "https://api.finbrain.tech/v1/market/S%26P%20500/predictions/daily?token=YOUR_API_KEY"

# Get monthly predictions for NASDAQ
curl "https://api.finbrain.tech/v1/market/NASDAQ/predictions/monthly?token=YOUR_API_KEY"

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_API_KEY")

# Get market predictions as DataFrame (recommended)
df = fb.predictions.market("S&P 500", prediction_type="daily", as_dataframe=True)
print(df.head())
#         expectedShort  expectedMid  expectedLong  sentimentScore
# ticker
# AAPL            0.22         0.58          0.25           0.186
# MSFT            1.15         1.82          2.10           0.342

# Filter for bullish tickers
bullish = df[df["expectedLong"] > 2.0]
print(f"Bullish tickers: {bullish.index.tolist()}")

# Get raw JSON response
predictions = fb.predictions.market("S&P 500", prediction_type="daily")
for pred in predictions:
    print(f"{pred['ticker']}: {pred['prediction']['expectedLong']}%")

#include <iostream>
#include <string>
#include <curl/curl.h>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

size_t WriteCallback(void* contents, size_t size, size_t nmemb, std::string* userp) {
    userp->append((char*)contents, size * nmemb);
    return size * nmemb;
}

json get_market_predictions(const std::string& market, const std::string& type,
                            const std::string& api_key) {
    CURL* curl = curl_easy_init();
    std::string response;

    if (curl) {
        char* encoded_market = curl_easy_escape(curl, market.c_str(), 0);
        std::string url = "https://api.finbrain.tech/v1/market/" +
                          std::string(encoded_market) + "/predictions/" + type +
                          "?token=" + api_key;
        curl_free(encoded_market);

        curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);
        curl_easy_perform(curl);
        curl_easy_cleanup(curl);
    }

    return json::parse(response);
}

int main() {
    auto data = get_market_predictions("S&P 500", "daily", "YOUR_API_KEY");

    for (auto& item : data) {
        std::cout << item["ticker"].get<std::string>() << ": "
                  << item["prediction"]["expectedLong"].get<std::string>() << "%"
                  << std::endl;
    }

    return 0;
}

use reqwest::blocking::Client;
use serde::Deserialize;
use std::error::Error;

#[derive(Debug, Deserialize)]
struct Prediction {
    #[serde(rename = "expectedShort")]
    expected_short: String,
    #[serde(rename = "expectedMid")]
    expected_mid: String,
    #[serde(rename = "expectedLong")]
    expected_long: String,
    #[serde(rename = "lastUpdate")]
    last_update: String,
    #[serde(rename = "type")]
    pred_type: String,
}

#[derive(Debug, Deserialize)]
struct MarketPrediction {
    ticker: String,
    name: String,
    prediction: Prediction,
    #[serde(rename = "sentimentScore")]
    sentiment_score: String,
}

fn get_market_predictions(market: &str, pred_type: &str, api_key: &str)
    -> Result<Vec<MarketPrediction>, Box<dyn Error>> {
    let url = format!(
        "https://api.finbrain.tech/v1/market/{}/predictions/{}?token={}",
        urlencoding::encode(market), pred_type, api_key
    );

    let client = Client::new();
    let response: Vec<MarketPrediction> = client.get(&url).send()?.json()?;

    Ok(response)
}

fn main() -> Result<(), Box<dyn Error>> {
    let data = get_market_predictions("S&P 500", "daily", "YOUR_API_KEY")?;

    for item in &data {
        println!("{}: {}%", item.ticker, item.prediction.expected_long);
    }

    Ok(())
}

import requests
from urllib.parse import quote

market = "S&P 500"
response = requests.get(
    f"https://api.finbrain.tech/v1/market/{quote(market)}/predictions/daily",
    params={"token": "YOUR_API_KEY"}
)
predictions = response.json()

const market = encodeURIComponent("S&P 500");

const response = await fetch(
  `https://api.finbrain.tech/v1/market/${market}/predictions/daily?token=YOUR_API_KEY`
);
const predictions = await response.json();

Response

Success Response (200 OK)

[
  {
    "ticker": "STX",
    "name": "Seagate Technology",
    "prediction": {
      "expectedShort": "1.24632",
      "expectedMid": "1.34583",
      "expectedLong": "0.07213",
      "lastUpdate": "2020-10-27T23:46:54.359Z",
      "type": "daily"
    },
    "sentimentScore": "-0.137"
  },
  {
    "ticker": "TAP",
    "name": "Molson Coors Brewing Company",
    "prediction": {
      "expectedShort": "0.14241",
      "expectedMid": "1.19539",
      "expectedLong": "1.34984",
      "lastUpdate": "2020-10-27T23:46:54.415Z",
      "type": "daily"
    },
    "sentimentScore": "0.261"
  }
  // ... more tickers
]

Response Fields

The response is an array of prediction objects with the following fields:

Field	Type	Description
`ticker`	string	Ticker symbol
`name`	string	Company name
`prediction`	object	Prediction data object
`sentimentScore`	string	Current sentiment score for the ticker

Prediction Object Fields

Field	Type	Description
`expectedShort`	string	Expected price change % (short-term, ~3 days)
`expectedMid`	string	Expected price change % (mid-term, ~5 days)
`expectedLong`	string	Expected price change % (long-term, ~10 days)
`lastUpdate`	string	Timestamp of last prediction update (ISO 8601)
`type`	string	Prediction type (`daily` or `monthly`)

Usage Examples

Screen for Bullish Signals

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_API_KEY")

# Get all S&P 500 predictions
predictions = fb.predictions.market("S&P 500", prediction_type="daily")

# Filter for strongly bullish predictions (expectedLong > 2%)
bullish = []
for pred in predictions:
    expected_long = float(pred["prediction"]["expectedLong"])
    if expected_long > 2.0:
        bullish.append({
            "ticker": pred["ticker"],
            "name": pred["name"],
            "expected_long": expected_long,
            "sentiment": float(pred["sentimentScore"])
        })

# Sort by expected return
bullish = sorted(bullish, key=lambda x: x["expected_long"], reverse=True)

print("Top Bullish Signals (10-day expected return > 2%):")
for b in bullish[:10]:
    print(f"  {b['ticker']}: {b['expected_long']:.2f}% expected, sentiment: {b['sentiment']:.3f}")

Market Sentiment Summary

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_API_KEY")

def market_sentiment_summary(market):
    """Calculate overall market sentiment from predictions"""
    predictions = fb.predictions.market(market, prediction_type="daily")

    bullish = 0
    bearish = 0
    neutral = 0

    for pred in predictions:
        expected_long = float(pred["prediction"]["expectedLong"])
        if expected_long > 1.0:
            bullish += 1
        elif expected_long < -1.0:
            bearish += 1
        else:
            neutral += 1

    total = len(predictions)
    return {
        "market": market,
        "total_tickers": total,
        "bullish": bullish,
        "bearish": bearish,
        "neutral": neutral,
        "bullish_pct": bullish / total * 100 if total > 0 else 0
    }

summary = market_sentiment_summary("S&P 500")
print(f"Market: {summary['market']}")
print(f"Bullish: {summary['bullish']} ({summary['bullish_pct']:.1f}%)")
print(f"Bearish: {summary['bearish']}")
print(f"Neutral: {summary['neutral']}")

Compare Markets

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_API_KEY")

markets = ["S&P 500", "NASDAQ"]

for market in markets:
    predictions = fb.predictions.market(market, prediction_type="daily")

    bullish_count = 0
    for pred in predictions:
        expected_long = float(pred["prediction"]["expectedLong"])
        if expected_long > 1.0:
            bullish_count += 1

    total = len(predictions)
    print(f"{market}: {bullish_count}/{total} bullish ({bullish_count/total*100:.1f}%)")

Errors

Code	Error	Description
400	Bad Request	Invalid market or prediction type
401	Unauthorized	Invalid or missing API key
404	Not Found	Market not found
500	Internal Server Error	Server-side error

Ticker Predictions - Get predictions for a single ticker
Available Markets - List available markets
Available Tickers - List available tickers