API Authentication

All FinBrain API requests require authentication using your API key. This guide explains how to obtain and use your API key.

Getting Your API Key

1. Visit finbrain.tech and create an account
2. Navigate to your account dashboard
3. Copy your API key from the API section

Your API key is a unique string that identifies your account and tracks your usage.

Using Your API Key

The FinBrain v2 API supports multiple authentication methods. Choose the one that best fits your use case:

Bearer Token (Recommended)

Authorization: Bearer YOUR_API_KEY

X-API-Key Header

X-API-Key: YOUR_API_KEY

Query Parameter

?apiKey=YOUR_API_KEY

Legacy Query Parameter

?token=YOUR_API_KEY

Example Requests

Python SDK

from finbrain import FinBrainClient

# Initialize with your API key
fb = FinBrainClient(api_key="YOUR_API_KEY")

# All subsequent calls use Bearer token auth automatically
predictions = fb.predictions.ticker("AAPL", as_dataframe=True)
sentiment = fb.sentiments.ticker("AAPL", as_dataframe=True)

Python (requests)

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.finbrain.tech/v2"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Get daily predictions for Apple
response = requests.get(
    f"{BASE_URL}/predictions/daily/AAPL",
    headers=headers
)
data = response.json()
print(data)

JavaScript

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.finbrain.tech/v2";

async function getPredictions(ticker) {
  const response = await fetch(
    `${BASE_URL}/predictions/daily/${ticker}`,
    {
      headers: { "Authorization": `Bearer ${API_KEY}` }
    }
  );
  return response.json();
}

const data = await getPredictions("AAPL");
console.log(data);

cURL

# Get predictions for Apple
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.finbrain.tech/v2/predictions/daily/AAPL"

# Get sentiment data
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.finbrain.tech/v2/sentiment/AAPL"

# Get insider transactions
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.finbrain.tech/v2/insider-trading/AAPL"

API Key Security

Follow these best practices to keep your API key secure:

Do

• Store your API key in environment variables
• Use secrets management in production (AWS Secrets Manager, HashiCorp Vault, etc.)
• Rotate your key periodically
• Use different keys for development and production

Don’t

• Commit your API key to version control
• Share your API key publicly
• Include your API key in client-side code
• Log requests that contain your API key

Environment Variables Example

Python SDK

import os
from finbrain import FinBrainClient

# Reads from FINBRAIN_API_KEY env var automatically
fb = FinBrainClient()

Python

import os
import requests

# Load from environment variable
api_key = os.environ.get("FINBRAIN_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}

response = requests.get(
    "https://api.finbrain.tech/v2/predictions/daily/AAPL",
    headers=headers
)

JavaScript

const API_KEY = process.env.FINBRAIN_API_KEY;

const response = await fetch(
  "https://api.finbrain.tech/v2/predictions/daily/AAPL",
  {
    headers: { "Authorization": `Bearer ${API_KEY}` }
  }
);

Bash

# Set environment variable
export FINBRAIN_API_KEY="your_api_key_here"

# Use in requests
curl -H "Authorization: Bearer $FINBRAIN_API_KEY" \
  "https://api.finbrain.tech/v2/predictions/daily/AAPL"

Authentication Errors

If authentication fails, you’ll receive one of these error responses:

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Causes:

• Missing API key
• Invalid API key
• Expired API key

Solution: Verify your API key is correct and included in the request.

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied for this resource"
  }
}

Causes:

• Your subscription doesn’t include this endpoint
• Account suspended
• Rate limit exceeded

Solution: Check your subscription tier or contact support.

Rate Limits

API rate limits depend on your subscription plan:

Plan	Rate Limit
Terminal + API + MCP	2,000 requests/hour
Enterprise	Custom, sized to your throughput requirements

When you exceed your rate limit, you’ll receive a 429 Too Many Requests response.

Every API response includes rate limit headers so you can track your usage:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the rate limit window resets

Next Steps

• Quick Start - Make your first API call
• API Reference - Complete endpoint documentation
• Error Codes - All error responses explained